Skip to content

Web 层:REST 控制器、参数校验与统一异常处理 ​

本篇要点:把一条下单接口做到「错误只有一种形状、校验在入口拦下、跨域和拦截器不互相拆台」。前置:《Spring Boot 4 起步:自动配置、起步依赖与模块化》已经能把 Boot 4 应用跑起来,这一章往里面填接口。

为什么需要它 ​

2026 年 1 月,前端同事拿着联调记录找我:同一个服务的下单接口,他要写四个分支才能判断成功与否。

  • 参数没传,返回 400,body 是框架默认错误体——字段名还跟着版本和 spring.mvc.problemdetails.enabled 变,前端只能猜。
  • 库存不足,业务代码 return 了 {"code":500,"msg":"库存不足"},HTTP 状态是 200。
  • 金额格式不对,抛 NumberFormatException,返回 500;浏览器直接访问看到的是 Whitelabel 错误页,Accept 是 JSON 时又是一段默认错误体。
  • 校验失败,返回 400,body 是 {"errors":[{"field":"qty","message":"must be greater than 0"}]}。

四种形状对应四个解析分支,try/catch 里 JSON.parse 两次。更难办的是第二个:HTTP 200 意味着成功,网关不会重试,监控不会报警,错误只在用户的截图里出现。

同一周还出了两件事。orderNo 传了空字符串,一路写进库,因为接口上没有任何校验;安卓端调上传接口,预检请求 OPTIONS 直接被 403,因为跨域配置只写在了 @PostMapping 方法上。

这三个问题都属于 Web 层的同一段路:请求怎么进来、参数怎么验、错误怎么出去。单个都不难,但会以几乎相同的形式在每个项目里重来一遍。

核心概念 ​

控制器与参数绑定:请求怎么落到方法上 ​

@RestController 等于 @Controller 加 @ResponseBody,方法返回值走消息转换器(HttpMessageConverter)写成 JSON,而不是被当成视图名去渲染。参数绑定是把请求里不同位置的数据映射到方法参数上。

注解取值位置典型场景容易写错的地方
@PathVariableURL 路径段/orders/{orderNo}名字要和占位符一致
@RequestParamquery 串或表单字段分页、筛选默认必填,要 required=false 才能省
@RequestBody请求体JSON 格式的 DTO一个方法只能有一个
@RequestHeader请求头租户、客户端版本头名大小写不敏感
@ModelAttribute表单字段绑对象后台表单与 JSON 提交互斥

反例:在一个参数上同时用 @RequestBody 和 @ModelAttribute,或者在方法上写两个 @RequestBody。前者启动时就会失败,后者要到第一次请求才抛 HttpMessageNotReadableException,症状是「明明传了 JSON 却读不到值」。

Bean Validation:两个校验入口,两种异常 ​

Bean Validation(jakarta.validation)是 Jakarta EE 的校验规范,实现通常是 Hibernate Validator。Spring 负责在参数绑定完成之后、控制器方法执行之前触发校验。问题在于入口有两个,失败的异常不是同一个:

  • 请求体或表单对象上的约束,写法是 @Valid @RequestBody OrderCreateReq req,失败抛 MethodArgumentNotValidException。
  • 方法参数上的约束,写法是 @RequestParam @Min(1) int page,需要类上加 @Validated 才生效,失败抛 ConstraintViolationException。

第一个异常有默认处理,会变成 400;第二个没有任何默认处理器接管,直接变成 500。两个入口,两种异常——这个差别是新手最容易卡住的地方:同样是「校验没过」,一个 400 一个 500,你会以为后者是代码 bug,于是去翻控制器,而问题在类上少了一个注解。

判断方法很简单:看这个参数是从哪来的。从请求体反序列化出来的对象,校验失败归 MethodArgumentNotValidException;直接从 URL 或请求头取出来的单个值,校验失败归 ConstraintViolationException。

全局异常处理与统一响应体 ​

@RestControllerAdvice 是带 @ResponseBody 的 @ControllerAdvice,里面用 @ExceptionHandler 把异常类型接到方法上,由 ExceptionHandlerExceptionResolver 执行,位置在参数解析与校验之后、响应写出之前。

统一响应体有两种做法,必须挑一种并全项目执行:

  1. 所有接口都包一层 {"code":0,"data":...,"message":""},HTTP 状态永远是 200。
  2. 用 HTTP 状态码表达结果,错误体用一种固定结构。

这一章选第二种。理由是第一种会让网关重试、监控告警、浏览器缓存、CDN 全部失真——《配置与可观测性:Profiles、Actuator 与 Micrometer》的指标按状态码分桶,200 的错误全落在成功那一桶里。固定结构用 Spring Framework 6 起内建的 ProblemDetail,格式按 RFC 9457,字段是 type、title、status、detail、instance,还能挂自定义属性。

内容协商、文件上传、跨域与拦截器 ​

内容协商(content negotiation):客户端用 Accept 头说明要什么格式,服务端用 produces 说明能给什么,对不上返回 406。比如客户端发 Accept: application/xml,接口只声明了 produces = "application/json",浏览器拿到的是 406,而不是任何一段业务代码的返回值——这条路径不经过控制器,排查时别在业务日志里找。

文件上传:Servlet 侧拿到的是 MultipartFile,大小限制在 spring.servlet.multipart.max-file-size 与 max-request-size,超限抛 MaxUploadSizeExceededException,需要自己映射成 413。getOriginalFilename() 是客户端给的,可以带路径分隔符和 ..,落盘前必须自己生成文件名,原始名只存进数据库做展示。

跨域(CORS,Cross-Origin Resource Sharing):浏览器对跨域的非简单请求会先发一个 OPTIONS 预检(preflight),服务端用 Access-Control-Allow-Origin 等响应头放行。Spring 给两种写法:@CrossOrigin 粒度细、容易漏,WebMvcConfigurer.addCorsMappings 集中、推荐。

拦截器(HandlerInterceptor)有三个回调:preHandle 在控制器方法之前,返回 false 即中断;postHandle 在方法返回后;afterCompletion 在请求完成后,异常也会走到这里。它只对「匹配到 Handler 的请求」生效,404 请求走不到 preHandle;preHandle 返回 false 时,afterCompletion 也不会执行。

如图 3-1 所示,请求在 Web 层里要穿过 Filter、拦截器、参数绑定三道关卡,而三类异常最后都汇到同一个 advice 节点上,这是「错误只有一种形状」能成立的结构原因。

图 3-1 请求在 Web 层的路径与三类异常的汇合点

动手实践 ​

依赖三个:spring-boot-starter-web、spring-boot-starter-validation、spring-boot-starter-test。基线是 Boot 4.1.x(截至 2026 年 11 月),Java 17 起。

第一步:控制器写对,先看校验的两个表现 ​

代码 3-1 是一条下单接口。注意类上的 @Validated 只为了让方法参数上的 @Min 生效,请求体那条路不需要它。

java
package com.example.web;

import java.math.BigDecimal;
import java.util.List;

import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Positive;

import org.springframework.http.HttpStatus;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@Validated
@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService service;

    public OrderController(OrderService service) {
        this.service = service;
    }

    @GetMapping("/{orderNo}")
    public OrderView get(@PathVariable String orderNo) {
        return service.find(orderNo);
    }

    @GetMapping
    public List<OrderView> list(@RequestParam(defaultValue = "1") @Min(1) int page,
                                @RequestParam(defaultValue = "20") @Min(1) int size) {
        return service.list(page, size);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public OrderView create(@Valid @RequestBody OrderCreateReq req) {
        return service.create(req);
    }

    public record OrderCreateReq(@NotBlank String sku,
                                 @NotNull @Positive Integer qty,
                                 @NotNull BigDecimal amount) {
    }

    public record OrderView(String orderNo, String sku, int qty) {
    }
}

预期输出(正常下单一次):

$ curl -s -i -X POST localhost:8080/api/orders -H 'Content-Type: application/json' \
    -d '{"sku":"SKU-1","qty":2,"amount":99.00}'
HTTP/1.1 201
Content-Type: application/json

{"orderNo":"SO202611160001","sku":"SKU-1","qty":2}

再看方法参数校验失败的那条路,只取状态码,预期输出:

$ curl -s -o /dev/null -w '%{http_code}\n' 'localhost:8080/api/orders?page=0'
500

500 不是 400,这就是 ConstraintViolationException 没有处理器的结果,日志里才是真正的原因:

jakarta.validation.ConstraintViolationException: list.page: 必须大于或等于 1

请求体校验失败那条路是 400,但错误体里只有一段通用描述,没有字段名。两条路都要在下一步接管。

第二步:把三类异常收成一个形状 ​

代码 3-2 继承 ResponseEntityExceptionHandler,它已经把框架内置的异常映射成了 ProblemDetail,只需要覆写想改的那个;业务异常和参数校验异常各挂一个 @ExceptionHandler。其中 BusinessException 是自定义异常,只有两个字段:code(字符串,给前端做分支)和 status(HttpStatus,决定 HTTP 状态码)。业务代码里 throw new BusinessException("OUT_OF_STOCK", HttpStatus.CONFLICT, "库存不足"),出去就是 409。

java
package com.example.web;

import java.net.URI;
import java.util.LinkedHashMap;
import java.util.Map;

import jakarta.validation.ConstraintViolationException;

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.multipart.MaxUploadSizeExceededException;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    // 业务异常:BusinessException 自带 code 与 HttpStatus
    @ExceptionHandler(BusinessException.class)
    public ProblemDetail onBusiness(BusinessException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(ex.status(), ex.getMessage());
        pd.setTitle("业务规则不满足");
        pd.setType(URI.create("https://mqxu.top/errors/" + ex.code()));
        pd.setProperty("code", ex.code());
        return pd;
    }

    // 方法参数校验失败:@RequestParam 上的 @Min 撞的是这个
    @ExceptionHandler(ConstraintViolationException.class)
    public ProblemDetail onConstraint(ConstraintViolationException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "参数校验失败");
        pd.setTitle("请求参数不合法");
        Map<String, String> errors = new LinkedHashMap<>();
        ex.getConstraintViolations().forEach(v ->
                errors.put(v.getPropertyPath().toString(), v.getMessage()));
        pd.setProperty("errors", errors);
        return pd;
    }

    // 请求体校验失败:覆写框架已有的处理,只加一个 errors 属性
    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex, HttpHeaders headers,
            HttpStatusCode status, WebRequest request) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "参数校验失败");
        pd.setTitle("请求参数不合法");
        Map<String, String> errors = new LinkedHashMap<>();
        for (FieldError fe : ex.getBindingResult().getFieldErrors()) {
            errors.putIfAbsent(fe.getField(), fe.getDefaultMessage());
        }
        pd.setProperty("errors", errors);
        return ResponseEntity.badRequest().body(pd);
    }

    // 上传超限单独映射成 413,别让它落进 500
    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public ProblemDetail onTooLarge(MaxUploadSizeExceededException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
                HttpStatus.PAYLOAD_TOO_LARGE, "文件超过上传上限");
        pd.setTitle("文件过大");
        return pd;
    }
}

预期输出:

$ curl -s -i -X POST localhost:8080/api/orders -H 'Content-Type: application/json' \
    -d '{"sku":"","qty":0,"amount":99.00}'
HTTP/1.1 400
Content-Type: application/problem+json

{"type":"about:blank","title":"请求参数不合法","status":400,"detail":"参数校验失败","errors":{"sku":"不能为空","qty":"必须大于 0"}}
$ curl -s -o /dev/null -w '%{http_code}\n' 'localhost:8080/api/orders?page=0'
400

消息文案取自 ValidationMessages_zh_CN,英文环境会换成 must not be blank 这类默认文案。第二个请求从 500 变成 400,就是 onConstraint 接管的证据。注意 Content-Type 变成 application/problem+json——这是 ProblemDetail 的默认序列化类型,前端可以直接按 RFC 9457 解析,不用再约定私有结构。

第三步:跨域与拦截器,谁先谁后 ​

代码 3-3 把 CORS 和拦截器一起配。跨域集中配在 WebMvcConfigurer,拦截器只做租户上下文,afterCompletion 负责清理。

java
package com.example.web;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("https://admin.mqxu.top")   // 带凭据时不能写 "*"
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowedHeaders("Content-Type", "Authorization")
                .allowCredentials(true)
                .maxAge(3600);
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new TenantInterceptor())
                .addPathPatterns("/api/**")
                .excludePathPatterns("/api/health");
    }

    static class TenantInterceptor implements HandlerInterceptor {

        @Override
        public boolean preHandle(HttpServletRequest req, HttpServletResponse resp, Object handler) {
            String tenant = req.getHeader("X-Tenant-Id");
            if (tenant == null || tenant.isBlank()) {
                resp.setStatus(400);
                return false;   // 中断:控制器不执行,afterCompletion 也不会走
            }
            TenantContext.set(tenant);   // ThreadLocal 持有,交给下游读取
            return true;
        }

        @Override
        public void afterCompletion(HttpServletRequest req, HttpServletResponse resp,
                                    Object handler, Exception ex) {
            TenantContext.clear();   // 线程池会复用线程,不清理就会串租户
        }
    }
}

预期输出,先看预检:

$ curl -s -i -X OPTIONS localhost:8080/api/orders \
    -H 'Origin: https://admin.mqxu.top' -H 'Access-Control-Request-Method: POST'
HTTP/1.1 200
Access-Control-Allow-Origin: https://admin.mqxu.top
Access-Control-Allow-Methods: GET,POST,PUT,DELETE
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 3600

再看拦截器拦下的请求,故意不带租户头:

$ curl -s -o /dev/null -w '%{http_code}\n' localhost:8080/api/orders/SO202611160001
400

400 是 preHandle 直接写的,body 为空,控制器里那行查库日志不会出现。如果把它换成 302 跳到登录页,postHandle 不执行但浏览器行为正常;换成 401 就得同时在响应体里写错误结构,否则前端拿不到 code。这一步的顺序也解释了一个常见现象:预检请求在 Filter 层就被 CorsFilter 或 Boot 的 CORS 处理结束,根本进不到拦截器,所以「拦截器里做鉴权」对 OPTIONS 是无效的,只在 Filter 里能拦住。

选拦截器而不是 Filter 做租户判断,理由只有一个:拦截器能拿到 HandlerMethod,可以读方法上的注解,做「这个接口要不要租户」这类判断;Filter 的参数里没有 Handler,只能按路径通配。反过来说,需要读请求体、需要改写请求包装(比如解密、签名校验)的时候,拦截器已经太晚,只能回到 Filter。

常见误解 ​

很多人以为 @Valid 加在任何参数上都生效。实际上 @RequestParam、@PathVariable 上的约束需要类级 @Validated,漏了不会报错,只是完全不校验,脏数据照样进库——这个误解的代价不在编译期,在三个月后的数据修复。顺带一个变化:不加 @Validated 时,Spring Framework 6.1 起 MVC 会自己校验方法参数,抛的是 HandlerMethodValidationException,默认 400;加了 @Validated 走的是 AOP 那条路,抛 ConstraintViolationException,默认 500。两个异常的类名、状态码、错误体形状都不同,排查前先确认自己站在哪条路上。

很多人以为统一响应体就是「全部包一层 {code,msg,data},HTTP 都返 200」。实际上它会把 HTTP 语义清空:网关不再按 5xx 重试,监控不再按状态码告警,浏览器和 CDN 缓存不再按状态区分,ProblemDetail 也失去意义。错误就该用 4xx 和 5xx,code 只用来区分同一种状态码下的不同原因。

很多人以为加上 @CrossOrigin 跨域就成了。实际上预检走 Filter,如果鉴权过滤器不放行 OPTIONS,预检先被拦掉,浏览器报的是 CORS 错误,日志里却是 401,两边对不上;allowCredentials(true) 配 allowedOrigins("*") 时启动就抛 IllegalArgumentException。跨域配置集中在一处,要么全在应用里,要么全在网关里,别两边各写一半。

小结 ​

  • @RestController 是 @Controller 加 @ResponseBody;路径、查询、请求体、请求头各有一个绑定注解,别混用,也别在一个方法上写两个 @RequestBody。
  • 校验有两个入口、两种异常:请求体走 MethodArgumentNotValidException,方法参数走 ConstraintViolationException 且需要类级 @Validated。后者默认是 500,必须自己接管。
  • 错误体用 ProblemDetail(RFC 9457),Content-Type 是 application/problem+json;状态码表达结果,别用 200 包错误。
  • 内容协商靠 Accept 与 produces,对不上是 406;上传上限在 spring.servlet.multipart 下,超限自己映射成 413。
  • 执行顺序是 Filter → preHandle → 参数绑定与校验 → 控制器 → postHandle → afterCompletion;preHandle 返回 false 时 afterCompletion 不执行,ThreadLocal 要在 preHandle 里才 set。

相关主题 ​

接口有了形状,数据还得从库里来。《数据访问:JdbcTemplate、Spring Data JPA 与 jOOQ》讲三条数据访问路线:JdbcTemplate、Spring Data JPA、jOOQ 各自的边界在哪里,实体该怎么建模,以及为什么在列表接口里随手补一次关联查询,就会变成 N+1。