如何统一处理Controller异常？

Question

在Java Web开发中，Controller层作为MVC架构中的控制层，承担着接收请求、调用业务逻辑并返回响应的职责。当Controller方法执行过程中发生异常时，如何统一处理这些异常以避免重复代码、提升可维护性，是一个常见的技术问题。传统做法是在每个Controller方法中使用try-catch块捕获异常，但这会导致大量冗余代码，违反DRY原则。因此，如何利用Spring框架提供的全局异常处理机制（如@ControllerAdvice、@ExceptionHandler）来集中管理异常响应格式、日志记录及错误码返回，成为开发者需要深入掌握的核心技能。

Answer 1

Java Web开发中Controller层异常统一处理机制详解

在Spring MVC架构中，Controller层承担着接收HTTP请求、调用Service业务逻辑并返回响应的核心职责。然而，在实际开发过程中，异常的处理往往成为代码冗余和可维护性差的主要根源。

1. 传统做法的问题分析

传统的做法是在每个Controller方法中手动使用try-catch块捕获异常：

@RestController
public class UserController {
    @GetMapping("/user/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        try {
            User user = userService.findUserById(id);
            return ResponseEntity.ok(user);
        } catch (UserNotFoundException e) {
            return ResponseEntity.status(HttpStatus.NOT_FOUND).body(null);
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }
}

这种写法虽然有效，但存在以下问题：

• 违反DRY原则（Don't Repeat Yourself）
• 难以维护和扩展
• 日志记录分散，不利于集中监控
• 错误码和响应格式不统一

2. Spring框架提供的解决方案

Spring提供了两种主要机制用于全局异常处理：

机制	作用范围	适用场景
@ExceptionHandler	单个Controller类内	局部异常处理，适用于特定Controller内部
@ControllerAdvice / @RestControllerAdvice	全局范围	整个应用的异常统一处理

3. 全局异常处理器的实现步骤

1. 定义统一的错误响应结构体
2. 创建一个带有@ControllerAdvice注解的类
3. 使用@ExceptionHandler声明不同类型的异常处理方法
4. 集成日志记录组件如SLF4J或Logback
5. 返回标准化的错误码与消息格式

示例：全局异常处理器实现

@RestControllerAdvice
public class GlobalExceptionHandler {

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

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleUserNotFound(Exception ex) {
        logger.error("用户未找到异常", ex);
        ErrorResponse error = new ErrorResponse("USER_NOT_FOUND", ex.getMessage());
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneralException(Exception ex) {
        logger.error("未知异常", ex);
        ErrorResponse error = new ErrorResponse("INTERNAL_SERVER_ERROR", "系统内部错误");
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

4. 异常响应格式标准化设计

建议采用JSON格式返回错误信息，包含以下字段：

• errorCode：错误码，便于前端识别和处理
• message：错误描述
• timestamp：发生时间
• details（可选）：详细信息（如堆栈跟踪）

例如：

{
  "errorCode": "USER_NOT_FOUND",
  "message": "用户ID不存在",
  "timestamp": "2025-04-05T12:34:56Z"
}

5. 进阶实践与注意事项

在大型分布式系统中，异常处理还需考虑如下因素：

• 与日志聚合系统集成（如ELK Stack）
• 结合链路追踪工具（如SkyWalking、Zipkin）记录traceId
• 对敏感信息进行脱敏处理
• 支持多语言国际化错误提示
• 根据环境区分是否返回详细错误信息（生产 vs 开发）

流程图示意异常处理流程：

graph TD
            A[HTTP请求进入] --> B{Controller方法执行}
            B --> C[正常返回结果]
            B -->|抛出异常| D[进入异常处理器]
            D --> E[匹配异常类型]
            E --> F[构造错误响应]
            F --> G[返回标准JSON错误]