如何使用 ResponseEntity 构建规范的 RESTful API 响应体？

在设计 RESTful 接口时，许多人只关注返回的 JSON 数据长什么样，却忽略了 HTTP 状态码和响应头同样是接口契约的一部分。查询成功返回 200，创建资源成功返回 201，删除成功返回 204，参数错误返回 400，这些细节直接决定了接口是否规范。Spring MVC 提供的 ResponseEntity 类允许开发者精确控制整个 HTTP 响应，包括状态码、响应头和响应体，是构建规范 REST 接口的核心工具。

一、ResponseEntity 的本质与基本用法

ResponseEntity 是 Spring 对 HTTP 响应的完整抽象，它继承自 HttpEntity，内部持有三个关键信息：HTTP 状态码（HttpStatus）、响应头（HttpHeaders）以及响应体（body）。当控制器方法返回 ResponseEntity 时，Spring 会跳过默认的视图解析流程，把它原封不动地序列化成 HTTP 响应。

最基础的用法是直接 new 一个实例，不过更推荐使用静态工厂方法，语义更清晰：

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        if (user == null) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.ok(user);
    }
}

这段代码体现了两个关键点。第一，泛型 ResponseEntity<User> 明确声明了响应体类型，配合 Swagger 等文档工具可以自动生成准确的接口描述；第二，notFound() 和 ok() 这类工厂方法让状态码的选择一目了然，代码可读性远高于手动拼接 Map。

二、常用静态工厂方法与状态码选择

REST 架构对状态码有明确约定，选错状态码是接口不规范的常见原因。ResponseEntity 为常用状态码都提供了便捷方法，整理如下：

创建资源的接口尤其值得注意，规范做法是返回 201，并通过 Location 响应头告知客户端新资源的地址。created 方法接收一个 URI 参数，正好满足这个要求：

@PostMapping
public ResponseEntity<User> createUser(@RequestBody UserDTO dto) {
    User saved = userService.create(dto);
    // 拼接新资源的访问地址，放入 Location 响应头
    URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(saved.getId())
            .toUri();
    return ResponseEntity.created(location).body(saved);
}

删除接口则通常返回 204，表示操作成功但没有响应体。注意 noContent() 返回的 Builder 不支持调用 body 方法，因为 204 本身就约定不能携带响应体，强行设置会在某些客户端引发解析异常。

三、统一响应体与全局异常处理的配合

实际项目中往往需要统一的响应结构，比如所有接口都返回 code、message、data 三个字段。这时可以定义一个泛型结果类，让 ResponseEntity 包装它，做到 HTTP 状态码和业务码的双重规范：

public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;

    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> r = new ApiResponse<>();
        r.code = 0;
        r.message = "success";
        r.data = data;
        return r;
    }
    // getter / setter 省略
}

异常场景交给 @RestControllerAdvice 统一处理，避免在业务代码里写满 try-catch：

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ApiResponse<Void>> handleNotFound(UserNotFoundException e) {
        ApiResponse<Void> body = new ApiResponse<>();
        body.setCode(10001);
        body.setMessage(e.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(body);
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiResponse<Void>> handleValid(MethodArgumentNotValidException e) {
        ApiResponse<Void> body = new ApiResponse<>();
        body.setCode(10002);
        body.setMessage(e.getBindingResult().getFieldError().getDefaultMessage());
        return ResponseEntity.badRequest().body(body);
    }
}

这种组合的价值在于：控制器只负责正常流程，异常统一由切面转换成规范的 HTTP 响应。客户端既可以通过 HTTP 状态码快速判断请求结果，也可以通过业务 code 做更细粒度的错误处理，两层信息互不冲突。

四、直接返回 DTO 还是包装 ResponseEntity

有人会问：控制器方法直接返回 User 不是更简单吗？确实，Spring 会默认以 200 状态码返回并序列化对象。但这种写法失去了对状态码的控制能力，一旦需要返回 201 或 404，就只能抛异常借助异常处理器间接实现，灵活性大打折扣。

两种方式的选择可以参考一个简单原则：如果接口语义固定为成功查询，直接返回 DTO 完全可以；如果接口涉及资源创建、删除、部分更新等操作，或者需要设置缓存头、自定义响应头，就应该用 ResponseEntity。例如给查询接口加上缓存控制和 ETag：

@GetMapping("/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    return ResponseEntity.ok()
            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(5)))
            .eTag("v" + user.getVersion())
            .body(user);
}

总而言之，ResponseEntity 的意义不只是包装返回值，而是让接口完整地表达 HTTP 语义。配合合理的异常处理机制和统一响应结构，可以让整个服务的接口风格高度一致，无论是对前端联调还是后续维护，都会省去大量沟通成本。

ResponseEntityRESTful APISpring Boot修改时间：2026-09-13 14:56:55