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. 关键注解与类说明

5. 场景总结表格

关键总结

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