如何在Spring Boot中优雅地处理全局异常并返回统一格式的响应

在实际的后端开发中，异常处理是不可忽视的一环。尤其是在构建 RESTful API 时，前端往往期望一个结构清晰、语义明确的错误响应格式。如果每个 Controller 都手动 try-catch，不仅代码冗余，还容易遗漏特定异常类型，导致前端无法准确识别错误来源。

Spring Boot 提供了强大的异常处理机制——@ControllerAdvice 和 @ExceptionHandler 组合，可以让我们在不侵入业务逻辑的前提下，集中管理所有控制器层抛出的异常，并以统一格式返回给客户端。

一、为什么要使用全局异常处理？

1. 减少重复代码：避免在每个接口中写相同的 try-catch 块。
2. 统一错误响应格式：便于前端解析，提高开发效率。
3. 增强可维护性：异常分类清晰，便于日志记录和监控。
4. 符合 RESTful 设计原则：HTTP 状态码 + 自定义错误信息 + 时间戳等字段。

二、基础实现步骤

1. 创建统一响应对象（ResponseEntity）

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

    public ApiResponse() {
        this.timestamp = System.currentTimeMillis();
    }

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

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

    // getter/setter...
}

2. 编写全局异常处理器类

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse<Object>> handleGenericException(Exception e) {
        ApiResponse<Object> response = ApiResponse.error(500, "服务器内部错误");
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response);
    }

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<ApiResponse<Object>> handleIllegalArgument(IllegalArgumentException e) {
        ApiResponse<Object> response = ApiResponse.error(400, e.getMessage());
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
    }

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiResponse<Object>> handleResourceNotFound(ResourceNotFoundException e) {
        ApiResponse<Object> response = ApiResponse.error(404, e.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(response);
    }
}

3. 定义自定义异常类（如需要）

public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

4. 在 Controller 中抛出自定义异常

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

    @GetMapping("/{id}")
    public ApiResponse<User> getUserById(@PathVariable Long id) {
        if (id <= 0) {
            throw new IllegalArgumentException("用户ID必须大于0");
        }
        // 模拟查询数据库
        User user = userService.findById(id);
        if (user == null) {
            throw new ResourceNotFoundException("用户不存在: " + id);
        }
        return ApiResponse.success(user);
    }
}

三、高级技巧与最佳实践

1. 异常分级处理（按异常类型细分）

• IllegalArgumentException: 参数非法
• MissingServletRequestParameterException: 必填参数缺失
• MethodArgumentNotValidException: Bean Validation 校验失败
• ConstraintViolationException: 数据库约束违反（如唯一索引冲突）
• DataAccessException: 数据库访问异常（如连接超时、SQL语法错误）

示例：

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ApiResponse<Object>> handleValidationException(MethodArgumentNotValidException e) {
    List<String> errors = e.getBindingResult()
        .getFieldErrors()
        .stream()
        .map(error -> error.getField() + ": " + error.getDefaultMessage())
        .collect(Collectors.toList());

    ApiResponse<Object> response = ApiResponse.error(400, "参数校验失败: " + errors.toString());
    return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
}

2. 日志记录（重要！）

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

@ExceptionHandler(Exception.class)
public ResponseEntity<ApiResponse<Object>> handleGenericException(Exception e) {
    logger.error("Global exception occurred", e);
    ApiResponse<Object> response = ApiResponse.error(500, "服务器内部错误");
    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response);
}

3. 使用 AOP 进一步封装（可选）

对于更复杂的场景（如权限检查、事务控制），可以结合 Spring AOP 实现横切关注点分离，进一步解耦异常处理逻辑。

4. 前端友好提示设计建议

这样前端可以根据 code 字段快速定位问题类型，无需依赖原始异常堆栈。

四、常见问题排查

五、总结

通过合理利用 Spring Boot 的全局异常处理机制，我们可以轻松构建出健壮、易维护的 API 接口。关键在于：

• 设计统一响应模型；
• 分类处理不同异常；
• 记录日志便于调试；
• 前后端约定好错误码规范。

这套方案已经在多个生产环境中稳定运行多年，非常适合中小型团队快速搭建标准化后端服务。

💡 小贴士：推荐配合 Swagger UI 文档工具一起使用，让接口文档也体现异常说明，提升协作效率！

如果你正在搭建新的 Spring Boot 项目，不妨现在就加入这一套异常处理框架吧！