后台接口明明写好了，前端一调却报400；Postman里测得好好的，换成axios就传不过去；URL上明明带了一堆参数，后端一接却收到null……这类问题在Spring开发里太常见了。Spring请求参数传递，说到底是“把HTTP请求里各个位置的数据映射到Controller方法形参上”这件事。看起来很简单，但它牵扯到URL结构、Content-Type、消息转换、类型转换多个环节，任何一个地方对不上，表现就是各种千奇百怪的报错。
我见过不少同事在这个问题上反复折腾，也见过前端同学对着接口文档一脸茫然：到底该把参数放在params里还是data里，后端用的是@RequestParam还是@RequestBody，这两种情况下前端写法完全不同。下面我按传参方式拆开讲，配实操代码和踩坑案例，把Spring的参数传递机制一次说清楚。
1. 先从HTTP请求本身说起：参数的四个“住处”你都知道吗
1.1 请求行、请求头、请求体到底各管什么
在Spring里谈参数传递，绕不开HTTP请求的三个基本组成部分。以POST /api/users?id=1024 HTTP/1.1为例，请求行就是第一行，包含方法（POST）、目标URL（/api/users?id=1024）和协议版本。请求头是紧随其后的键值对，比如Content-Type: application/json、Accept: application/json、Authorization: Bearer xxx。请求体是请求行之后、空行之后的那段内容，POST和PUT这类方法通常会携带请求体。
既然标题写了Java EE，这里插一句背景：无论你用的是Spring MVC还是Spring Boot，底层跑的还是Servlet容器，DispatcherServlet最终面对的就是一个实现了HttpServletRequest接口的对象。请求行、请求头、请求体这三块信息，都能从HttpServletRequest上拿到——getRequestURI()拿URL、getHeader()拿头、getInputStream()拿体。理解这一层，后面看@PathVariable、@RequestParam这些注解时就不会觉得它们各自为政了，它们本质上是Spring帮你从同一个HttpServletRequest里取数据的快捷方式。
1.2 URL上能放参数的四个位置
抛开请求头里的Token、Session之类的“元信息”，真正的业务参数其实只出现在四个位置：
| 参数位置 | 真实请求长什么样 | Spring对应注解 |
|---|---|---|
| URL路径段 | /users/1024/orders/99 | @PathVariable |
| URL查询串 | /users?page=1&size=20 | @RequestParam |
| 表单体 | name=张三&age=18 | @RequestParam / @ModelAttribute |
| JSON/XML体 | {"name":"张三","age":18} | @RequestBody |
可以先做个简单的判断：参数在URL上还是在请求体里？在URL上时，是在路径段里还是在问号后面？在请求体里时，是普通的键值对形式还是JSON字符串？把这四个问题分清，80%的参数传递问题都已经解决了。
1.3 一个常见误区：“POST的参数就一定要写在body里”
很多新手默认GET参数在URL、POST参数在body，这其实是个误区。POST请求的URL上同样可以带查询参数，例如POST /api/users?operator=admin，请求体里再放{"name":"张三"}，两者互不干扰。反过来，Spring能不能把这两处的参数都接收呢？能——operator用@RequestParam收，请求体用@RequestBody收，Controller方法可以同时出现这两个注解。
真正决定参数该放body还是URL的不是HTTP方法本身，而是接口约定的业务语义。举个例子：移动端的日志上报接口，可以把客户端版本、设备号放在URL查询串里用于网关识别，把日志正文放到请求体里；这时POST方法的URL照样有参数，后端也用@RequestParam收版本号，用@RequestBody收日志正文。搞清楚这一点，前端就不会再把query参数塞进data里。
2. 路径参数实战：@PathVariable的常规用法与版本差异
2.1 基本用法与参数名映射
REST风格接口最常见的传参方式就是把资源ID放在URL路径里，比如“查询id为1024的用户”，URL是GET /api/users/1024。Controller里的写法：
@RestController @RequestMapping("/api/users") public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService = userService; } @GetMapping("/{id}") public User getUserById(@PathVariable("id") Long id) { return userService.findById(id); } }建议显式写@PathVariable("id")而不是偷懒写成@PathVariable Long id。为什么？参数名推断依赖编译时加了-parameters参数，很多项目没配，一旦编译后形参名被丢弃或变成arg0，Spring就找不到对应关系，接口直接报“Missing URI template variable”。显式写名字虽然啰嗦，但避免了这种不确定性。如果你的项目是用Maven构建的，也可以在maven-compiler-plugin里勾上-parameters，这样方法参数名在字节码里得以保留，写代码时可以省略注解里的名字，但团队协作时还是建议保持显式，降低沟通成本。
2.2 一个容易被忽略的版本差异：路径匹配器的变化
路径变量有一个进阶用法，是用正则把路径模板“框”起来。早期版本里可以这么写：
@GetMapping("/users/{id:\\d+}") public User getUserById(@PathVariable Long id) { ... }它在AntPathMatcher时代是有效的，{id:\\d+}表示id这一段必须是数字。但从Spring Boot 2.6开始，默认的路径匹配策略改成了PathPatternParser，对这类正则路径模板的支持方式和以前不完全一样，原来一些合法的写法可能直接报错。我的建议是：不要在URL模板里做业务校验。URL的作用是“指明资源在哪”，至于id是不是数字、有没有非法字符，请在方法内部校验，或者让全局异常处理器兜底，这样既避免版本兼容问题，也让错误提示可控。
2.3 路径参数的边界条件与最佳实践
路径参数有几个容易踩的边界：
- 路径变量默认匹配到下一个
/为止。如果某个段位本身需要包含斜杠，比如要传一个多级目录路径，单个{path}是接不住a/b/c的，一般需要改用{*path}这样的多段通配写法，或者干脆把这类场景换成查询参数、请求体来传。 - 中文或特殊字符放路径里时，前端通常会对URL做编码，例如中文变成
%E5%BC%A0%E4%B8%89。Spring在解析PathVariable时会帮你解码，拿到的是正常字符。但如果前端没有编码，或者链路里有网关、Nginx对URL又做了一层处理，很可能出现乱码或404。遇到这种情况，先看浏览器Network面板里真实发出的URL是什么形态。 - 同一路径下尽量不要出现“一个占位符、一个不占位”的模糊匹配，比如
/api/users/{id}和/api/users/me同时存在，不同版本Spring对这类路由的匹配优先级处理有差异，容易产生诡异的结果。me这种固定静态路径建议单独设计，或者放在其他路径段下。
3. 查询参数实战：@RequestParam的必填、默认值与多值处理
3.1 注解的三个核心属性
查询参数在URL问号后面，典型场景是列表接口的分页和筛选：GET /api/users?page=1&size=20&keyword=java。Spring用@RequestParam接收：
@GetMapping("/api/users") public Result list(@RequestParam("page") Integer page, @RequestParam(value = "size", defaultValue = "20") Integer size, @RequestParam(value = "keyword", required = false) String keyword) { return userService.pageQuery(page, size, keyword); }这里面有三个属性值得说清楚。
required默认值是true，也就是说参数必须出现，否则Spring直接报400（MissingServletRequestParameterException）。如果你的接口允许不带某个字段，一定要记得标required = false。
defaultValue和required = false经常一起出现，它们有细微差别：设了defaultValue后，即使请求里没有这个参数，形参也会被赋默认值；只设required = false时，缺失的参数是null，需要自己在代码里做空判断。
还有一点常被忽略：前端传了空字符串?keyword=，Spring会把空字符串当作一个合法值绑定到keyword上，这跟参数缺失是两回事。很多“参数怎么判断为空”的Bug就出在这——有人用StringUtils.isEmpty判断没问题，但如果有@RequestParam(required = false) Integer age这种写法，空字符串转Integer会失败抛类型转换异常。所以前后端约定时尽量明确“空字符串即视为没传”并做统一处理。
3.2 同名多值与Map兜底接收
查询参数不一定是“一名一值”。比如一次想按多个标签筛选：GET /api/posts?tag=java&tag=spring&tag=cloud。Controller里收成一个列表：
@GetMapping("/api/posts") public Result list(@RequestParam(value = "tag") List<String> tags) { ... }另一种更灵活的写法是用Map接收全部查询参数：
@GetMapping("/api/search") public Result search(@RequestParam Map<String, String> params) { ... }注意，不加@RequestParam裸写一个Map形参，Spring不会把它当成参数收集器，它会被当作一个普通复杂对象来绑定，结果往往是null。这是新手常踩的坑。用Map接收的好处是接口兼容性高，新增筛选条件不用改方法签名，缺点是类型全成了String，后续要做转换，可读性也差一些。我一般推荐在写通用网关、报表导出这类“参数会频繁变动”的接口时用Map，业务型接口还是老老实实列明确参数。
3.3 和axios GET请求配合时，参数到底放在哪里
前端用axios发GET请求，参数通常放在params配置里：
axios.get('/api/users', { params: { page: 1, size: 20, keyword: 'java' } })axios在浏览器端会把params序列化成查询串拼到URL上；如果你不小心放到data里，浏览器实际发出的GET请求是没有任何参数的，后端自然收到null。另一个高频坑是参数里带了数组，例如tags: ['java', 'spring']，axios默认的序列化结果是tags[]=java&tags[]=spring，后端如果按tag=java&tag=spring那种同名多值方式（即List tags）来接，是接不到的。解决方案是给axios配置自定义paramsSerializer，或者前后端约定好同一个数组参数的传法，比如前端拼成逗号分隔的tags=java,spring，后端用@RequestParam String tags接收后自己split。哪种方式都可以，关键是两边要对齐。
4. 表单绑定实战：@ModelAttribute如何把零散字段拼成对象
4.1 模型绑定的底层原理
传统表单（application/x-www-form-urlencoded）提交的数据长这样：name=张三&age=18&address.city=杭州。当一个Controller方法的形参是一个POJO，没有@RequestBody注解时，Spring走的是模型绑定流程，相当于@ModelAttribute起的效果：
@PostMapping("/api/users") public Result createUser(UserDTO user) { return userService.create(user); }Spring拿到请求参数后，先用反射创建一个UserDTO实例，然后遍历请求参数里的每个键值对，根据属性名调用对应的setter，把字符串值做类型转换后塞进去。这个过程由WebDataBinder驱动，它负责三件事：参数名到属性的匹配、字符串到目标类型的转换、校验与错误收集。这也是为什么@Data、@Setter这类代码生成工具能“凭空”让Spring完成绑定——本质上是它们生成了setter方法。
4.2 嵌套对象、数组与类型转换的细节
嵌套对象的表单怎么写？如果UserDTO里有一个Address address字段，前端表单里字段名要带点：
<input name="name" value="张三" /> <input name="age" value="18" /> <input name="address.city" value="杭州" /> <input name="address.district" value="西湖区" />对应Java对象：
public class UserDTO { private String name; private Integer age; private Address address; // getter/setter 省略 } public class Address { private String city; private String district; // getter/setter 省略 }Spring识别到address.city，会先找属性名为address的字段，再往它的city属性里塞值。这类“点分路径”在表单绑定里随处可见，前端写错一截，后端就是静默忽略，不报错也不给默认值。排查这类问题时，可以把POST请求体拉出来和实体字段一个一个对，很多时候就是字段名少了个前缀。
数组和List的绑定，麻烦在写法不一。前端如果按hobby=篮球&hobby=足球这种方式重复提交同名参数，后端可以用List<String> hobby或String[] hobby接收。还有一种写法是带下标的hobby[0]=篮球&hobby[1]=足球，Spring也支持，但下标的连续性一旦中断，后面几项可能直接被丢弃。我的建议是：能不用下标就不用下标，重复同名参数最简单也最不容易错。
类型转换也是常见的报错源。表单里传age=18abc，String转Integer失败，Spring默认抛MethodArgumentTypeMismatchException，表现是400。更隐蔽的是日期字段：表单传birthday=1999-01-01，实体里的LocalDate birthday字段，Spring能不能自动转换取决于有没有注册对应的转换器。Spring Boot的格式化器对LocalDate/LocalDateTime默认支持ISO格式，但如果前端传的是1999/01/01或者1999-01-01 12:00:00，就建议在字段上明确加@DateTimeFormat(pattern = "yyyy-MM-dd")，别指望“应该能转”。
4.3 BindingResult的位置规则与参数校验
模型绑定和校验经常一起出现。最常见的写法：
@PostMapping("/api/users") public Result createUser(@Valid @ModelAttribute UserDTO user, BindingResult bindingResult) { if (bindingResult.hasErrors()) { return Result.error(bindingResult.getFieldErrors()); } return userService.create(user); }这里有一个Spring MVC的铁律：BindingResult必须紧跟在被校验的参数后面，中间插入其他参数直接报错。这是为了把绑定错误和校验错误配对到同一个参数对象上。很多人在后面加了HttpServletRequest参数又加BindingResult，结果启动正常、一调用就500，检查半天才发现是参数顺序问题。
另外，@ModelAttribute和@RequestParam可以混用：基本类型参数用@RequestParam，复杂对象用@ModelAttribute（或者隐式模型绑定）。我习惯在每个需要模型绑定的参数上都显式写@ModelAttribute，一是语义清楚，二是方便配合@Valid做校验；不写也能工作，但代码意图没那么直白。
5. JSON请求体实战：@RequestBody背后的消息转换链路
5.1 @RequestBody与@RequestParam的本质区别
前后端分离项目里，接口传参的主流已经是JSON了。前端这样请求：
axios.post('/api/users', { name: '张三', age: 18, address: { city: '杭州' } })后端对应：
@PostMapping("/api/users") public Result createUser(@RequestBody UserDTO user) { return userService.create(user); }@RequestBody的作用不是“把参数绑到对象上”，而是“把整个请求体按照Content-Type声明的格式反序列化成对象”。它和@RequestParam有本质区别：@RequestParam读的是URL查询串或表单体里的键值对，@RequestBody读的是原始请求字节流，交给消息转换器去解析。所以你不能期望一个加了@RequestParam的接口能收到JSON对象，也不能期望@RequestBody能自动接住action=create&name=张三这种表单体（除非你能接受把整个form字符串交给转换器）。
5.2 HttpMessageConverter是怎么选出来的
Spring在解析@RequestBody时，核心机制是HttpMessageConverter。它先看请求头的Content-Type，比如application/json;charset=UTF-8，然后遍历容器里注册的转换器，找到能处理这个媒体类型的那个。JSON请求对应的是MappingJackson2HttpMessageConverter，它内部用Jackson把JSON字符串转成目标类型。
理解这个机制之后，有两个问题就很好解释了。
第一，为什么前端传了字符串却收到415？因为请求头Content-Type不对。比如前端用axios传了一个字符串：
axios.post('/api/users', '{name:"张三", age:18}')axios对字符串做POST时，默认不会自动设置Content-Type为application/json，很多浏览器环境里会是text/plain;charset=UTF-8，Spring找不到合适的消息转换器，直接回415 Unsupported Media Type。
第二，为什么同样的接口，Postman能通、axios不能通？多半是Postman的body类型选了“raw + JSON”，自动带上了application/json头，而axios的调用代码里没设置请求头，或者Content-Type被某个拦截器改掉了。排查时先看实际发出的请求，浏览器F12的Network面板能直接看到请求头内容，比后端猜前端猜快得多。
5.3 Jackson反序列化的关键细节
用@RequestBody配合Jackson，有几个字段层面的细节建议知道：
- 默认情况下，JSON里的字段名要和Java字段名一致。不一致时可以在DTO字段上加
@JsonProperty("front_name")做映射。但你要是担心中后端字段命名风格不统一的，更推荐在前端就对齐字段名，或者在DTO层面做映射，别把事情推迟到Service层。 - 日期字段在JSON里一般配
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")，同时建议设置timezone属性。不设置时，date类型容易差8小时，因为Jackson默认按UTC解析和输出。 - 请求体里出现DTO没有的字段时，Jackson默认忽略，不会报错。如果你希望严格校验，可以在配置里开启
FAIL_ON_UNKNOWN_PROPERTIES。 - 如果请求体的JSON结构是泛型集合，比如
List<UserDTO>，直接写@RequestBody List<UserDTO> users是没问题的，Spring能通过方法签名推断泛型。但如果需要进一步处理泛型嵌套，比如ResponseEntity<List<UserDTO>>，建议用ParameterizedTypeReference搭配RestTemplate或WebClient，这个方法在客户端开发时经常会用到。
5.4 请求体校验与InputStream一次性问题
@RequestBody配校验，和表单绑定类似：
@PostMapping("/api/users") public Result createUser(@Valid @RequestBody UserDTO user) { return userService.create(user); }在DTO字段上用@NotBlank、@Size、@NotNull做约束，校验失败默认抛MethodArgumentNotValidException，需要异常处理器把它转成友好的错误信息。Spring Boot 3里引入了@Validated的类级别校验和更多JSR-380约束，建议给项目配一个@RestControllerAdvice统一处理校验异常，否则前端拿到的都是Spring默认的丑陋错误结构。
还有一点，@RequestBody是一次性流。如果你在过滤器或切面里先读了一次输入流，后面DispatcherServlet再去读请求体就会拿到空，导致@RequestBody接到的对象全是默认值。这就是“接口在我本地能通，加了日志过滤器就拿到null”的典型原因。解决思路是使用Spring提供的ContentCachingRequestWrapper包装请求，或者把日志记录放到Controller里再读取。
6. 联调现场的经典翻车：400、415、null是怎么产生的
6.1 三个典型报错的问题定位表
前后端联调时，参数类问题集中表现为三种现象。我整理了一个快速的定位表格：
| 现象 | 核心原因 | 第一步排查动作 |
|---|---|---|
| 400 Bad Request | 必填参数缺失 / 参数类型转不过去 / JSON结构对不上 | 看后端异常日志，区分是MissingServletRequestParameterException还是MethodArgumentTypeMismatchException还是HttpMessageNotReadableException |
| 415 Unsupported Media Type | 请求头Content-Type和后端期望的媒体类型不匹配 | 看Network面板中请求头发送的是什么Content-Type |
| 参数为null | 参数名不一致 / 参数位置放错 / 后端字段名拼写错误 | 用curl或Postman复现，对比接口文档与DTO字段 |
这三种现象往往不是独立出现的，例如前端用表单形式传了一个JSON对象，后端用@RequestBody接收，可能先是415，改了请求头之后变成400，再改完结构之后又发现字段名对不上导致null。我一般建议一步到位：打开Network面板，先看“实际发出的请求长什么样”，再对照后端期望的“参数位置+参数名+Content-Type+类型”，逐个对齐。
6.2 一套可以复制的排查步骤
我自己的排查流程是这样的：
- 让前端或Postman发请求，浏览器F12/Postman控制台记录下来完整的请求行、请求头、请求体。
- 对照后端Controller方法签名，确认标注的注解是@RequestParam还是@RequestBody还是@PathVariable。
- 从请求里找到对应的参数位置，确认参数名是否和注解里的名字一致，大小写是否敏感。
- 看Content-Type：query串、form表单、JSON输入流，分别对应不同的处理链路。
- 如果还没定位，在Controller方法第一行临时打印参数内容，或者直接把
HttpServletRequest注入进来，调用getParameterMap()和getInputStream()看原始值——这一招能绕开所有注解的干扰，直接确认HTTP层到底收到了什么。 - 确认是业务问题后，再决定是改前端传参方式，还是改后端接收方式。不要两边同时改，否则出了问题都不知道谁改坏了。
很多人排查参数问题习惯盯着代码看，但我更推荐先盯HTTP报文。因为参数传递问题的本质就是报文和Spring解析规则之间的映射，报文对了，注解自然就对上。
6.3 Postman、axios和浏览器各自的“默认行为”差异
最后说一个联调中很现实的问题：Postman能通，axios不通，到底是谁的锅？多数情况下是“默认行为不同”：
- Postman用“x-www-form-urlencoded”这一项发POST时，会自动带
Content-Type: application/x-www-form-urlencoded；用“raw + JSON”时会自动带application/json。你选了哪个，它就在请求头里写哪个。 - axios在浏览器里发对象时，一般会自动设
application/json；发字符串时通常不设Content-Type，让浏览器默认决定，很多情况会变成text/plain。所以axios调用JSON接口，要么传对象让axios自动序列化，要么手动加上headers: { 'Content-Type': 'application/json' }。 - 浏览器直接提交传统表单时，Content-Type固定是
application/x-www-form-urlencoded，这是HTML表单的标准行为，没有配置就改变不了。所以一个页面是普通form提交还是ajax JSON提交，后端接口设计时就要确定好。
我踩过最典型的一次：老项目表单登录，后端用@RequestBody接收用户名密码，前端用的是原生form提交，结果接口永远报415。后来把后端改成接收表单参数（把@RequestBody去掉，改用@ModelAttribute），十几秒就解决了。这个例子说明一个道理：先看请求长什么样，再决定后端注解怎么写，而不是反过来。
实际开发中我还有一个习惯：每建一个新接口，会先写一行注释标明“参数来源 + Content-Type + 前端示例”。比如：
// POST /api/users body: {"name":"张三","age":18} Content-Type: application/json这个注释看起来不起眼，但对跨端联调的帮助非常大。前后端一旦因为参数问题争执起来，把注释拍出来，谁对谁错一目了然。参数传递的本质说到底是约定问题，而Spring只是把约定翻译成了代码，把约定写明白，比背再多注解都管用。
