Servlet类org.restlet.ext.servlet.ServerServlet非jakarta.servlet.Servlet问题排查

这个错误我之前帮开发者排查过好几次，核心问题就是Servlet API的包名迁移导致的版本不兼容，具体拆解如下：

核心原因 #

你遇到的jakarta.servlet.UnavailableException: Servlet class org.restlet.ext.servlet.ServerServlet is not a jakarta.servlet.Servlet错误，本质是：

• 你的Jetty版本（应该是10.x及以上）已经切换到了Jakarta Servlet API，对应的包名是jakarta.servlet.*
• 但你使用的Restlet组件的ServerServlet类，仍然实现的是旧版Java EE的javax.servlet.Servlet接口
• 新的Jetty容器只承认实现jakarta.servlet.Servlet接口的类为合法Servlet，所以旧版本的Restlet Servlet被判定为不合法

具体触发场景 #

Jetty 10是一个重要的版本分界点：

• Jetty 9.x及以下：基于旧版javax.servlet API（Servlet 4.0及以下）
• Jetty 10+：全面迁移到jakarta.servlet API（Servlet 5.0及以上）
  如果你的mvn jetty:run使用的是Jetty 10+，但Restlet依赖还是适配javax.servlet的旧版本，就会触发这个错误。

可行的解决办法 #

1. 降级Jetty版本 #

如果暂时不想升级Restlet，可以将Jetty插件降级到9.x系列，它仍然兼容旧版javax.servlet API。修改你的pom.xml中的Jetty插件配置：

<plugin>
    <groupId>org.eclipse.jetty</groupId>
    <artifactId>jetty-maven-plugin</artifactId>
    <!-- 使用Jetty 9的稳定版本，比如9.4.52.v20230823 -->
    <version>9.4.52.v20230823</version>
</plugin>

2. 升级Restlet到适配Jakarta的版本 #

查找Restlet的最新稳定版本，确保其servlet扩展模块已经适配了jakarta.servlet包名。比如Restlet 2.5.x后期版本或3.x版本通常会提供Jakarta兼容的依赖，更新你的pom.xml中的Restlet依赖即可。

3. 临时迁移（不推荐） #

如果上述两种方式都无法快速实施，可以尝试使用Jakarta迁移工具批量替换Restlet类中的javax.servlet为jakarta.servlet，但这种方式属于临时hack，可能会引发其他依赖冲突，仅作为应急方案。

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