spring-webmvc @ResponseStatus 典型用法

典型用法

为某个接口指定固定的 HTTP 状态码（如创建成功返回 201）

当该方法执行成功时，HTTP 响应状态码会是 201 Created。
适用于不需要动态控制状态码的场景。

@PostMapping("/users")
@ResponseStatus(HttpStatus.CREATED)
public User createUser(@RequestBody User user) {
    return userService.save(user);
}

抛出自定义异常时自动设置 HTTP 状态码（如资源未找到返回 404）

当抛出 ResourceNotFoundException 时，Spring 会自动将其映射为 404 Not Found 响应。非常适合统一异常处理机制。

@ResponseStatus(HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.findById(id).orElseThrow(() -> new ResourceNotFoundException("User not found"));
}

结合 @ControllerAdvice 实现全局异常处理

在结合 @ControllerAdvice 实现全局异常处理时，通常不会直接使用 @ResponseStatus 注解来设置响应状态码，而是通过返回值类型 ResponseEntity 或其他封装方式来显式控制 HTTP 状态码和响应体内容。

@ControllerAdvice
public class GlobalExceptionHandler {

    // 处理资源未找到异常
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleResourceNotFound(ResourceNotFoundException ex) {
        ErrorResponse error = new ErrorResponse("RESOURCE_NOT_FOUND", ex.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }

    // 处理参数校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach(error -> {
            String field = ((FieldError) error).getField();
            String message = error.getDefaultMessage();
            errors.put(field, message);
        });
        ErrorResponse error = new ErrorResponse("VALIDATION_ERROR", errors);
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(error);
    }

    // 处理所有其他异常
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneralException(Exception ex) {
        ErrorResponse error = new ErrorResponse("INTERNAL_SERVER_ERROR", "An unexpected error occurred");
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
    }
}

指定响应体内容（不推荐）

虽然 @ResponseStatus 可以设置 reason 属性，但不推荐直接通过注解设置响应体内容，因为这会导致响应格式不一致。

@ResponseStatus(value = HttpStatus.FORBIDDEN, reason = "Access denied")
public class AccessDeniedException extends RuntimeException {
}