1. 从一个真实踩坑场景说起MockMvc 参数传值为什么总出问题做 Spring Boot 项目的人只要写过 Controller 层的单元测试大概率都碰过 MockMvc。它能在不启动完整 Servlet 容器的前提下把请求打进 DispatcherServlet验证路由、参数绑定、序列化、拦截器、异常处理这一整条链路。相比直接 new Controller 调方法MockMvc 更接近真实 HTTP 请求能暴露很多“方法调用测不出来”的问题。但真正让人头疼的往往不是 MockMvc 本身怎么用而是参数到底怎么传。我见过太多类似的情况接口在 Postman 里跑得好好的一写 MockMvc 测试就 400明明传了 JSONController 里对象全是 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)RequestHeaderCookie.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/jsonMockMvc 必须自己.contentType(MediaType.APPLICATION_JSON)。Postman 表单会自动生成 boundaryMockMvc 的 multipart 必须用MockMultipartFile。Postman 会把对象序列化成标准 JSONMockMvc 里如果你手写字符串很容易少引号、多逗号、日期格式不对。所以“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 查询参数 RequestParamparam 和 queryParam 的区别查询参数用.param(key, value)最常见。但要注意.param()加的是请求参数它既可能出现在查询字符串也可能出现在表单体里。对于 GET 请求通常就是查询参数对于 POST 表单它会被当作表单字段。如果你明确只想加在 URL 查询串上可以用.queryParam(key, value)。两者在大多数场景下效果一致但语义更清晰。几个高频问题多值参数.param(ids, 1, 2, 3)对应RequestParam ListLong 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.webDEBUG能看到参数解析器、消息转换器的详细过程。我习惯在测试里加.andDo(print())它会打印完整请求和响应包括请求头、请求体、状态码、响应体。定位传值问题时这一行能省很多时间。mockMvc.perform(post(/users) .contentType(MediaType.APPLICATION_JSON) .content(json)) .andDo(print()) .andExpect(status().isOk());4.2 常见问题速查表现象可能原因排查方向400 Bad RequestJSON 格式错误、类型转换失败、缺少必填参数检查 content、param、日期格式415 Unsupported Media TypeContent-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 还是传统 MockMvcSpring 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 传值问题都能在几分钟内定位。真正花时间的不是写测试而是不知道错在哪。希望这些内容能帮你少走几个弯路。
1. 从一个真实踩坑场景说起MockMvc 参数传值为什么总出问题做 Spring Boot 项目的人只要写过 Controller 层的单元测试大概率都碰过 MockMvc。它能在不启动完整 Servlet 容器的前提下把请求打进 DispatcherServlet验证路由、参数绑定、序列化、拦截器、异常处理这一整条链路。相比直接 new Controller 调方法MockMvc 更接近真实 HTTP 请求能暴露很多“方法调用测不出来”的问题。但真正让人头疼的往往不是 MockMvc 本身怎么用而是参数到底怎么传。我见过太多类似的情况接口在 Postman 里跑得好好的一写 MockMvc 测试就 400明明传了 JSONController 里对象全是 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)RequestHeaderCookie.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/jsonMockMvc 必须自己.contentType(MediaType.APPLICATION_JSON)。Postman 表单会自动生成 boundaryMockMvc 的 multipart 必须用MockMultipartFile。Postman 会把对象序列化成标准 JSONMockMvc 里如果你手写字符串很容易少引号、多逗号、日期格式不对。所以“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 查询参数 RequestParamparam 和 queryParam 的区别查询参数用.param(key, value)最常见。但要注意.param()加的是请求参数它既可能出现在查询字符串也可能出现在表单体里。对于 GET 请求通常就是查询参数对于 POST 表单它会被当作表单字段。如果你明确只想加在 URL 查询串上可以用.queryParam(key, value)。两者在大多数场景下效果一致但语义更清晰。几个高频问题多值参数.param(ids, 1, 2, 3)对应RequestParam ListLong 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.webDEBUG能看到参数解析器、消息转换器的详细过程。我习惯在测试里加.andDo(print())它会打印完整请求和响应包括请求头、请求体、状态码、响应体。定位传值问题时这一行能省很多时间。mockMvc.perform(post(/users) .contentType(MediaType.APPLICATION_JSON) .content(json)) .andDo(print()) .andExpect(status().isOk());4.2 常见问题速查表现象可能原因排查方向400 Bad RequestJSON 格式错误、类型转换失败、缺少必填参数检查 content、param、日期格式415 Unsupported Media TypeContent-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 还是传统 MockMvcSpring 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 传值问题都能在几分钟内定位。真正花时间的不是写测试而是不知道错在哪。希望这些内容能帮你少走几个弯路。
