java后端开发怎么在项目中统一API返回格式？

定义统一Result类并结合@ControllerAdvice自动包装返回值与异常处理，使前后端接口格式一致。1. 创建包含code、message、data的Result类；2. 实现ResponseBodyAdvice对非Result类型自动封装；3. 使用@ExceptionHandler统一处理异常返回。最终所有接口均返回标准JSON结构，无需手动封装。

在Java后端开发中，统一API返回格式能提升前后端协作效率、增强接口可读性和一致性。通常做法是定义一个通用的响应体结构，并通过拦截或封装机制自动应用到所有接口返回中。

定义统一的返回结果类（Result）

创建一个通用的响应包装类，包含必要的字段如状态码、消息、数据等。

public class Result {
  private int code;
  private String message;
  private T data;

  // 构造方法
  public Result(int code, String message, T data) {
    this.code = code;
    this.message = message;
    this.data = data;
  }

  public static Result success(T data) {
    return new Result(200, "success", data);
  }

  public static Result fail(int code, String message) {
    return new Result(code, message, null);
  }

  // getter 和 setter 省略
}

这样前端始终接收 { "code": 200, "message": "success", "data": { ... } } 这类结构，便于统一处理。

使用@ControllerAdvice全局处理返回值

通过实现ResponseBodyAdvice接口，可以在不修改原有Controller的情况下，对所有返回结果进行包装。

立即学习“Java免费学习笔记（深入）”；

ARTi.PiCS

ARTi.PiCS是一款由AI驱动的虚拟头像生产器，可以生成200多个不同风格的酷炫虚拟头像

下载

@ControllerAdvice
public class ResponseWrapper implements ResponseBodyAdvice

这个组件会自动将Controller中返回的普通对象（如User、List等）包装成Result格式。

异常统一处理

配合@ExceptionHandler使用，确保异常也返回相同格式。

@ControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(Exception.class)
  public Result handleException(Exception e) {
    return Result.fail(500, "系统错误：" + e.getMessage());
  }

  // 可扩展处理特定异常，如参数校验异常等
}

这样无论是正常返回还是抛出异常，前端收到的都是统一结构。

实际使用示例

Controller中无需手动封装：

@RestController
public class UserController {

  @GetMapping("/user/{id}")
  public User getUser(@PathVariable Long id) {
    return userService.findById(id); // 直接返回实体
  }

  @PostMapping("/user")
  public User createUser(@RequestBody User user) {
    return userService.save(user); // 返回结果会被自动包装
  }
}

最终输出：
{ "code": 200, "message": "success", "data": { "id": 1, "name": "张三" } }