随着微服务架构的广泛普及，Spring Boot 凭借其简洁的配置和强大的生态成为后端开发的首选框架。在构建 RESTful API 时，统一的异常处理机制是保证系统健壮性和用户体验一致性的关键。Spring 提供的 @RestControllerAdvice 注解使得开发者能够集中管理全局异常，但如何 Customisation of The RestControllerAdvice Response（自定义响应格式）成为许多团队面临的进阶课题。本文将深入解析这一技术细节，并提供实战级的最佳实践。

一、为什么需要自定义 RestControllerAdvice 响应？

默认情况下，@RestControllerAdvice 结合 @ExceptionHandler 会返回 Spring 内置的错误结构，例如 DefaultErrorAttributes 生成的 JSON 包含 timestamp、status、error、message、path 等字段。然而，实际生产环境中，前端或客户端往往期望统一的响应体，比如：

{
  "code": 10001,
  "message": "用户不存在",
  "data": null
}

此外，不同业务场景可能需要携带额外的调试信息、国际化消息或链路追踪 ID。因此，自定义响应格式能够提升 API 的可维护性和团队协作效率。

二、核心实现：从基础到高级

1. 定义统一的响应体类

首先，创建一个泛型响应类 ApiResponse<T>，包含 code、message、data 等字段，并支持链式调用：

public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;
    // 构造函数、getter/setter
    public static <T> ApiResponse<T> success(T data) { ... }
    public static <T> ApiResponse<T> error(int code, String message) { ... }
}

2. 重构异常处理器

在 @RestControllerAdvice 中，使用自定义响应包裹异常信息。关键点在于捕获不同异常时返回统一结构：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ResourceNotFoundException.class)
    public ApiResponse<?> handleNotFound(ResourceNotFoundException ex) {
        return ApiResponse.error(404, ex.getMessage());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResponse<?> handleValidation(MethodArgumentNotValidException ex) {
        String msg = ex.getBindingResult().getFieldErrors().stream()
                .map(e -> e.getField() + ":" + e.getDefaultMessage())
                .collect(Collectors.joining("; "));
        return ApiResponse.error(400, msg);
    }
}

3. 高级自定义：动态响应格式

当需要根据客户端版本或环境动态调整响应字段时，可以引入 HttpServletRequest 或自定义注解。例如，通过判断请求头中的 X-Debug 字段来附加堆栈信息：

@ExceptionHandler(Exception.class)
public ApiResponse<?> handleAll(Exception ex, HttpServletRequest request) {
    boolean debug = "true".equals(request.getHeader("X-Debug"));
    ApiResponse<?> resp = ApiResponse.error(500, "服务器内部错误");
    if (debug) {
        resp.setStackTrace(ex.getStackTrace()); // 添加额外字段
    }
    return resp;
}

4. 与 Spring Security 集成

处理安全异常时，需注意 AccessDeniedException 和 AuthenticationException 不会被 @RestControllerAdvice 直接捕获，因为它们在过滤器链中抛出。解决方案是自定义 AccessDeniedHandler 并注入相同的 ApiResponse 格式。

三、最佳实践与注意事项

1. 保持响应结构的统一性

团队应制定 API 响应规范，确保所有成功、失败响应使用相同的顶层字段。建议将 code 定义为业务码（如 20000 表示成功，20001 表示参数错误），避免与 HTTP 状态码混淆。

2. 避免暴露敏感信息

在生产环境中，应屏蔽 SQL 异常、堆栈追踪等内部信息。可以利用 application-prod.yml 配置 server.error.include-stacktrace=never，并在异常处理器中区分环境。

3. 国际化支持

通过 LocaleContextHolder 获取当前用户语言，使用 MessageSource 动态生成错误消息，使 API 响应自动适配多语言。

4. 性能监控

在较大并发场景下，异常处理的性能不可忽视。建议在处理器中记录日志（使用 MDC 保存 traceId），避免在异常对象中执行耗时操作（如数据库查询）。

四、案例：金融系统实战

某支付平台需要所有 API 返回密文格式的响应。他们在 @RestControllerAdvice 中实现了如下流程：捕获异常 → 组装 ApiResponse → 使用 AES 加密 data 字段 → 返回统一加密 JSON。同时，通过拦截器自动解密请求，实现了端到端的安全通信。

五、总结

自定义 RestControllerAdvice 响应是 Spring Boot 工程中提升 API 质量的重要一步。从定义统一响应体到动态调整字段，再到与安全、国际化模块整合，开发者可以根据业务需求灵活定制。未来，随着响应式编程（WebFlux）的普及，ResponseBodyAdvice 和 @ControllerAdvice 的配合将带来更多可能性。掌握这一技术，将使您的后端服务更加健壮、规范且易于维护。

（全文约 980 字）