1. 从一个真实踩坑场景说起：MockMvc 参数传值为什么总出问题
做 Spring Boot 项目的人，只要写过 Controller 层的单元测试，大概率都碰过 MockMvc。它能在不启动完整 Servlet 容器的前提下，把请求打进 DispatcherServlet，验证路由、参数绑定、序列化、拦截器、异常处理这一整条链路。相比直接 new Controller 调方法，MockMvc 更接近真实 HTTP 请求，能暴露很多“方法调用测不出来”的问题。
但真正让人头疼的，往往不是 MockMvc 本身怎么用，而是参数到底怎么传。我见过太多类似的情况：接口在 Postman 里跑得好好的，一写 MockMvc 测试就 400；明明传了 JSON，Controller 里对象全是 null；路径参数、查询参数、表单参数、请求头、文件上传混在一起，测试代码写得像猜谜。更麻烦的是，这类问题报错信息通常很模糊，只告诉你状态码不对，不告诉你哪个参数没绑上。
这篇内容就围绕Spring Boot MockMvc 单元测试中的参数传值问题展开，把常见的传参方式、底层绑定原理、容易踩的坑、排查思路和可直接复用的代码模板一次讲透。适合已经写过 Spring Boot 接口、准备补单元测试的开发者，也适合测试用例总是“跑不通但不知道错在哪”的同学。下面所有示例都基于常见实践整理，你可以直接对照自己的项目改造。
2. 先搞清楚 MockMvc 到底在测什么
2.1 MockMvc 的定位：不是纯单元测试，而是切片测试
很多人把 MockMvc 叫“单元测试”，严格说它更接近Web 层切片测试。它不启动真实端口，但会加载 Spring MVC 的核心组件：HandlerMapping、HandlerAdapter、参数解析器、消息转换器、拦截器、异常处理器等。也就是说，你测的不只是某个方法，而是“一个 HTTP 请求进入后，Spring MVC 如何把它变成 Java 方法参数”的完整过程。
这一点非常关键。因为参数传值问题，绝大多数不是 MockMvc 的 API 用错了，而是请求构造出来的形态，和 Controller 期望的绑定方式不匹配。比如 Controller 用@RequestBody接收 JSON，你却用param()传参；Controller 用@RequestParam接收查询参数，你却在 body 里塞 JSON。MockMvc 会忠实模拟这个“不匹配”，然后返回 400 或绑定失败。
所以理解 MockMvc 参数传值，第一步不是背 API，而是先明确：你的 Controller 到底期望什么形态的请求。
2.2 参数绑定的三条主线：来源、类型、转换
Spring MVC 的参数绑定可以拆成三条主线：
- 来源：参数来自 URL 路径、查询字符串、请求体、请求头、Cookie、Session、文件等。
- 类型：目标是简单类型、对象、集合、Map、MultipartFile 等。
- 转换：字符串如何转成目标类型，JSON 如何反序列化成对象，日期如何格式化。
MockMvc 的请求构造器MockHttpServletRequestBuilder提供了对应的方法：
| 参数来源 | MockMvc 构造方法 | 对应注解 |
|---|---|---|
| 路径变量 | get("/users/{id}", 1) | @PathVariable |
| 查询参数 | .param("name", "x") | @RequestParam |
| 表单参数 | .param(...)+contentType(APPLICATION_FORM_URLENCODED) | @RequestParam/ 对象绑定 |
| JSON 请求体 | .content(json)+contentType(APPLICATION_JSON) | @RequestBody |
| 请求头 | .header("X-Token", "abc") | @RequestHeader |
| Cookie | .cookie(new Cookie(...)) | @CookieValue |
| 文件上传 | MockMultipartFile+.multipart(...) | @RequestPart/MultipartFile |
这张表建议你贴在工位上。90% 的传值问题，都能通过“Controller 注解”和“MockMvc 方法”是否对齐来解释。
2.3 为什么 Postman 能通、MockMvc 不通
Postman 是一个完整的 HTTP 客户端，它会自动帮你补很多细节：Content-Type、Content-Length、字符编码、表单边界、JSON 序列化格式。MockMvc 不会自动补这些，它要求你显式构造。比如：
- Postman 选 JSON 会自动带
Content-Type: application/json，MockMvc 必须自己.contentType(MediaType.APPLICATION_JSON)。 - Postman 表单会自动生成 boundary，MockMvc 的 multipart 必须用
MockMultipartFile。 - Postman 会把对象序列化成标准 JSON，MockMvc 里如果你手写字符串，很容易少引号、多逗号、日期格式不对。
所以“Postman 能通”只能说明接口逻辑没问题，不能说明你的 MockMvc 请求构造正确。排查时要把这两件事分开看。
3. 常见参数传值方式逐个拆解
3.1 路径参数 @PathVariable：最容易忽略编码和类型
路径参数看起来最简单，get("/users/{id}", 1)就完事了。但实际有几个坑：
第一，路径变量类型转换失败。如果 Controller 写的是@PathVariable Long id，你传"abc"，会直接抛类型转换异常，表现为 400。测试里最好传合法值，专门测异常时再传非法值。
第二，路径变量名必须和占位符一致。get("/users/{userId}", 1)对应@PathVariable("userId") Long id。如果编译时没保留参数名，而你又没写显式名称，就会报“Name for argument type not available”。解决办法是显式写@PathVariable("userId")，或者在构建配置里开启-parameters编译参数。
第三，路径中的特殊字符要编码。比如参数里带斜杠、空格、中文，直接拼进 URL 可能被截断或解析错误。MockMvc 提供了UriComponentsBuilder来安全构造：
String url = UriComponentsBuilder.fromPath("/users/{name}") .buildAndExpand("张三 李四") .encode() .toUriString(); mockMvc.perform(get(url)).andExpect(status().isOk());提示：路径参数不要用来传复杂对象或大段文本，它本质是 URL 的一部分，长度和字符都有限制。
3.2 查询参数 @RequestParam：param 和 queryParam 的区别
查询参数用.param("key", "value")最常见。但要注意，.param()加的是请求参数，它既可能出现在查询字符串，也可能出现在表单体里。对于 GET 请求，通常就是查询参数；对于 POST 表单，它会被当作表单字段。
如果你明确只想加在 URL 查询串上，可以用.queryParam("key", "value")。两者在大多数场景下效果一致，但语义更清晰。
几个高频问题：
- 多值参数：
.param("ids", "1", "2", "3")对应@RequestParam List<Long> ids。 - 可选参数：Controller 里
@RequestParam(required = false)，测试时不传即可，不要传空字符串，除非你确实想测空串。 - 默认值：
@RequestParam(defaultValue = "10")，测试不传时验证默认值是否生效。 - 中文乱码：GET 请求查询参数中文，MockMvc 默认按 UTF-8 处理，一般没问题。如果 Controller 里拿到乱码，检查服务器编码配置，而不是先怀疑 MockMvc。
mockMvc.perform(get("/search") .queryParam("keyword", "测试") .queryParam("page", "1") .queryParam("size", "20")) .andExpect(status().isOk()) .andExpect(jsonPath("$.content").isArray());3.3 表单参数与对象绑定：contentType 是关键
如果 Controller 用对象接收表单参数，比如：
@PostMapping("/login") public Result login(LoginForm form) { ... }这种叫对象属性绑定，Spring MVC 会从请求参数里按属性名逐个赋值。MockMvc 里要这样写：
mockMvc.perform(post("/login") .contentType(MediaType.APPLICATION_FORM_URLENCODED) .param("username", "demo") .param("password", "123456")) .andExpect(status().isOk());这里contentType非常关键。虽然很多情况下不写也能绑定，但显式声明APPLICATION_FORM_URLENCODED更接近真实表单提交，也能避免某些版本或配置下的解析差异。
如果对象里嵌套了对象或集合，表单绑定会变得很别扭，比如address.city、items[0].name。这种场景建议改用 JSON 请求体，可读性和稳定性都更好。
3.4 JSON 请求体 @RequestBody：序列化方式决定成败
@RequestBody是问题最集中的地方。核心就一句话：请求体必须是合法 JSON，且 Content-Type 必须是 application/json。
常见错误写法：
// 错误：没有 contentType mockMvc.perform(post("/users").content("{\"name\":\"张三\"}")); // 错误：JSON 字符串拼错 mockMvc.perform(post("/users") .contentType(MediaType.APPLICATION_JSON) .content("{name:张三}"));正确写法有两种。第一种是手写 JSON 字符串：
mockMvc.perform(post("/users") .contentType(MediaType.APPLICATION_JSON) .content("{\"name\":\"张三\",\"age\":20}")) .andExpect(status().isOk());第二种是用 ObjectMapper 序列化对象，推荐这种方式，避免手写 JSON 出错：
ObjectMapper objectMapper = new ObjectMapper(); UserCreateRequest request = new UserCreateRequest(); request.setName("张三"); request.setAge(20); mockMvc.perform(post("/users") .contentType(MediaType.APPLICATION_JSON) .content(objectMapper.writeValueAsString(request))) .andExpect(status().isOk());如果项目里注册了 JavaTimeModule、自定义日期格式、命名策略，记得用和项目一致的 ObjectMapper，而不是 new 一个默认的。否则日期字段、驼峰下划线转换很容易对不上。
3.5 请求头与 Cookie：别漏了认证和追踪字段
很多接口依赖请求头，比如认证 token、租户 ID、追踪 ID。MockMvc 里用.header()添加：
mockMvc.perform(get("/profile") .header("Authorization", "Bearer test-token") .header("X-Tenant-Id", "1001")) .andExpect(status().isOk());Cookie 用.cookie(new Cookie("sessionId", "abc"))。注意jakarta.servlet.http.Cookie或javax.servlet.http.Cookie的包名要和项目版本一致，Spring Boot 3 之后是jakarta。
如果多个测试都需要认证头，可以写一个工具方法或自定义 RequestPostProcessor，避免每个用例重复：
public static RequestPostProcessor auth(String token) { return request -> { request.addHeader("Authorization", "Bearer " + token); return request; }; }3.6 文件上传：multipart 必须用 MockMultipartFile
文件上传不能用.content()模拟，必须用multipart()：
MockMultipartFile file = new MockMultipartFile( "file", "test.png", MediaType.IMAGE_PNG_VALUE, "fake-image-content".getBytes() ); mockMvc.perform(multipart("/upload") .file(file) .param("bizType", "avatar")) .andExpect(status().isOk());如果同时有 JSON 部分和文件部分，可以用.part()加MockPart。注意multipart()默认是 POST，如果要 PUT，需要.with(request -> { request.setMethod("PUT"); return request; })。
4. 参数传值问题的系统排查方法
4.1 先看状态码，再看响应体，最后看日志
排查 MockMvc 参数问题，建议按这个顺序：
- 状态码：400 通常是参数绑定失败或 JSON 解析失败；415 是 Content-Type 不支持；404 是路径不对；500 是业务或转换异常。
- 响应体：很多项目有全局异常处理器，会把具体错误信息放进响应体。打印出来看，比猜快得多。
- 日志：开启
logging.level.org.springframework.web=DEBUG，能看到参数解析器、消息转换器的详细过程。
我习惯在测试里加.andDo(print())，它会打印完整请求和响应，包括请求头、请求体、状态码、响应体。定位传值问题时，这一行能省很多时间。
mockMvc.perform(post("/users") .contentType(MediaType.APPLICATION_JSON) .content(json)) .andDo(print()) .andExpect(status().isOk());4.2 常见问题速查表
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 400 Bad Request | JSON 格式错误、类型转换失败、缺少必填参数 | 检查 content、param、日期格式 |
| 415 Unsupported Media Type | Content-Type 缺失或不匹配 | 补.contentType() |
| Controller 对象全 null | 用了@RequestBody却用 param 传参 | 改用.content(json) |
@RequestParam收不到 | 参数名不一致、没加@RequestParam名称 | 显式写参数名 |
| 中文乱码 | 编码不一致 | 检查请求编码和服务器配置 |
| 文件上传失败 | 没用 MockMultipartFile | 改用multipart() |
| 路径变量报名称不可用 | 编译未保留参数名 | 显式写@PathVariable("name") |
4.3 一个容易被忽略的点：字符编码
MockMvc 默认请求编码是 UTF-8，但如果你手动设置了characterEncoding("ISO-8859-1")，中文就会乱。另外，响应编码由produces和消息转换器决定。测试中文时，建议同时断言响应内容，确认整条链路编码一致。
mockMvc.perform(post("/users") .contentType(MediaType.APPLICATION_JSON) .characterEncoding("UTF-8") .content("{\"name\":\"张三\"}")) .andExpect(jsonPath("$.name").value("张三"));5. 可复用的测试基类与最佳实践
5.1 抽一个 BaseControllerTest
每个测试类都写一遍@SpringBootTest、@AutoConfigureMockMvc、ObjectMapper 注入，很啰嗦。可以抽一个基类：
@SpringBootTest @AutoConfigureMockMvc public abstract class BaseControllerTest { @Autowired protected MockMvc mockMvc; @Autowired protected ObjectMapper objectMapper; protected String toJson(Object obj) throws Exception { return objectMapper.writeValueAsString(obj); } protected RequestPostProcessor auth() { return request -> { request.addHeader("Authorization", "Bearer test-token"); return request; }; } }这样业务测试类只关注请求和断言，传值细节统一收敛。
5.2 用 MockMvcTester 还是传统 MockMvc
Spring Boot 3.4 之后引入了MockMvcTester，支持 AssertJ 风格断言，可读性更好。但传统MockMvc依然稳定，资料也多。我的建议是：新项目可以尝试MockMvcTester，老项目继续用传统方式，不必为了新 API 大规模重构。关键是理解参数绑定原理，API 只是外壳。
5.3 测试数据构造的几条经验
- 不要手写复杂 JSON，用对象序列化。
- 日期字段统一格式，比如
yyyy-MM-dd HH:mm:ss，并在测试里用同一格式。 - 枚举值传字符串，确认反序列化策略是名称还是序号。
- 集合参数注意空数组和 null 的区别，很多业务逻辑对这两者处理不同。
- 每个测试只验证一个核心行为，参数传值正确性、业务结果、异常处理分开测。
6. 实操心得与避坑清单
最后分享几条我在实际项目里踩出来的经验。
第一，先写一个最小可通用例。不要一上来就测复杂对象，先用最简单参数把请求打通，确认路径、Content-Type、认证头都对，再逐步加字段。这样出问题时，范围小，好定位。
第二，善用 andDo(print())。它打印的内容包括请求方法、路径、请求头、请求体、响应状态、响应头、响应体。参数传值问题，看这一份输出基本能定位到八成。
第三，区分“绑定失败”和“校验失败”。绑定失败是参数根本没进方法，校验失败是进了方法但@Valid不通过。前者看 400 和绑定异常，后者看BindingResult或全局异常处理器。两者排查方向完全不同。
第四，不要忽略全局异常处理器的影响。有些项目把参数异常统一包装成 200 加错误码，这时候你看状态码会误判。要结合响应体里的错误码判断。
第五，MockMvc 测试要独立于外部依赖。Controller 层测试用@MockBean或@MockitoBean把 Service 替换掉，只验证 Web 层行为。否则数据库、远程调用一挂，测试就不稳定，参数问题也被掩盖。
第六，版本差异要留意。Spring Boot 2 和 3 在包名（javax/jakarta）、MockMvc 配置、Security 测试支持上都有差异。抄网上代码时，先确认版本，否则会出现“代码没错但就是跑不起来”的情况。
参数传值这件事，说到底就是请求形态和绑定注解要对齐。把来源、类型、转换这三条线理清楚，再配合打印和速查表，绝大多数 MockMvc 传值问题都能在几分钟内定位。真正花时间的不是写测试，而是不知道错在哪。希望这些内容能帮你少走几个弯路。
