典型用法

為某個接口指定固定的 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 {
}