Spring Boot中SOAP端点与HandlerMapping/Dispatcher冲突问题求解

问题根源 #

Apache CXF的Servlet配置若覆盖了Spring Boot默认的DispatcherServlet映射路径，会导致Thymeleaf页面、REST请求无法被正确调度，而SOAP服务独占请求处理通道。以下是针对性的解决方案：

方案一：隔离CXF与默认DispatcherServlet的映射路径 #

这是最直接的解决方式，给CXF Servlet指定独立的前缀路径，避免和默认Web请求路径冲突：

1. 配置CXF Servlet的专属路径

@Configuration
public class CxfSoapConfig {
    // 注册CXF Servlet，映射到/soap/*路径下
    @Bean
    public ServletRegistrationBean<CXFServlet> cxfServlet() {
        ServletRegistrationBean<CXFServlet> cxfReg = new ServletRegistrationBean<>(new CXFServlet(), "/soap/*");
        cxfReg.setLoadOnStartup(1);
        return cxfReg;
    }

    @Bean(name = Bus.DEFAULT_BUS_ID)
    public SpringBus springBus() {
        return new SpringBus();
    }

    // 发布SOAP服务，路径基于/soap前缀，最终访问地址为/soap/YourServiceName
    @Bean
    public Endpoint soapEndpoint(YourSoapServiceImpl soapService) {
        EndpointImpl endpoint = new EndpointImpl(springBus(), soapService);
        endpoint.publish("/UserService");
        return endpoint;
    }
}

2. 保留Spring Boot默认Web配置

• 移除@EnableWebMvc注解，它会禁用Spring Boot自动配置的视图解析器、资源处理器等组件，导致Thymeleaf页面无法加载。
• 确保Thymeleaf依赖正常引入，配置文件中路径参数正确：

spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html
spring.thymeleaf.enabled=true

方案二：调整DispatcherServlet优先级（若需CXF映射/*） #

如果业务要求CXF必须处理/*路径，可通过提升DispatcherServlet优先级来确保Web请求优先被处理：

@Configuration
public class WebMvcConfig {
    // 重新注册DispatcherServlet，映射到/并设置更高启动优先级
    @Bean
    public ServletRegistrationBean<DispatcherServlet> dispatcherServletReg(DispatcherServlet dispatcherServlet) {
        ServletRegistrationBean<DispatcherServlet> dispReg = new ServletRegistrationBean<>(dispatcherServlet, "/");
        dispReg.setLoadOnStartup(0); // 优先级高于CXF的loadOnStartup(1)
        return dispReg;
    }
}

关键排查点 #

• 查看启动日志，确认两个Servlet的映射路径：

  Mapping servlet: 'dispatcherServlet' to [/]
  Mapping servlet: 'CXFServlet' to [/soap/*]
  

• 检查自定义错误页是否放置在src/main/resources/templates/error/目录下（如404.html），Thymeleaf会自动识别该目录下的错误页面。
• 避免在配置文件中设置spring.mvc.servlet.path属性，防止覆盖默认映射规则。

内容的提问来源于stack exchange，提问作者Naslo Flaquez