Spring Boot REST接口返回HTTP状态码应遵循语义化原则，推荐三种方式：1. @ResponseStatus用于固定状态码；2. ResponseEntity实现动态控制；3. @ControllerAdvice统一异常处理。
用 @ResponseStatus 注解固定状态码
适合返回结果确定、无需动态判断的接口，比如创建资源固定返回 201，或某个方法明确表示“不支持”返回 405。直接加在 Controller 方法或自定义异常类上：
- 加在方法上：该接口每次调用都返回指定状态码，不管逻辑是否出错
- 加在异常类上：抛出该异常时自动映射为对应状态码，推荐用于业务校验失败（如参数非法、权限不足）
示例（方法级）：
@PostMapping("/order")
@ResponseStatus(HttpStatus.CREATED)
public Order createOrder(@RequestBody OrderRequest req) {
return orderService.save(req);
}
注意：如果方法里实际抛了异常（比如空指针），@ResponseStatus 不会捕获它，最终仍可能返回 500 —— 所以它只适用于“正常流程下稳定返回某状态”的场景。
用 ResponseEntity 动态控制状态码
适合需要根据运行时条件返回不同状态码的接口，比如查用户：存在 → 200，不存在 → 404；或提交表单：校验通过 → 200，失败 → 400。它把响应体、状态码、响应头全部封装进一个对象，灵活又直观：
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
-
ResponseEntity.ok().body(x)→ 默认 200 -
ResponseEntity.status(400).body("参数错误")→ 自定义 400 -
ResponseEntity.badRequest().body(...)→ 语义化写法，等价于 400
示例：
@GetMapping("/user/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
User user = userService.findById(id);
if (user == null) {
return ResponseEntity.notFound().build(); // 404
}
return ResponseEntity.ok(user); // 200
}
用 @ControllerAdvice + @ExceptionHandler 统一处理异常
这是最推荐的全局方案，尤其当项目中大量使用自定义异常（如 `UserNotFoundException`、`InsufficientBalanceException`）时。好处是：一处定义，处处生效；避免每个接口重复 try-catch；还能统一记录日志、补全错误信息。
- 拦截特定异常类型，返回对应状态码和结构化 JSON
- 配合统一封装的响应体（如 Result
），让 404/500 也返回和正常接口一致的格式 - 别忘了在配置中启用 404 拦截：
spring.mvc.throw-exception-if-no-handler-found=true和spring.resources.add-mappings=false
示例（处理未找到资源）：
@ExceptionHandler(UserNotFoundException.class)
@ResponseBody
public Result<Void> handleUserNotFound(UserNotFoundException e) {
return Result.error(404, "用户不存在");
}
这样，即使 URL 写错触发 404，也不会返回 Spring Boot 默认的 HTML 或原始 JSON，而是你定义的 {"code":404,"message":"用户不存在","data":null} 格式。
