Spring MVC 处理 HTTP 状态码、响应头和异常的完整示例
Spring MVC 处理 HTTP 状态码、响应头和异常的完整示例
1. 正常响应处理
通过 ResponseEntity 可以灵活控制 HTTP 状态码、响应头和响应体。
代码示例：创建资源返回 201 并设置 Location 头
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/users")
public class UserController {
@PostMapping
public ResponseEntity<User> createUser(@RequestBody User user) {
// 保存用户逻辑（假设已成功保存）
user.setId(1L); // 假设生成的用户ID为1
// 设置 Location 头指向新资源的 URI
HttpHeaders headers = new HttpHeaders();
headers.setLocation(ServletUriComponentsBuilder
.fromCurrentRequest()
.path("/{id}")
.buildAndExpand(user.getId())
.toUri());
return new ResponseEntity<>(user, headers, HttpStatus.CREATED); // 201 Created
}
}
代码示例：成功响应返回 200 并设置 Cache-Control 头
@GetMapping("/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
User user = userService.findById(id); // 假设用户存在
HttpHeaders headers = new HttpHeaders();
headers.setCacheControl(CacheControl.noCache()); // 禁止缓存
return new ResponseEntity<>(user, headers, HttpStatus.OK); // 200 OK
}
2. 异常处理
通过 @ResponseStatus 和 @ControllerAdvice 实现异常状态码与响应控制。
自定义异常类（带 @ResponseStatus）
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ResponseStatus;
@ResponseStatus(code = HttpStatus.NOT_FOUND, reason = "User not found")
public class UserNotFoundException extends RuntimeException {
public UserNotFoundException(String message) {
super(message);
}
}
全局异常处理类（@ControllerAdvice）
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorDetails> handleUserNotFound(
UserNotFoundException ex, WebRequest request) {
ErrorDetails error = new ErrorDetails(
HttpStatus.NOT_FOUND.value(),
ex.getMessage(),
request.getDescription(false)
);
return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
}
@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorDetails> handleGeneralException(
Exception ex, WebRequest request) {
ErrorDetails error = new ErrorDetails(
HttpStatus.INTERNAL_SERVER_ERROR.value(),
"Internal Server Error",
request.getDescription(false)
);
return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
}
// 辅助类：错误响应体
private static class ErrorDetails {
private int statusCode;
private String message;
private String path;
public ErrorDetails(int statusCode, String message, String path) {
this.statusCode = statusCode;
this.message = message;
this.path = path;
}
// 省略 getter/setter
}
}
3. 响应头设置示例
@GetMapping("/custom-headers")
public ResponseEntity<String> customHeaders() {
HttpHeaders headers = new HttpHeaders();
headers.add("X-Custom-Header", "custom-value");
headers.set("Content-Type", "text/plain");
headers.set("Access-Control-Allow-Origin", "*");
return new ResponseEntity<>("Response with custom headers", headers, HttpStatus.OK);
}
4. 关键注解与类说明
| 注解/类 | 作用 | 示例 |
|---|---|---|
@ResponseStatus | 在异常类上定义默认 HTTP 状态码和原因。 | @ResponseStatus(HttpStatus.NOT_FOUND) |
ResponseEntity | 直接控制 HTTP 状态码、响应头和响应体。 | new ResponseEntity<>(data, headers, HttpStatus.OK) |
@ControllerAdvice | 全局异常处理类，集中管理异常响应。 | @ControllerAdvice + @ExceptionHandler |
HttpStatus | HTTP 状态码枚举（如 HttpStatus.OK, HttpStatus.CREATED）。 | HttpStatus.NOT_FOUND |
5. 场景总结表格
| 场景 | 实现方式 | 状态码 | 响应头示例 | 适用情况 |
|---|---|---|---|---|
| 成功创建资源 | ResponseEntity + HttpStatus.CREATED | 201 | Location: /api/users/1 | 新资源创建成功后返回位置 |
| 返回成功数据 | ResponseEntity + HttpStatus.OK | 200 | Cache-Control: no-cache | 正常业务响应 |
| 资源不存在异常 | @ResponseStatus(HttpStatus.NOT_FOUND) | 404 | 无 | 资源查询失败 |
| 全局异常处理（如服务器错误） | @ControllerAdvice + @ExceptionHandler | 500 | 无 | 捕获通用未处理异常 |
| 自定义响应头 | ResponseEntity 设置 HttpHeaders | 200 | X-Custom-Header: custom-value | 需要添加自定义响应头时 |
关键总结
- 状态码控制：
ResponseEntity直接指定状态码（如HttpStatus.CREATED）。@ResponseStatus在异常类上定义默认状态码。
- 响应头管理：
- 通过
HttpHeaders对象添加任意头信息。
- 通过
- 异常处理：
- 自定义异常 +
@ResponseStatus：针对特定异常返回状态码。 @ControllerAdvice：全局统一处理异常，返回结构化错误信息。
- 自定义异常 +
- 最佳实践：
- 使用
ResponseEntity精确控制响应细节。 - 通过
ErrorDetails统一错误响应格式。 - 对于常见 HTTP 状态码（如 404、500），优先使用标准枚举值。
- 使用