用户注册时,如果用户名已经被占用,Service 可以直接抛出 UsernameAlreadyExistsException。问题是,前端怎么才能收到 HTTP 409 和一句「用户名已被占用」?
一种写法是在 Controller 里加 try-catch。注册接口写一遍,修改用户名的接口再写一遍。等到提示文案或错误码需要调整,就要去多个地方找相同的代码。
Spring MVC 提供了更集中的写法:Service 在发现业务问题时抛出异常,全局异常处理器负责把异常转换成 HTTP 状态和 JSON 响应。 本文用一个可以实际发请求验证的注册接口,把这个过程走一遍。
一、先定好接口遇到错误时返回什么
注册接口是 POST /users。客户端提交一个用户名:
{
"username": "xiaoming"
}
假设这个用户名已经注册过,服务端返回 HTTP 409 Conflict,响应体如下:
{
"code": "USERNAME_ALREADY_EXISTS",
"message": "用户名已被占用"
}
前端可以根据 code 把错误提示显示在用户名输入框旁边。以后把文案改成「这个名字已经有人用了」,判断逻辑也能继续使用。
本文约定三种错误:
| 场景 | HTTP 状态 | 业务错误码 | 谁发现问题 |
|---|---|---|---|
| 用户名为空或全是空格 | 400 | INVALID_ARGUMENT | Spring MVC 参数校验 |
| 用户名已经被占用 | 409 | USERNAME_ALREADY_EXISTS | 注册服务 |
| 服务端出现未预期异常 | 500 | INTERNAL_ERROR | 全局处理器兜底 |
二、写一个能触发异常的注册接口
示例使用 Java 17、Spring Boot 3.5 和 Spring MVC。项目需要 spring-boot-starter-web 和 spring-boot-starter-validation 两个依赖。以下类放在启动类所在包或其子包中,每个 public 类型单独一个文件。
先定义注册请求:
import jakarta.validation.constraints.NotBlank;
public record RegisterRequest(
@NotBlank(message = "用户名不能为空")
String username
) {}
再定义一个业务异常。异常类名本身就表达了失败原因:
public class UsernameAlreadyExistsException extends RuntimeException {
public UsernameAlreadyExistsException() {
super("用户名已被占用");
}
}
注册服务用一个内存集合保存用户名,启动项目就能测试。`Set.add()` 会告诉我们这次添加是否成功,两个请求同时注册相同用户名时,并发集合也只会接受一次。
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import org.springframework.stereotype.Service;
@Service
public class RegistrationService {
private final Set<String> usernames = ConcurrentHashMap.newKeySet();
public void register(String username) {
if (!usernames.add(username.strip())) {
throw new UsernameAlreadyExistsException();
}
}
}
最后写 Controller。注册成功返回 201 Created:
import jakarta.validation.Valid;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/users")
public class UserController {
private final RegistrationService registrationService;
public UserController(RegistrationService registrationService) {
this.registrationService = registrationService;
}
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public void register(@Valid @RequestBody RegisterRequest request) {
registrationService.register(request.username());
}
}
这段代码里有两条不同的失败路径。提交空用户名时,`@Valid` 在进入 register() 方法之前触发校验,对这个方法签名,Spring MVC 会抛出 MethodArgumentNotValidException。提交重复用户名时,参数校验通过,异常来自 RegistrationService。两条路径都可以交给同一个处理器。Spring MVC 参数校验文档
三、配置全局异常处理器
首先定义错误响应。这里取名 ApiError,避免和 Spring 自带的 ErrorResponse 类型混淆。
public record ApiError(String code, String message) {}
然后创建 GlobalExceptionHandler。如果项目习惯按职责分包,可以把它放进 exception 包。只要它位于组件扫描范围内,`@RestControllerAdvice` 就能生效,无需再给这个类添加 @Configuration。
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.*;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;
@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
private static final Logger log =
LoggerFactory.getLogger(GlobalExceptionHandler.class);
@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(
MethodArgumentNotValidException ex,
HttpHeaders headers,
HttpStatusCode status,
WebRequest request) {
FieldError error = ex.getBindingResult().getFieldError();
String message = error == null ? "请求参数有误" : error.getDefaultMessage();
return new ResponseEntity<>(
new ApiError("INVALID_ARGUMENT", message), headers, status);
}
@ExceptionHandler(UsernameAlreadyExistsException.class)
public ResponseEntity<ApiError> handleUsernameConflict(
UsernameAlreadyExistsException ex) {
return ResponseEntity.status(HttpStatus.CONFLICT)
.body(new ApiError("USERNAME_ALREADY_EXISTS", ex.getMessage()));
}
@ExceptionHandler(Exception.class)
public ResponseEntity<ApiError> handleUnexpected(Exception ex) {
log.error("处理请求时发生未预期异常", ex);
return ResponseEntity.internalServerError()
.body(new ApiError("INTERNAL_ERROR", "服务暂时不可用,请稍后重试"));
}
}
这三个方法里,各有一个值得留意的细节。
参数校验失败时,从字段错误中取提示。 getDefaultMessage() 可以拿到 @NotBlank 上写的「用户名不能为空」。直接返回 ex.getMessage(),用户看到的可能是一大段包含参数和校验规则的技术描述。这里的表单只有一个字段,因此取第一条字段错误就够了。
业务失败时,同时设置 HTTP 状态和响应体。 ResponseEntity.status(HttpStatus.CONFLICT) 设置真正的 HTTP 409,`body(...)` 则负责 JSON 内容。如果处理方法只返回一个普通 ApiError 对象,响应体里的错误码本身不会设置 HTTP 状态。
意外异常要保留服务端堆栈。 log.error("...", ex) 把完整异常交给日志系统,客户端收到稳定的 INTERNAL_ERROR。示例继承了 ResponseEntityExceptionHandler,Spring MVC 已识别的常见请求错误仍由对应的具体处理逻辑接手,例如请求体 JSON 损坏时保留 HTTP 400。本文自定义了表格中的三类响应,其他框架异常仍使用基类的默认响应体。Spring MVC 异常处理文档
四、发三次请求,看看异常在哪一层发生
启动项目后,在 Postman 中选择 POST http://localhost:8080/users,Body 选择 raw → JSON。按顺序发送下面三次请求:
| 次数 | 请求体 | 预期结果 |
|---|---|---|
| 第一次 | {"username":" "} | HTTP 400,提示「用户名不能为空」 |
| 第二次 | {"username":"xiaoming"} | HTTP 201,注册成功,响应体为空 |
| 第三次 | {"username":"xiaoming"} | HTTP 409,提示「用户名已被占用」 |
想看清楚执行顺序,可以在 registrationService.register(...) 和 handleUsernameConflict(...) 各打一个断点。第一次请求会在参数校验阶段结束。第二次请求进入 Service 并添加用户名。第三次请求中,`Set.add()` 返回 false,Service 抛出业务异常,随后程序会进入 handleUsernameConflict()。
如果要验证 500 兜底分支,可以在 Controller 测试里用 mock 让 registrationService.register(...) 抛出 IllegalStateException,断言 HTTP 状态为 500、响应中的 code 为 INTERNAL_ERROR。这样正常注册接口里也无需保留专门触发故障的代码。
五、两个实际开发中经常遇到的问题
为什么写了全局异常处理,前端还是收到了 HTTP 200?
先看处理方法的返回值。如果只是 return new ApiError(...),Spring 会把对象写进响应体。希望前端收到 400 或 409,可以像上例一样返回 ResponseEntity,或者在对应的处理方法上标记 @ResponseStatus。
为什么注册成功一次,重启项目后同名又能注册?
示例里的用户名保存在内存中,重启后集合会清空。换成数据库时,应给用户名建立唯一约束,并在保存时把用户名唯一约束冲突转换成 UsernameAlreadyExistsException。此时持久化方式发生了变化,客户端仍然收到相同的 HTTP 409 和业务错误码。
这也是全局异常处理在项目里的实际价值:以后新增「修改用户名」接口,只要它遇到占用情况时抛出同一个业务异常,现有处理器就能返回前端已经认识的那份 JSON。
1856



被折叠的 条评论
为什么被折叠?



