responseentity 是 rest 接口中精准构造 http 响应的标准方式，支持统一控制状态码、响应头和响应体；提供 ok()、badrequest() 等静态方法快速返回常见状态，也支持 status()、header() 动态设置；配合 result 包装类时仍需保留语义化状态码，异常应由 @controlleradvice 统一处理。
在 REST 接口开发中，ResponseEntity 不是用来“自定义类”的工具，而是用来精准构造 HTTP 响应的官方标准方式。它让你在单个返回值里同时控制状态码、响应头和响应体，避免状态码和业务数据脱节。
用静态方法快速返回常见状态
Spring 提供了语义清晰的静态工厂方法，适合多数场景：
-
ResponseEntity.ok(body)→ 200 OK，带响应体 -
ResponseEntity.badRequest().body("参数有误")→ 400 Bad Request -
ResponseEntity.notFound().build()→ 404 Not Found，无响应体 -
ResponseEntity.noContent().build()→ 204 No Content -
ResponseEntity.created(URI.create("/users/123")).body(user)→ 201 Created + Location 头
动态设置状态码与响应头
当需要非标准码（如 422 Unprocessable Entity）或自定义头（如下载文件名、缓存策略），用 .status() 和 .header() 链式调用：
ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY).body("校验失败")ResponseEntity.status(422).header("X-Error-ID", "ERR-789").body(map)- 文件下载：
ResponseEntity.ok().header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"report.pdf\"").contentType(MediaType.APPLICATION_PDF).body(resource)
配合统一响应结构（如 Result）
即使项目封装了 Result.success(data) 这类包装类，也不要放弃 HTTP 状态码的语义表达：
- 正确写法：
return ResponseEntity.ok(Result.success(user))（200） - 错误处理：
return ResponseEntity.status(HttpStatus.FORBIDDEN).body(Result.error("权限不足"))（403） - 避免所有接口都返回 200 + 自定义 code 字段，这会让前端无法利用浏览器/框架的原生错误拦截机制
异常场景交给 @ControllerAdvice 统一处理
业务异常、参数校验失败等不该散落在每个接口里手动判断：
- 全局捕获
MethodArgumentNotValidException，返回 400 并附带校验字段信息 - 捕获自定义业务异常（如
UserNotFoundException），映射为 404 - 统一返回
ResponseEntity.status(...).body(...)，保持响应格式一致
