Spring Boot：统一返回格式，这样搞就对了。

Spring统一数据返回格式的核心思想是：强制所有Controller的返回值遵循同一个JSON结构，从而使前端处理响应时有一致的规范。

为什么要统一数据返回格式？

1. 前端处理方便：前端不需要为每个接口判断不同的响应结构，只需处理一种固定格式。
2. 便于协作：前后端约定好格式后，可以并行开发。
3. 标准化：包含状态码、信息、数据等标准字段，易于理解和维护。
4. 易于扩展：可以统一添加如timestamp、path等通用字段。

标准的统一响应体格式

一个通用的响应体通常包含以下字段：

JSON示例：

成功响应：

{
  "code": 200,
  "message": "请求成功",
  "data": {
    "id": 1,
    "name": "张三",
    "age": 25
  },
  "timestamp": 1719371635110
}

失败/异常响应：

{
  "code": 500,
  "message": "系统内部异常，请联系管理员",
  "data": null,
  "timestamp": 1719371635110
}

实现方案（三种，推荐方案三）

方案一：手动封装（不推荐，繁琐）

在每个Controller方法中手动创建响应对象。

// 1. 首先定义一个通用的响应类
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Result<T> {
    private Integer code;
    private String message;
    private T data;
    private Long timestamp = System.currentTimeMillis();

    public static <T> Result<T> success(T data) {
        return new Result<>(200, "成功", data, System.currentTimeMillis());
    }

    public static <T> Result<T> error(Integer code, String message) {
        return new Result<>(code, message, null, System.currentTimeMillis());
    }
}

// 2. 在Controller中手动使用
@RestController
@RequestMapping("/user")
public class UserController {

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

    @PostMapping
    public Result<String> createUser(@RequestBody User user) {
        userService.save(user);
        return Result.success("用户创建成功"); // 手动包装
    }
}

缺点：每个方法都要写Result.success(...)，代码重复。

方案二：使用@ControllerAdvice注解（推荐，优雅）

通过实现ResponseBodyAdvice接口，在数据写入Response Body之前进行拦截和包装。

步骤：

1. 定义统一响应体Result（同上）。
2. 实现ResponseBodyAdvice：

@RestControllerAdvice(basePackages = "com.yourpackage.controller") // 指定要拦截的包
public class GlobalResponseHandler implements ResponseBodyAdvice<Object> {

    /**
     * 判断是否支持advice功能
     * 返回true表示支持，会执行beforeBodyWrite方法
     */
    @Override
    public boolean supports(MethodParameter returnType, Class converterType) {
        // 排除掉已经封装成Result的返回值、Swagger的响应等
        return !returnType.getParameterType().isAssignableFrom(Result.class) &&
               !returnType.hasMethodAnnotation(ResponseBody.class); // 通常不需要这个检查，但根据情况定
    }

    /**
     * 对响应体进行实际包装
     */
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        // 如果返回的是String类型，需要特殊处理（因为String的转换器不同）
        if (body instanceof String) {
            // 通常不会直接返回String，如果返回了，需要手动转成JSON
            // 实际开发中应避免Controller直接返回String
            return JSON.toJSONString(Result.success(body));
        }
        // 如果返回体已经是Result类型（比如全局异常处理器返回的），则直接返回
        if (body instanceof Result) {
            return body;
        }
        // 最普遍的情况：包装成Result格式
        return Result.success(body);
    }
}

3. Controller保持干净：

@RestController
@RequestMapping("/user")
public class UserController {

    // 直接返回数据对象，GlobalResponseHandler会自动帮你包装成Result格式
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.getById(id);
    }

    @PostMapping
    public String createUser(@RequestBody User user) {
        userService.save(user);
        return "用户创建成功"; // 不推荐直接返回String，容易出问题
    }
    
    // 返回null也可以
    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        userService.removeById(id);
    }
}

注意：直接返回String类型可能会引发异常，因为Spring有专门的StringHttpMessageConverter。建议避免Controller直接返回String，或者在你的beforeBodyWrite方法中做好特殊处理（如上例所示）。

方案三：结合全局异常处理（最完整方案）

通常，方案二会和全局异常处理一起使用，以统一成功和失败的格式。

@RestControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 捕获所有未知异常
     */
    @ExceptionHandler(Exception.class)
    public Result<String> handleException(Exception e) {
        // 记录日志...
        return Result.error(500, "系统繁忙，请稍后再试: " + e.getMessage());
    }

    /**
     * 捕获业务异常（假设你有一个自定义的BusinessException）
     */
    @ExceptionHandler(BusinessException.class)
    public Result<String> handleBusinessException(BusinessException e) {
        return Result.error(e.getCode(), e.getMessage());
    }
}

这样，无论是正常响应还是异常抛出，最终返回给前端的都是统一的Result格式。

总结

最佳实践：采用方案三（@ControllerAdvice + 全局异常处理），这是目前Spring Boot项目中实现统一返回格式最主流、最优雅的方式。