外观
15 - Controller 参数从哪里来:参数解析、数据绑定与请求体转换
适用版本:Spring MVC 6.x。JSON 示例通常依赖 Jackson,具体模块版本由项目依赖管理决定。
前置阅读:14 - DispatcherServlet 调度全流程。本文假设 Handler 已经匹配,聚焦调用 Controller 之前如何得到每一个方法参数。
摘要
前端传了参数,Controller 却得到 null;数字转换失败返回 400;过滤器(Filter)读过请求体后,@RequestBody 无法再读取内容。这些现象发生在不同阶段,不能都归为“参数没传对”。
调用 Controller 之前,Spring MVC 要先为每个方法参数选择解析器,再把请求中的数据转换成参数需要的 Java 值或对象,并在适用时执行校验。理解这条链路,就能区分参数来源错误、类型转换失败、请求体不可读和约束不满足。
1. 参数不是由一个组件统一解析
下面是 Controller 方法声明片段,省略导入、DTO 定义和业务实现。@PathVariable、@RequestParam 未显式指定名称时,需要编译产物包含可供框架使用的参数名元数据。
java
@PostMapping("/users/{id}")
User update(
@PathVariable long id,
@RequestParam boolean notify,
@Valid @RequestBody UpdateUser request) { ... }三个参数的来源不同:id 来自路径中的 {id},notify 来自请求参数,request 来自 HTTP 请求体(Body)。路径或查询中的文本不能直接作为 long、boolean 使用,JSON 文本也不能直接作为 UpdateUser 使用,所以找到数据之后还需要转换。
HandlerMethodArgumentResolver 是方法参数解析器:它判断自己是否支持某个参数,并负责得到该参数的值。Spring 按顺序询问解析器,找到支持者后就由它完成解析,这种组织方式称为责任链。图中展示的是不同参数可能走的分支,不是一个参数依次经过所有解析器。
图表将在阅读到此处时加载…
RequestMappingHandlerAdapter 是负责调用注解控制器的适配器,维护一组有序的参数解析器。MethodParameter 描述一个方法参数,包括类型和注解等信息;首个通过 supportsParameter() 声明支持它的解析器(Resolver)负责解析。只有参数准备完成,框架才能调用 Controller 方法。
2. RequestParam 与 ModelAttribute
@RequestParam 通常读取查询参数或表单字段,适合取得单个值;@ModelAttribute 用于把请求参数绑定到对象。数据绑定是把外部输入按名称填入目标对象,并完成所需的类型转换。
例如,字符串 "2" 要先转换为整数,才能赋给整数类型的参数或对象属性。ConversionService(类型转换服务)提供这类转换能力;WebDataBinder(Web 数据绑定器)组织属性访问、类型转换与校验衔接。若收到 "abc",转换无法完成,问题发生在业务使用该值之前。
不要把外部输入直接绑定到持久化实体(Entity,即映射数据库数据的对象)。单独定义请求 DTO(数据传输对象),只声明接口允许接收的字段,可以减少客户端修改内部字段的风险。DTO 的字段设计仍需与接口权限和业务规则一致。
简单值转换失败与对象绑定失败通常会形成不同异常;是否直接返回 400 又取决于参数声明、异常解析器和应用的统一错误处理。排障时应保留目标参数名、目标类型和失败的原始值类型,但不要把密码、令牌等原值写入日志。
3. RequestBody 与 HttpMessageConverter
@RequestBody 的解析器根据 Content-Type(请求体的媒体类型)和目标 Java 类型,选择能读取该内容的 HttpMessageConverter(HTTP 消息转换器)。转换器读取请求体并生成对象;JSON 常由基于 Jackson 的转换器完成。把 JSON 文本还原成 Java 对象的过程称为反序列化。
这与请求参数绑定的入口不同:@RequestParam、@ModelAttribute 处理请求参数,@RequestBody 处理请求体的格式。因此,排查 JSON 字段错误时,应检查消息转换器和 Jackson 配置,而不是只检查请求参数转换服务。
常见失败:
- Content-Type 不正确;
- JSON 语法错误;
- 字段类型不匹配;
- 构造方式或可见性不满足反序列化要求;
- 请求体已被上游组件读取。
Jackson 能否构造 record、不可变对象、日期类型或多态对象,取决于 Jackson 版本、已注册模块和可见性配置。Spring MVC 负责组织请求体转换流程,具体 JSON 绑定能力不能脱离序列化库版本判断。
4. 校验发生在哪里
类型转换回答“能否得到这个类型的值”,校验回答“这个值是否符合规则”。下面是请求 DTO 和 Controller 方法片段,需要相应的 Spring Web、Jakarta Validation 导入、可用的校验实现,以及支持该 record 的 JSON 转换配置。Order 和业务实现需由应用提供。
java
record CreateOrderRequest(
@NotBlank String productCode,
@Positive int quantity) { }java
@PostMapping
Order create(@Valid @RequestBody CreateOrderRequest request) { ... }@Valid 表示需要对对象执行 Bean Validation(基于约束注解的对象校验)。在请求体成功转换为对象、校验器可用的条件下,@NotBlank 要求 productCode 不是空白字符串,@Positive 要求 quantity 大于 0。合法 JSON 中的 quantity: 0 可以完成整数转换,却不能通过这里的约束。
绑定或反序列化失败与校验失败应分开定位:前者无法按要求生成数据,后者是生成的数据不满足约束。统一异常响应应保留字段、拒绝值类型和可读原因,避免暴露敏感原始数据。
如果方法参数后紧跟 BindingResult,应用可以自行处理部分绑定或校验错误;没有对应参数时,框架通常把失败交给异常解析链。BindingResult 是绑定或校验结果的容器,具体可接管的错误取决于参数类型和校验方式;它不能让无效 JSON 成功反序列化。Controller 若接收了它,必须先检查错误,再决定是否执行业务写入。
5. 自定义参数解析器
当接口反复需要“当前用户”这样的 Web 层参数时,可以用自定义解析器封装其获取方式。下面的类片段省略导入,依赖应用定义的 @CurrentUser 注解,并需要注册到 MVC 参数解析器列表中;请求作用域中的 currentUser 应由前置组件设置,且类型应与方法参数一致。
java
public class CurrentUserResolver implements HandlerMethodArgumentResolver {
@Override
public boolean supportsParameter(MethodParameter parameter) {
return parameter.hasParameterAnnotation(CurrentUser.class);
}
@Override
public Object resolveArgument(MethodParameter parameter,
ModelAndViewContainer container,
NativeWebRequest request,
WebDataBinderFactory binderFactory) {
return request.getAttribute("currentUser", RequestAttributes.SCOPE_REQUEST);
}
}这里的 supportsParameter() 只检查注解,resolveArgument() 只读取请求属性,没有完成认证或用户查询。属性不存在时会得到 null,应用需要约定缺失用户信息的处理方式。
解析器适合封装稳定的 Web 层参数语义,不应把复杂业务查询塞进参数解析阶段。匹配范围应尽可能精确,例如结合注解和目标类型判断;若自定义解析器排在某个内置解析器之前且同时支持该参数,就可能改变原有解析路径。
6. 请求体为什么不能随便读两次
Servlet 是处理 HTTP 请求的服务端 API,请求体通常以输入流形式提供。读取会推进流的位置;Filter 若先读完,后续转换器面对的就是已耗尽的流,而不是另一份请求体。
ContentCachingRequestWrapper 是请求包装器,会在内容被读取时缓存这些字节,便于后续记录,但它并不会自动让后续组件重新读取一个已被 Filter 提前耗尽的输入流。若 Filter 必须先读取再把请求交给下游,需要实现真正保存字节并为后续调用重新提供输入流的 wrapper,或使用框架中满足该语义的组件。
无论采用哪种方案,都必须限制缓存大小、处理字符编码、避免记录文件上传,并对密码、令牌和个人信息脱敏。请求体日志功能本身也可能造成内存放大和延迟。
7. 分阶段复现失败
以下是订单创建场景的预期失败示例。请求体校验采用第 4 节的 DTO;查询参数转换用例需要接口另行声明整数类型的 quantity 请求参数,不能只在 URL 中添加同名字段就认为它会绑定到 JSON DTO。接口应已成功匹配,JSON 转换器与校验器应已配置;统一异常处理可能改变表中的常见状态码。
表中 quantity=0 指 JSON 请求体中的数值字段;媒体类型用例还需区分映射条件与转换器选择:
| 请求 | 预期失败阶段 | 常见结果 |
|---|---|---|
quantity=abc 查询参数 | ConversionService / DataBinder | 400 |
| JSON 缺少右括号 | HttpMessageConverter 读取 | 400 |
quantity=0 且带 @Positive | Bean Validation | 400 |
Content-Type: text/plain 但只接受 JSON | 若映射已通过,则检查 Converter 选择;若声明了 JSON consumes,可能先在映射阶段失败 | 415 |
| Filter 提前读完 Body | Converter 读取 | 空请求体或 400 |
测试时结合异常类型断言具体错误码、适用的字段路径,以及业务方法是否被调用。没有 BindingResult 接管错误等条件下,参数准备失败通常会阻止 Controller 方法执行;若应用自行接管校验错误,则需检查错误分支是否阻止了业务写入。仅断言“不是 200”无法证明失败阶段。
8. 容易踩的坑
- DTO 中仅凭基本类型字段的值,无法区分“未传”和“传了 0/false”;若接口需要区分,应设计相应的缺失值表达和校验规则。
- 参数名依赖编译元数据,却未显式写注解 value。
- 自定义 Converter 全局生效,误伤其他接口。
- 校验分组过度复杂,使接口规则难以理解。
- 将反序列化失败和 Bean Validation 失败合并成不可区分的错误码。
9. 排障清单
- 根据参数的注解和目标类型,哪个 ArgumentResolver 首先声明支持它?
- 原始请求的 Path、Query、Header、Content-Type 和 Body 是什么?
- 失败发生在读取、反序列化、绑定、转换还是校验?
- 请求体是否被 Filter 提前消费?
- DTO 与线上实际 JSON 结构是否一致?
- 自定义 Resolver 或 Converter 是否改变了默认处理路径?
- Jackson、Validation 及相关模块的实际版本是什么?
- 业务方法是否已经执行,还是在参数准备阶段就已失败?
10. 总结
Controller 参数解析是一条按参数类型分派的责任链,不同来源应从不同组件定位。
- ArgumentResolver 决定参数从哪里来。
- WebDataBinder 负责属性绑定与转换,HttpMessageConverter 负责请求体格式转换。
- 请求体、校验和日志处理都要考虑安全与可重复读取边界。
阅读导航
- Handler 如何被选中:14 - DispatcherServlet 调度全流程
- 参数生成后的响应阶段:16 - 返回值、JSON 与统一异常处理
- 请求体读取与 HTTP 语义:网络 12 - HTTP 连接复用与协议演进
- 跨层故障分诊:20 - Spring 线上问题排查手册