Spring MVC处理HTTP状态码、响应头和异常的完整示例

2025-08-21 10:35:32 作者：爱的叹息

Spring MVC 是 Spring 框架中的一个模块,专门用于构建基于 MVC（Model-View-Controller）架构的 Web 应用程序,其核心在于处理 HTTP 请求并将其映射到相应的控制器方法,本文给大家介绍了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），优先使用标准枚举值。

以上就是Spring MVC处理HTTP状态码、响应头和异常的完整示例的详细内容，更多关于Spring MVC处理HTTP的资料请关注脚本之家其它相关文章！