迁移至Spring Boot 3.1.3时出现HandlerWrapper类未找到异常的原因及解决

AI 小北

2026-7-11

Spring Boot 3.1.3 + Jetty 12 类找不到异常的原因及解决方法

异常原因

Jetty 12做了架构大重构，把HandlerWrapper类从原来的org.eclipse.jetty.server.handler包移到了org.eclipse.jetty.server包下。而Spring Boot 3.1.3的JettyServletWebServerFactory仍然依赖旧包路径的HandlerWrapper，直接使用Jetty 12就会因为找不到对应类抛出异常。

另外，Spring Boot对Jetty版本有严格的适配规则：3.1.x官方仅支持Jetty 11.x系列，Jetty 12要到Spring Boot 3.2及以上版本才被原生支持。你选用的Jetty 12超出了当前Spring Boot版本的适配范围，这是类路径不匹配的核心原因。

解决方法

方案一：降级Jetty到官方适配版本
直接使用Spring Boot 3.1.3默认依赖的Jetty 11.x（具体为11.0.16），该版本完全兼容Servlet 6.0，无需手动指定版本，让Spring Boot的依赖管理自动处理即可。Maven配置示例：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

方案二：升级Spring Boot到支持Jetty 12的版本
如果必须使用Jetty 12，需将Spring Boot升级到3.2.x及以上版本（比如3.2.0或更高），这个版本已原生适配Jetty 12，能正确处理类路径的变化。升级后同样直接使用spring-boot-starter-jetty即可，无需手动指定Jetty版本。
方案三：手动适配Jetty 12（不推荐）
若既不想降级Jetty也不想升级Spring Boot，需自定义JettyServletWebServerFactory的实现，替换所有依赖旧HandlerWrapper的代码，改用Jetty 12中org.eclipse.jetty.server.HandlerWrapper的新路径。但这种方式需要修改大量Spring Boot的Jetty集成代码，容易引入其他兼容性问题，不建议在生产环境使用。