使用@RestControllerAdvice怎么对异常进行处理

发布时间：2021-06-18 15:50:40 作者：Leah
来源：亿速云阅读：315

# 使用@RestControllerAdvice怎么对异常进行处理

## 目录
- [一、Spring Boot异常处理机制概述](#一spring-boot异常处理机制概述)
- [二、@RestControllerAdvice核心原理](#二restcontrolleradvice核心原理)
- [三、基础异常处理实战](#三基础异常处理实战)
- [四、自定义异常体系构建](#四自定义异常体系构建)
- [五、响应数据标准化封装](#五响应数据标准化封装)
- [六、全局异常处理进阶技巧](#六全局异常处理进阶技巧)
- [七、特定异常的特殊处理](#七特定异常的特殊处理)
- [八、异常处理性能优化](#八异常处理性能优化)
- [九、测试策略与验证方法](#九测试策略与验证方法)
- [十、生产环境最佳实践](#十生产环境最佳实践)
- [总结与展望](#总结与展望)

---

## 一、Spring Boot异常处理机制概述

### 1.1 传统异常处理方式的问题
在传统Spring MVC应用中，我们通常使用以下方式处理异常：

```java
@Controller
public class UserController {
    
    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFound(UserNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
    
    @GetMapping("/users/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        // ...
    }
}

这种方式的局限性： 1. 异常处理逻辑分散在各个Controller中 2. 重复代码难以避免 3. 响应格式不统一

1.2 Spring的异常处理演进

Spring框架提供了多种异常处理机制：

机制	作用范围	适用场景
@ExceptionHandler	单个Controller	局部异常处理
@ControllerAdvice	全局范围	传统MVC全局异常处理
@RestControllerAdvice	全局范围	RESTful API异常处理

1.3 @RestControllerAdvice的优势

集中管理：所有异常处理逻辑集中在一个地方
响应统一：保证所有异常返回相同结构
灵活扩展：支持多种异常类型处理
代码复用：避免重复的异常处理代码

二、@RestControllerAdvice核心原理

2.1 注解解析

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ControllerAdvice
@ResponseBody
public @interface RestControllerAdvice {
    // ...
}

关键组合： - @ControllerAdvice：提供全局异常处理能力 - @ResponseBody：自动将返回值序列化为JSON

2.2 工作原理时序图

sequenceDiagram
    Client->>+DispatcherServlet: HTTP请求
    DispatcherServlet->>+Controller: 调用处理方法
    Controller-->>-DispatcherServlet: 抛出异常
    DispatcherServlet->>+ExceptionHandlerExceptionResolver: 解析异常
    ExceptionHandlerExceptionResolver->>+@RestControllerAdvice: 查找匹配的处理器
    @RestControllerAdvice-->>-ExceptionHandlerExceptionResolver: 返回处理结果
    ExceptionHandlerExceptionResolver-->>-DispatcherServlet: 转换响应
    DispatcherServlet->>+Client: 返回JSON响应

2.3 核心处理流程

请求进入DispatcherServlet
Controller方法执行抛出异常
ExceptionHandlerExceptionResolver查找匹配的@ExceptionHandler
执行对应的异常处理方法
返回标准化响应

三、基础异常处理实战

3.1 最小化配置示例

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleAllExceptions(Exception ex) {
        ErrorResponse response = new ErrorResponse(
            HttpStatus.INTERNAL_SERVER_ERROR.value(),
            "Internal Server Error",
            ex.getMessage()
        );
        return new ResponseEntity<>(response, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

@Data
@AllArgsConstructor
class ErrorResponse {
    private int status;
    private String error;
    private String message;
}

3.2 常见HTTP异常处理

@ExceptionHandler({
    MethodArgumentNotValidException.class,
    ConstraintViolationException.class
})
public ResponseEntity<ErrorResponse> handleValidationExceptions(Exception ex) {
    List<String> errors = new ArrayList<>();
    
    if (ex instanceof MethodArgumentNotValidException) {
        ((MethodArgumentNotValidException) ex).getBindingResult()
            .getFieldErrors()
            .forEach(error -> errors.add(error.getDefaultMessage()));
    } else if (ex instanceof ConstraintViolationException) {
        ((ConstraintViolationException) ex).getConstraintViolations()
            .forEach(violation -> errors.add(violation.getMessage()));
    }
    
    ErrorResponse response = new ErrorResponse(
        HttpStatus.BAD_REQUEST.value(),
        "Validation Failed",
        errors.toString()
    );
    return new ResponseEntity<>(response, HttpStatus.BAD_REQUEST);
}

3.3 处理404异常

@ExceptionHandler(NoHandlerFoundException.class)
public ResponseEntity<ErrorResponse> handle404(NoHandlerFoundException ex) {
    ErrorResponse response = new ErrorResponse(
        HttpStatus.NOT_FOUND.value(),
        "Resource Not Found",
        ex.getMessage()
    );
    return new ResponseEntity<>(response, HttpStatus.NOT_FOUND);
}

// 需要在application.properties中配置：
// spring.mvc.throw-exception-if-no-handler-found=true
// spring.web.resources.add-mappings=false

四、自定义异常体系构建

4.1 业务异常基类设计

public abstract class BusinessException extends RuntimeException {
    private final ErrorCode errorCode;
    private final Map<String, Object> details;

    protected BusinessException(ErrorCode errorCode, String message) {
        this(errorCode, message, null);
    }

    protected BusinessException(ErrorCode errorCode, String message, 
                             Map<String, Object> details) {
        super(message);
        this.errorCode = errorCode;
        this.details = details != null ? details : new HashMap<>();
    }
    
    // getters...
}

4.2 具体业务异常实现

public class OrderNotFoundException extends BusinessException {
    public OrderNotFoundException(Long orderId) {
        super(ErrorCode.ORDER_NOT_FOUND, 
             "Order not found with ID: " + orderId,
             Map.of("orderId", orderId));
    }
}

public class InsufficientStockException extends BusinessException {
    public InsufficientStockException(String productCode, int requested) {
        super(ErrorCode.INSUFFICIENT_STOCK,
             "Insufficient stock for product: " + productCode,
             Map.of(
                 "productCode", productCode,
                 "requestedQuantity", requested
             ));
    }
}

4.3 异常处理器实现

@ExceptionHandler(BusinessException.class)
public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException ex) {
    ErrorResponse response = new ErrorResponse(
        ex.getErrorCode().getHttpStatus().value(),
        ex.getErrorCode().name(),
        ex.getMessage(),
        ex.getDetails()
    );
    return new ResponseEntity<>(response, ex.getErrorCode().getHttpStatus());
}

五、响应数据标准化封装

5.1 统一响应结构设计

@Data
@NoArgsConstructor
@AllArgsConstructor
public class ApiResponse<T> {
    private boolean success;
    private int code;
    private String message;
    private T data;
    private long timestamp = System.currentTimeMillis();
    
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(true, 200, "success", data);
    }
    
    public static ApiResponse<?> error(int code, String message) {
        return new ApiResponse<>(false, code, message, null);
    }
}

5.2 异常响应转换

@ExceptionHandler(Exception.class)
public ApiResponse<?> handleGlobalException(Exception ex) {
    if (ex instanceof BusinessException) {
        BusinessException be = (BusinessException) ex;
        return ApiResponse.error(
            be.getErrorCode().getHttpStatus().value(),
            be.getMessage()
        );
    } else if (ex instanceof MethodArgumentNotValidException) {
        return ApiResponse.error(
            HttpStatus.BAD_REQUEST.value(),
            "Validation error: " + extractValidationError((MethodArgumentNotValidException) ex)
        );
    } else {
        return ApiResponse.error(
            HttpStatus.INTERNAL_SERVER_ERROR.value(),
            "Internal server error: " + ex.getMessage()
        );
    }
}

六、全局异常处理进阶技巧

6.1 异常处理优先级

@RestControllerAdvice
@Order(Ordered.HIGHEST_PRECEDENCE)
public class CustomExceptionHandler {
    // 具体异常处理优先于通用异常
    @ExceptionHandler(CustomException.class)
    public ResponseEntity<?> handleCustomException() {
        // ...
    }
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<?> handleGenericException() {
        // ...
    }
}

6.2 多@RestControllerAdvice协作

// 基础异常处理
@RestControllerAdvice
public class BasicExceptionHandler {
    @ExceptionHandler(Exception.class)
    public ResponseEntity<?> handleBasicException() {
        // ...
    }
}

// 业务异常处理（更高优先级）
@RestControllerAdvice
@Order(Ordered.HIGHEST_PRECEDENCE)
public class BusinessExceptionHandler {
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<?> handleBusinessException() {
        // ...
    }
}

七、特定异常的特殊处理

7.1 文件上传异常

@ExceptionHandler(MaxUploadSizeExceededException.class)
public ResponseEntity<?> handleFileSizeLimitExceeded() {
    return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE)
           .body("File size exceeds maximum allowed limit");
}

7.2 认证授权异常

@ExceptionHandler({
    AccessDeniedException.class,
    AuthenticationException.class
})
public ResponseEntity<?> handleAccessDeniedException(Exception ex) {
    return ResponseEntity.status(HttpStatus.FORBIDDEN)
           .body("Access denied: " + ex.getMessage());
}

八、异常处理性能优化

8.1 异常堆栈处理策略

@ExceptionHandler(Exception.class)
public ResponseEntity<?> handleException(Exception ex) {
    if (environment.acceptsProfiles(Profiles.of("prod"))) {
        log.error("System error occurred", ex);
        return ResponseEntity.internalServerError()
               .body("Internal server error");
    } else {
        return ResponseEntity.internalServerError()
               .body(new ErrorDetail(ex));
    }
}

8.2 异常缓存机制

private final Map<Class<? extends Exception>, HttpStatus> exceptionCache = 
    new ConcurrentHashMap<>();

@PostConstruct
public void init() {
    exceptionCache.put(IllegalArgumentException.class, HttpStatus.BAD_REQUEST);
    // 其他预定义映射...
}

@ExceptionHandler(Exception.class)
public ResponseEntity<?> handleCachedException(Exception ex) {
    HttpStatus status = exceptionCache.getOrDefault(
        ex.getClass(), 
        HttpStatus.INTERNAL_SERVER_ERROR
    );
    return ResponseEntity.status(status).body(ex.getMessage());
}

九、测试策略与验证方法

9.1 单元测试示例

@WebMvcTest
@Import(GlobalExceptionHandler.class)
class ExceptionHandlerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void testBusinessException() throws Exception {
        mockMvc.perform(get("/api/test-exception"))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.code").value(400))
            .andExpect(jsonPath("$.message").exists());
    }
}

9.2 集成测试策略

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class ExceptionHandlerIT {

    @LocalServerPort
    private int port;

    @Test
    void test404Handling() {
        ResponseEntity<String> response = restTemplate.getForEntity(
            "http://localhost:" + port + "/nonexistent",
            String.class
        );
        
        assertEquals(HttpStatus.NOT_FOUND, response.getStatusCode());
        assertTrue(response.getBody().contains("Not Found"));
    }
}

十、生产环境最佳实践

10.1 监控与告警集成

@ExceptionHandler(Exception.class)
public ResponseEntity<?> handleException(Exception ex) {
    metrics.counter("system.errors", "type", ex.getClass().getSimpleName())
           .increment();
    
    if (isCritical(ex)) {
        alertService.sendCriticalAlert(ex);
    }
    
    // 正常异常处理...
}

10.2 生产环境配置建议

# 异常处理相关配置
server.error.include-message=never
server.error.include-stacktrace=never
server.error.include-binding-errors=never

# 日志配置
logging.level.org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver=WARN

总结与展望

关键要点回顾

@RestControllerAdvice提供了集中式REST异常处理能力
自定义异常体系可以更好地表达业务语义
统一响应结构提升API一致性
异常处理需要考虑不同环境的需求差异

未来演进方向

与OpenAPI/Swagger集成生成异常文档
基于的异常自动分类与处理
更细粒度的异常处理策略配置
响应式编程中的异常处理模式

本文详细介绍了@RestControllerAdvice在Spring Boot中的异常处理实践，从基础用法到高级技巧，共计约17550字。实际开发中应根据项目需求选择合适的异常处理策略，在统一性和灵活性之间取得平衡。 “`

注：由于篇幅限制，这里展示的是精简后的文章框架和核心内容示例。完整17550字的文档需要扩展每个章节的详细说明、更多代码示例、性能对比数据、实际案例分析和参考资料等部分。如需完整版本，可以告知具体需要扩展的章节方向。