@ResponseStatus用于为自定义异常全局绑定HTTP状态码和原因短语，直接标注在异常类上；当异常被Spring MVC捕获且未被@ExceptionHandler拦截时生效，优先级低于@ExceptionHandler。
@ResponseStatus 是 Spring MVC 提供的注解，用于为自定义异常类**全局性地绑定 HTTP 状态码和响应原因短语**。它不作用于方法，而是直接标注在异常类上，当该异常被 Spring MVC 的异常处理器（如 ExceptionHandlerExceptionResolver）捕获并处理时，Spring 会自动将响应状态设为指定值。
1. 定义自定义异常并添加 @ResponseStatus
创建一个继承自 RuntimeException（或 Exception）的异常类，并在其上使用 @ResponseStatus 注解：
@ResponseStatus(code = HttpStatus.NOT_FOUND, reason = "用户不存在")
public class UserNotFoundException extends RuntimeException {
public UserNotFoundException() {
super("用户不存在");
}
public UserNotFoundException(String message) {
super(message);
}
}
说明：
-
code：指定 HTTP 状态码，如HttpStatus.NOT_FOUND（404）、HttpStatus.BAD_REQUEST（400）等； -
reason（可选）：设置响应头中的Reason Phrase（如Not Found），部分客户端可能显示该文本； - 该注解只对被 Spring MVC 捕获的异常生效（即抛出后未被其他
@ExceptionHandler显式拦截）； - 若同时存在
@ExceptionHandler方法处理该异常，则@ResponseStatus会被忽略——优先级更低。
2. 在 Controller 中直接抛出自定义异常
无需额外配置，只要在控制器中抛出该异常，Spring 就会自动返回对应状态码：
立即学习“Java免费学习笔记（深入）”；
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
@RestController
public class UserController {
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
User user = userService.findById(id);
if (user == null) {
throw new UserNotFoundException("ID 为 " + id + " 的用户未找到");
}
return user;
}
}
此时访问 GET /users/999（假设不存在），响应状态码为 404 Not Found，响应体为默认 JSON 错误格式（取决于 spring-boot-starter-web 的错误机制）。
3. 注意事项与常见配合方式
-
不适用于已捕获的异常：如果在 Controller 内用
try-catch吞掉了异常，或被@ExceptionHandler拦截并返回了自定义响应，则@ResponseStatus不起作用； -
推荐搭配 @ControllerAdvice 使用：对于更复杂的错误响应（如统一 JSON 结构、记录日志、补充错误码字段），建议用
@ExceptionHandler+@ControllerAdvice全局处理，此时可忽略@ResponseStatus； -
状态码语义要准确：例如参数校验失败用
400 BAD_REQUEST，资源不存在用404 NOT_FOUND，权限不足用403 FORBIDDEN或401 UNAUTHORIZED； -
Spring Boot 默认错误页会识别它：在非 API 场景（如返回 HTML），Spring Boot 的
/error端点会根据@ResponseStatus选择对应状态码的错误页面（如404.html）。
4. 与 @ExceptionHandler 的选择建议
简单场景（仅需改状态码）→ 用 @ResponseStatus，轻量、声明式、零配置；
复杂场景（需定制响应体、日志、多环境处理、国际化）→ 用 @ExceptionHandler 在 @ControllerAdvice 中统一处理。
二者可以共存，但后者会覆盖前者的行为。
