Spring @AutoConfigureRestDocs自定义配置后测试返回404如何解决
问题根因
出现404的核心原因是嵌套配置类的注解选择错误:
- 你在测试类内部定义的
RestDocsConfiguration使用了普通@Configuration注解,Spring测试上下文加载时,会将这个类判定为整个测试上下文的主配置入口 - 一旦主配置源切换为这个嵌套类,原本
@WebMvcTest自带的“仅注册指定控制器、加载Web层切片配置”的逻辑就会失效,Spring容器不会主动加载PayrollController,自然不存在对应的接口路由,访问时直接返回404 - 这个异常和RestDocs自定义逻辑本身无关,哪怕这个嵌套@Configuration类里不定义任何Bean,只要加上普通@Configuration注解,就会触发该上下文加载问题。
解决方案
两种可行的改法,满足“不单个测试方法配置美化、不出现404”的需求:
方案1:替换嵌套配置类的注解类型
把内部嵌套的RestDocsConfiguration上的@Configuration换成@TestConfiguration即可。@TestConfiguration是Spring为测试场景设计的专用配置注解,只会作为测试上下文的附加配置源存在,不会替换原有@WebMvcTest的主加载逻辑,修改后的代码:
@WebMvcTest(PayrollController.class) @AutoConfigureRestDocs class PayrollControllerTest { // 仅需替换注解,其余自定义逻辑完全不变 @TestConfiguration static class RestDocsConfiguration { @Bean public RestDocsMockMvcConfigurationCustomizer restDocsMockMvcConfigurationCustomizer() { return configurer -> configurer.operationPreprocessors() .withResponseDefaults(Preprocessors.prettyPrint()); } } @Autowired private MockMvc mockMvc; @Test void testHello() throws Exception { this.mockMvc.perform(MockMvcRequestBuilders.get("/api/payroll/hello")) .andExpect(status().isOk()) .andExpect(content().string("hello world")); } }
修改后,@WebMvcTest会正常注册PayrollController的路由映射,@AutoConfigureRestDocs会自动检测到自定义的RestDocsMockMvcConfigurationCustomizer Bean,对所有接口的响应内容应用格式化美化逻辑,测试用例可正常运行。
方案2:抽离独立通用配置类,实现全局复用
如果希望这个美化配置给项目内所有RestDocs测试类通用,可以把配置类从测试类内部抽离为独立的测试源码类,避免嵌套配置带来的上下文加载问题:
- 在测试源码目录下新建独立配置类,用
@TestConfiguration标记:@TestConfiguration public class CommonRestDocsConfig { @Bean public RestDocsMockMvcConfigurationCustomizer restDocsMockMvcConfigurationCustomizer() { return configurer -> configurer.operationPreprocessors() .withResponseDefaults(Preprocessors.prettyPrint()); } } - 在需要使用该配置的测试类上,通过
@Import显式导入即可,无需每个测试方法单独编写美化逻辑:@WebMvcTest(PayrollController.class) @AutoConfigureRestDocs @Import(CommonRestDocsConfig.class) class PayrollControllerTest { // 原有测试逻辑保持不变 }
常见坑提醒
- 使用各类切片测试(
@WebMvcTest/@DataJpaTest/@JsonTest等)时,不要用普通@Configuration定义内部嵌套配置类,普通@Configuration会被判定为主配置类,截断切片测试的自动组件扫描逻辑 - 测试场景下追加自定义Bean,优先使用
@TestConfiguration标记配置类,该注解的设计逻辑就是不干扰主配置的正常加载流程
内容的提问来源于stack exchange,提问作者ashley
相关产品推荐
相关产品推荐

