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 {@PostMappingpublic ResponseEntity<User> createUser(@RequestBody User user) {// 保存用户逻辑（假设已成功保存）user.setId(1L); // 假设生成的用户ID为1// 设置 Location 头指向新资源的 URIHttpHeaders 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	需要添加自定义响应头时

---

关键总结

1. 状态码控制：
   • ResponseEntity 直接指定状态码（如 HttpStatus.CREATED）。
   • @ResponseStatus 在异常类上定义默认状态码。
2. 响应头管理：
   • 通过 HttpHeaders 对象添加任意头信息。
3. 异常处理：
   • 自定义异常 + @ResponseStatus：针对特定异常返回状态码。
   • @ControllerAdvice：全局统一处理异常，返回结构化错误信息。
4. 最佳实践：
   • 使用 ResponseEntity 精确控制响应细节。
   • 通过 ErrorDetails 统一错误响应格式。
   • 对于常见 HTTP 状态码（如 404、500），优先使用标准枚举值。