ResponseEntity 是 Spring Boot 中最常用且灵活的响应封装方式，可精确控制 HTTP 状态码、响应头和响应体；推荐使用 HttpStatus 枚举而非数字状态码，并结合 HttpHeaders 添加自定义头，异常处理应通过 @ControllerAdvice 统一返回 ResponseEntity。

在 Java 的 Spring Boot 项目中，ResponseEntity 是最常用、最灵活的响应封装方式，它允许你**精确控制 HTTP 状态码、响应头和响应体**，而不仅限于默认的 200 OK。

直接返回 ResponseEntity 包裹的数据和状态码

这是最常见也最推荐的方式：用 ResponseEntity.ok()、ResponseEntity.status() 或构造器显式指定状态码。

• ResponseEntity.ok(data) → 返回 200 OK + 数据
• ResponseEntity.status(HttpStatus.CREATED).body(data) → 返回 201 Created + 数据
• ResponseEntity.badRequest().body("参数错误") → 返回 400 Bad Request + 错误信息
• ResponseEntity.status(422).body(map) → 自定义非标准状态码（如 422 Unprocessable Entity）

配合 HttpStatus 枚举提升可读性和类型安全

Spring 提供了完整的 HttpStatus 枚举，建议优先使用它而不是硬写数字，避免拼写/数值错误，也便于后期维护。

Java 接口排错助手

在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。

下载

• 不推荐：ResponseEntity.status(404).body("未找到")
• 推荐：ResponseEntity.status(HttpStatus.NOT_FOUND).body("用户不存在")
• 常见枚举值：OK、CREATED、NO_CONTENT、BAD_REQUEST、NOT_FOUND、UNAUTHORIZED、FORBIDDEN、INTERNAL_SERVER_ERROR

添加自定义响应头（如 Location、X-Total-Count）

当需要返回额外元数据时（比如新建资源后的 URL、分页总数），可用 HttpHeaders 构建完整响应。

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

• 例如创建用户后返回 Location 头：
  

  HttpHeaders headers = new HttpHeaders();<br>
    headers.setLocation(URI.create("/api/users/123"));<br>
    return ResponseEntity.created(headers.getLocation()).headers(headers).body(user);

• 分页接口中带总数：
  

  headers.set("X-Total-Count", String.valueOf(total));<br>
    return ResponseEntity.ok().headers(headers).body(list);

统一异常处理中结合 ResponseEntity 使用

不要在每个 Controller 方法里手动写 4xx/5xx 响应。推荐用 @ControllerAdvice + @ExceptionHandler 统一拦截异常并包装为 ResponseEntity。

• 例如捕获业务异常：
  

  @ExceptionHandler(UserNotFoundException.class)<br>
    public ResponseEntity<String> handleUserNotFound(UserNotFoundException e) {<br>
      return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());<br>
    }

• 这样 Controller 层只关注正常流程，异常响应逻辑集中、一致、易测试