Spring Boot统一异常处理与返回结构设计

在 Spring Boot 接口开发中，如果每个 Controller 都手动 try-catch，代码会很快变得重复且不一致。更好的方式是定义统一返回结构、业务异常和全局异常处理器，让 Controller 专注业务流程。

本文介绍一个常见实践：成功响应返回统一 JSON，业务失败抛出自定义异常，参数校验和未知异常由全局处理器统一转换。

定义统一返回结构

先定义一个通用响应类：

public class ApiResponse<T> {
    private String code;
    private String message;
    private T data;

    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode("OK");
        response.setMessage("success");
        response.setData(data);
        return response;
    }

    public static <T> ApiResponse<T> error(String code, String message) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode(code);
        response.setMessage(message);
        return response;
    }

    // getter and setter
}

实际项目可以使用 Lombok 简化 getter、setter，但核心结构应该清晰。

成功响应示例：

{
  "code": "OK",
  "message": "success",
  "data": {
    "id": 1,
    "name": "clang"
  }
}

失败响应示例：

{
  "code": "USER_NOT_FOUND",
  "message": "用户不存在"
}

定义业务异常

业务异常用于表达可预期的业务失败，例如用户不存在、余额不足、权限不足。

public class BusinessException extends RuntimeException {
    private final String code;

    public BusinessException(String code, String message) {
        super(message);
        this.code = code;
    }

    public String getCode() {
        return code;
    }
}

也可以定义错误码枚举：

public enum ErrorCode {
    USER_NOT_FOUND("USER_NOT_FOUND", "用户不存在"),
    PARAM_INVALID("PARAM_INVALID", "参数错误");

    private final String code;
    private final String message;

    ErrorCode(String code, String message) {
        this.code = code;
        this.message = message;
    }

    public String getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }
}

这样错误码更集中，避免字符串散落在业务代码中。

全局异常处理器

使用 @RestControllerAdvice：

@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ApiResponse<Void>> handleBusinessException(BusinessException ex) {
        return ResponseEntity
                .badRequest()
                .body(ApiResponse.error(ex.getCode(), ex.getMessage()));
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiResponse<Void>> handleValidationException(MethodArgumentNotValidException ex) {
        String message = ex.getBindingResult()
                .getFieldErrors()
                .stream()
                .findFirst()
                .map(FieldError::getDefaultMessage)
                .orElse("参数错误");

        return ResponseEntity
                .badRequest()
                .body(ApiResponse.error("PARAM_INVALID", message));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse<Void>> handleException(Exception ex) {
        log.error("unhandled exception", ex);
        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(ApiResponse.error("INTERNAL_ERROR", "服务器内部错误"));
    }
}

未知异常要记录完整堆栈，但响应中不要暴露 SQL、文件路径、服务器 IP、密钥等内部信息。

Controller 中的使用方式

Controller 不需要 try-catch：

@RestController
@RequestMapping("/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/{id}")
    public ApiResponse<UserVO> getUser(@PathVariable Long id) {
        UserVO user = userService.getUser(id);
        return ApiResponse.success(user);
    }
}

Service 中抛出业务异常：

public UserVO getUser(Long id) {
    User user = userRepository.findById(id)
            .orElseThrow(() -> new BusinessException("USER_NOT_FOUND", "用户不存在"));

    return convert(user);
}

这样业务代码只表达业务逻辑，错误转换交给全局处理器。

参数校验

请求 DTO：

public class CreateUserRequest {

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 32, message = "用户名长度必须在3到32之间")
    private String username;

    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;

    // getter and setter
}

Controller 中启用校验：

@PostMapping
public ApiResponse<UserVO> createUser(@Valid @RequestBody CreateUserRequest request) {
    UserVO user = userService.createUser(request);
    return ApiResponse.success(user);
}