跳到主要内容
约 7 分钟3 张卡

Spring MVC 参数解析

Spring MVC 参数解析是把 HTTP 请求里的路径、查询参数、请求头和请求体,转换成 Controller 方法参数的过程。Controller 能直接拿到一个 long id 或一个填好字段的 DTO,靠的就是它。这个过程里有三处容易出错:值转不成目标类型,转出来的值违反约束,请求或响应的格式对不上。分清错误发生在哪一步,才能解释为什么有的请求返回 400,有的返回 415 或 406。下文以 Spring 6.2 为准。

1. 面试核心​

先记住这几条,再读正文
  • @RequestBody 通过 HttpMessageConverter 按目标类型和 Content-Type 读取请求体,读出对象后再由 @Valid 触发校验。卡 · 参数来源注解
  • 输入转换不成目标类型是绑定错误,转换成功但违反字段约束是校验错误。
  • Spring MVC 6.1 起内置方法校验,方法参数直接声明约束时可触发这条路径,失败可抛出 HandlerMethodValidationException。卡 · 方法校验
  • 请求媒体类型不受支持时默认返回 415,请求体解析失败时默认返回 400。卡 · Content-Type 与 Accept
  • Accept 和服务端能生成的响应媒体类型没有交集时,返回 406。

2. 参数来源注解​

参数注解告诉 MVC 从请求的哪个位置取值。来源写明白了,API 文档能对上,出错时也能直接定位到具体字段:

@PostMapping(path = "/orders/{id}", consumes = "application/json")
OrderResponse update(
@PathVariable long id,
@RequestParam(defaultValue = "false") boolean dryRun,
@RequestHeader("If-Match") String version,
@Valid @RequestBody UpdateOrderRequest request) {
return service.update(id, version, dryRun, request);
}

update 的四个参数来自四个不同的地方:

  • @PathVariable 从路径模板 /orders/{id} 里读出 id。
  • @RequestParam 读取查询参数 dryRun,没传时用 false;它也能读 Servlet 表单参数。
  • @RequestHeader 从 If-Match 请求头读出 version。
  • @RequestBody 把 JSON 请求体读成 UpdateOrderRequest 对象。

读取请求体的是消息转换器(HttpMessageConverter),它负责在 HTTP 消息体和 Java 对象之间互相转换,比如用 Jackson 把 JSON 转成对象。

@ModelAttribute 走的是另一条路:它用数据绑定器把一个个请求参数填进对象的属性,适合查询条件和表单。和读取 JSON 请求体的 @RequestBody 不是同一套解析逻辑。

3. 绑定失败与校验失败​

绑定错误是输入无法转换或填入目标对象,校验错误是已经得到的值违反了约束。比如 quantity=abc 转不成整数,属于前一种;quantity=-1 能转成整数,却不满足下面的 @Positive 正数约束,属于后一种。

record UpdateOrderRequest(
@NotBlank String address,
@Positive int quantity) {}

字段上的这些约束由 Bean Validation 检查,项目里要引入它的实现(比如 Hibernate Validator)。写了 @Valid @RequestBody 后,MVC 先把请求体读成对象,再执行校验。address 上有 @NotBlank,所以空值和全是空白的字符串都通不过。

没有触发方法校验时(见第 5 节),MVC 单独校验这个对象参数,失败就抛出 MethodArgumentNotValidException。如果紧跟在这个参数后面声明一个 BindingResult 参数,异常就不会抛出,错误交给 Controller 自己读取。这时要先检查结果,通过了再调用业务方法,否则无效数据会直接进入业务逻辑。

错误响应要区分转换失败和约束失败,带上字段名、被拒绝的值的类型和稳定的错误码。内部异常类名只留在服务端日志里。响应格式见 API 错误契约。

4. 请求 DTO​

请求 DTO 是专门接收某个操作输入的数据对象,只声明客户端允许修改的字段。如果直接用持久化实体接收请求,status、ownerId 这类内部字段也会被客户端改写;实体跟着数据库模型变化时,API 也会被牵连。所以应该用 DTO 接收,在 service 里显式映射字段,同时检查权限和业务状态。

设计请求 DTO 还要注意几个边界:

  • 嵌套对象上要加 @Valid,校验器才会继续检查它内部的字段,这叫级联校验。
  • 字符串长度、集合大小和金额范围都要设上限,否则格式合法但体量巨大的输入也能耗尽资源。
  • 使用 @ModelAttribute 时,可以用 allowedFields 限定数据绑定器允许写入哪些属性。

5. 方法校验​

方法校验是检查方法参数和返回值上的约束。它既能检查 page 这样的简单参数,也能通过 @Valid 继续检查 DTO 内的字段。Spring MVC 6.1 起内置了这条校验路径,例如下面的方法直接在 page 上声明 @Min(1):

@GetMapping("/orders")
List<OrderResponse> list(@RequestParam @Min(1) int page) {
return service.list(page);
}

请求 page=0 时,MVC 抛出 HandlerMethodValidationException,默认返回 400。返回值约束校验失败则说明服务端返回了不符合约定的结果,默认返回 500。

如果 Controller 类上加了 @Validated,方法校验就会改走 AOP 代理,而不是 MVC 内置的这条路径。想用内置校验,就去掉这个类级注解;service 层仍然可以通过 @Validated 使用代理校验。对象校验和方法校验抛的是不同异常,统一异常处理要把两种都覆盖到。

@Valid 只表示要级联校验,它本身不要求非空;需要禁止空值时要加 @NotNull。@Validated 则还能指定校验组。

6. Content-Type 与 Accept​

内容协商是确定请求和响应使用哪种媒体类型(比如 application/json)的过程。请求头 Content-Type 声明请求体是什么格式,Accept 声明客户端能接受什么格式的响应。

Controller 上的 consumes 限定能接收的请求格式,produces 限定能返回的响应格式。MVC 再结合已注册的消息转换器,判断能不能读取或写出。失败发生在不同阶段,默认状态码也不同:

请求或响应条件默认结果
请求类型与 consumes 不符,或没有支持的读取器415
已选择 JSON 读取器,但 JSON 语法或值类型错误400
必需的请求体缺失400
响应类型与 Accept 无交集406

区分 415 和 400 的关键是有没有选中读取器。415 表示请求的媒体类型和映射条件或转换器的支持范围对不上,连读取器都没选出来。选中了 JSON 读取器、读的时候才发现语法错或类型不对,抛出的是 HttpMessageNotReadableException,默认对应 400。如果格式协商已经成功,是服务端在序列化响应时失败,那属于写出错误,不归这几类。

API 要写明支持哪些媒体类型和字符编码。响应格式按声明好的协商规则选择,不要让 URL 后缀或任意的用户参数改变输出类型。

7. 自定义参数解析器​

HandlerMethodArgumentResolver 是 MVC 将请求转换成方法参数的扩展接口。多个接口都需要当前用户、租户或分页对象时,可以用它集中处理取值规则。supportsParameter() 判断某个参数归不归它处理,resolveArgument() 负责取值和转换。

匹配范围要限定在专用注解或专用类型上。如果它声称能处理所有 String 参数,无关的参数也会被它接管。解析失败时,返回稳定的客户端错误,方便调用方修正请求。

解析器通过 WebMvcConfigurer.addArgumentResolvers() 注册。当前用户和租户身份要从可信的认证上下文里取,不能把请求里客户端自报的身份直接当作认证结果。

8. 常见问题​

8.1 创建和更新要共用一个 DTO 吗?​

可以共用,但要看输入字段和规则有多大差异。@Validated 可以指定创建、更新等校验组,让同一个对象按不同规则校验。但组分得太多,就很难看出某个操作实际执行了哪些约束。创建和更新的规则差别较大时,拆成各自独立的 DTO 更好维护。

8.2 字段校验通过后,还需要检查业务权限吗?​

9. 面试题卡片​

10. 参考资料​

来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明