统一数据返回格式和统一异常处理

在Java开发，尤其是基于Spring Boot的后端开发中，统一数据返回格式和统一异常处理是构建规范、健壮API接口的两大基石。这两者结合使用，可以极大地降低前后端联调成本，并提升系统的可维护性。

以下我将为你详细拆解这两部分的实现原理与最佳实践：

一、 统一数据返回格式 (Uniform Response Format)

1. 为什么要统一

如果不统一，你的接口可能返回：

成功时返回一个对象 {id: 1, name: "张三"}

失败时直接抛异常，返回Spring默认的500页面或错误栈。

这种不一致性会让前端程序员非常痛苦，因为他们需要针对每个接口写不同的解析逻辑。

统一后的标准格式通常如下：

{
  "code": 200,
  "message": "success",
  "data": {
    // 业务数据
  }
}

2. 核心实现：@ControllerAdvice + ResponseBodyAdvice

Spring提供了ResponseBodyAdvice接口，允许我们在响应体写出之前对其进行包装。

步骤一：定义返回结果实体类

@Data
public class Result<T> {
    private Integer code;
    private String message;
    private T data;

    // 构造成功结果
    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.code = 200;
        result.message = "success";
        result.data = data;
        return result;
    }

    // 构造失败结果
    public static <T> Result<T> error(Integer code, String message) {
        Result<T> result = new Result<>();
        result.code = code;
        result.message = message;
        return result;
    }
}

步骤二：实现全局响应拦截器

为了让 Controller 不需要手动写 return Result.success(user)，我们可以利用 @ControllerAdvice 拦截所有响应，自动进行包装。

@ControllerAdvice
public class ResponseAdvice implements ResponseBodyAdvice<Object> {

    // 判断是否需要执行 beforeBodyWrite 方法
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        // 这里可以加逻辑，比如某些接口不需要包装，可以在这里过滤
        return true;
    }

    // 对响应体进行包装
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
                                  Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                  ServerHttpRequest request, ServerHttpResponse response) {
        
        // 1. 防止重复包装：如果已经是Result类型，直接返回，避免出现 "data: {data: xxx}}"
        if (body instanceof Result) {
            return body;
        }

        // 2. 特殊处理String类型：因为StringHttpMessageConverter不能直接写入对象
        if (body instanceof String) {
            try {
                // 需要手动序列化为JSON字符串
                return new ObjectMapper().writeValueAsString(Result.success(body));
            } catch (JsonProcessingException e) {
                // 记录日志
            }
        }

        // 3. 默认包装
        return Result.success(body);
    }
}

如果不使用自动包装，也可以在 Controller 中手动调用，虽然多写几个字，但逻辑更清晰：

@GetMapping("/user/{id}")
public Result<User> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    return Result.success(user); // 手动包装
}

二、 统一异常处理 (Global Exception Handling)

1. 为什么要全局捕获？

当代码中出现 NullPointerException、ArithmeticException 或自定义业务异常时，如果不处理，Spring会返回HTTP 500错误，且数据格式混乱。

2. 核心实现：@ControllerAdvice + @ExceptionHandler

利用@ExceptionHandler注解，我们可以拦截指定类型的异常。

步骤一：定义自定义业务异常

// 业务异常，用于主动抛出（如：余额不足、库存不够）
public class BizException extends RuntimeException {
    private Integer code;

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

    // getter/setter...
}

步骤二：编写全局异常处理器

使用 @RestControllerAdvice（等同于 @ControllerAdvice + @ResponseBody）来捕获所有 Controller 层抛出的异常。

@RestControllerAdvice // 等同于 @ControllerAdvice + @ResponseBody
public class GlobalExceptionHandler {

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

    // 1. 捕获自定义业务异常
    @ExceptionHandler(BizException.class)
    public Result<String> handleBizException(BizException e) {
        logger.warn("业务异常: {}", e.getMessage());
        return Result.error(e.getCode(), e.getMessage());
    }

    // 2. 捕获参数校验异常 (JSR-303)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<String> handleValidException(MethodArgumentNotValidException e) {
        BindingResult bindingResult = e.getBindingResult();
        String errorMsg = bindingResult.getFieldError().getDefaultMessage();
        return Result.error(400, errorMsg);
    }

    // 3. 捕获所有未处理的系统异常
    @ExceptionHandler(Exception.class)
    public Result<String> handleException(Exception e) {
        // 1. 记录详细的错误日志（便于运维排查）
        logger.error("系统未知异常: ", e);
        
        // 2. （可选）发送告警通知，如飞书/钉钉机器人、邮件
        // alarmService.send("系统异常", e.getMessage());

        // 3. 返回给前端通用的错误提示，不要暴露敏感信息
        return Result.error(500, "服务器内部错误，请稍后重试");
    }
}

三、效果演示

配置完成后，你的接口表现将如下所示：

1. 正常请求

@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) { // 注意：这里直接返回 User 对象
    return new User("李四", 25);
}

前端收到JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "name": "李四",
    "age": 25
  }
}

2. 抛出异常

@GetMapping("/error")
public void throwError() {
    throw new BizException(400, "用户余额不足");
}

前端收到的 JSON

{
  "code": 400,
  "message": "用户余额不足",
  "data": null
}

四、 遇到的常见坑与解决方案

在实际落地过程中，你可能会遇到以下几个经典问题

问题场景	现象	解决方案
String 类型转换异常	报错 ClassCastException: Result cannot be cast to String	在 beforeBodyWrite 中判断，如果是String类型，需手动用 ObjectMapper 转为JSON字符串后再返回。
重复包装	返回数据变成 { code: 200, data: { code: 200, data: xxx } }	在 beforeBodyWrite 中先判断 if (body instanceof Result)，如果是，直接返回原对象。
静态资源干扰	访问 /favicon.ico 或错误路径导致异常	在 supports 方法中增加逻辑，过滤掉不需要处理的请求路径或返回类型。
异常信息泄露	生产环境把数据库密码、栈信息暴露给前端	全局异常处理器中，Exception.class 捕获后，只返回通用提示（如"系统繁忙"），详细日志仅记录在服务器。

五、 最佳实践建议

早抛出，晚捕获：在业务逻辑层（Service）发现错误应尽早抛出异常，不要在Service层进行try-catch吞掉异常，让Controller层或全局处理器统一处理。

异常分类：

业务异常（如：手机号已注册）：返回给用户看，HTTP状态码通常为200（业务成功响应）或400。

系统异常（如：数据库连接失败）：记录日志并告警，返回给用户"系统繁忙"。

结合日志与监控：统一异常处理是日志埋点的最佳位置。建议在此处集成ELK日志收集或Prometheus监控，一旦出现500错误，立即触发告警。

六、总结

通过结合 ResponseBodyAdvice 和 @ExceptionHandler，你建立了一个完善的 API 防护网：

数据格式统一：前端只需解析一种 JSON 结构。

代码解耦：业务代码专注于逻辑，无需关心 try-catch 和返回包装。

安全：隐藏了服务器的内部细节（如 Tomcat 版本、具体异常类名）。

可维护性：所有错误码和提示信息集中管理，修改时只需改一处。