You need to enable JavaScript to run this app. Spring @AutoConfigureRestDocs自定义配置后测试返回404如何解决
优惠活动
大模型
产品
解决方案
定价
更多

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测试类通用,可以把配置类从测试类内部抽离为独立的测试源码类,避免嵌套配置带来的上下文加载问题:

  1. 在测试源码目录下新建独立配置类,用@TestConfiguration标记:
    @TestConfiguration
    public class CommonRestDocsConfig {
        @Bean
        public RestDocsMockMvcConfigurationCustomizer restDocsMockMvcConfigurationCustomizer() {
            return configurer -> configurer.operationPreprocessors()
                    .withResponseDefaults(Preprocessors.prettyPrint());
        }
    }
    
  2. 在需要使用该配置的测试类上,通过@Import显式导入即可,无需每个测试方法单独编写美化逻辑:
    @WebMvcTest(PayrollController.class)
    @AutoConfigureRestDocs
    @Import(CommonRestDocsConfig.class)
    class PayrollControllerTest {
        // 原有测试逻辑保持不变
    }
    
常见坑提醒
  • 使用各类切片测试(@WebMvcTest/@DataJpaTest/@JsonTest等)时,不要用普通@Configuration定义内部嵌套配置类,普通@Configuration会被判定为主配置类,截断切片测试的自动组件扫描逻辑
  • 测试场景下追加自定义Bean,优先使用@TestConfiguration标记配置类,该注解的设计逻辑就是不干扰主配置的正常加载流程

内容的提问来源于stack exchange,提问作者ashley

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.26 20:06:03