Dropwizard 5.0.x 升级指南：Java 17 基线、Jakarta EE 10 与 Jetty 12 全面升级

• 后端
• Web框架

本篇技术指南聚焦 Dropwizard 5.0.x 的官方升级说明（upgrade notes），系统梳理从 4.0.x 升级到 5.0.x 时的全部破坏性变更与依赖跃迁：Java 17 基线、Jakarta EE 10、Jetty 12 的Handler#handle新签名、虚拟线程执行模型的纠正，以及 Jackson、Hibernate、Liquibase、Jersey 等核心组件的版本变化。读完后，你将能够对照源码确认每一项变更在仓库中的落地位置，并制定一份可执行的迁移清单。

Java 17：不可商量的新基线

Dropwizard 5.0.x 最重要的前置条件来自 Jetty 12——它不再支持 Java 17 以下的版本。为避免版本冲突，Dropwizard 将自身的 Java 基线同步调整为 Java 17：

要使用 Dropwizard 5.0.x，必须升级到 Java 17 或更高版本。

这一基线在构建配置中可以直接验证。dropwizard-parent/pom.xml 中明确声明了：

<maven.compiler.release>17</maven.compiler.release>

也就是说，整个项目使用release 17编译。如果你的项目目前运行在 Java 8/11 上，升级 Dropwizard 5.0.x 的第一步就是提升 JDK 并检查字节码兼容性。值得注意的一点是：虽然基线是 Java 17，但仓库中与虚拟线程相关的测试（如 VirtualThreadsTest）通过@EnabledForJreRange(min = JRE.JAVA_21)限定在 Java 21+ 环境执行，这反映了虚拟线程特性对运行时版本的额外要求。

依赖版本总览

5.0.x 是一次大规模的依赖升级。官方升级说明给出的关键版本变化如下：

这些声明性版本范围在 dropwizard-dependencies/pom.xml 中可以得到逐项印证（当前分支为 5.0.3-SNAPSHOT，具体小版本可能已随维护更新）：

• Jetty：<jetty.version>12.1.11</jetty.version>（pom.xml#L54）
• Jackson：<jackson.version>2.22.2</jackson.version>，通过jackson-bom导入（pom.xml#L87-L94）
• Hibernate：<hibernate-core.version>6.6.57.Final</hibernate-core.version>
• Jersey：<jersey.version>3.1.12</jersey.version>，经jersey-bom导入
• Liquibase：<liquibase-core.version>4.33.0</liquibase-core.version>
• Logback：<logback.version>1.5.38</logback.version>，SLF4J 为2.0.19
• JUnit：<junit5.version>5.14.4</junit5.version>，经junit-bom导入

对应用方的实际含义是：如果你的工程独立管理了这些第三方依赖的版本，需要逐一与上述 BOM 对齐，否则很容易在运行期出现 API 缺失或类型不兼容。

Jakarta EE 10 兼容性

Dropwizard 4.0.x 完成了从javax命名空间到jakarta命名空间的迁移（详见 4.0.x 升级说明），而 5.0.x 将全部 Jakarta EE 依赖推进到 Jakarta EE 10 基线，各 API 规格版本以 Jakarta EE 10 产品需求定义为准。

在依赖清单中可以看到 Jakarta 10 基线对应的具体 API 版本（dropwizard-dependencies/pom.xml#L41-L47）：

• jakarta.servlet-api6.0.0
• jakarta.ws.rs-api3.1.0（JAX-RS 3.1）
• jakarta.persistence-api3.1.0
• jakarta.validation-api3.0.2
• jakarta.annotation-api2.1.1、jakarta.el-api5.0.1、jakarta.inject-api2.0.1

对已经迁移过 4.0.x 的 4.x 用户来说，命名空间不再变化（依旧是jakarta.*），主要工作量在于上述 API 小版本升级带来的行为差异与第三方库兼容性检查。

虚拟线程：从反模式到 AdaptiveExecutionStrategy

3.x 与 4.x 曾为虚拟线程提供基础支持，但当时的实现是直接用虚拟线程承载 Jetty 的内部线程池——这在 Jetty 的线程模型中属于反模式（线程池应当复用少量平台线程，而虚拟线程的价值在于任务级并发）。

Dropwizard 5.x 纠正了这一行为：

• Jetty 的线程池现在由平台线程承担；
• 虚拟线程以executor的形式提供给 Jetty 12 的AdaptiveExecutionStrategy，由它在需要时调度任务执行到虚拟线程上。

这一设计与仓库中的测试完全对应。VirtualThreadsTest 通过构造ExecutionStrategy.Producer并把它交给AdaptiveExecutionStrategy(producer, threadPool)，实际派发一个任务，再用VirtualThreads.isVirtualThread()探测任务是否运行在虚拟线程上，分别验证setEnableVirtualThreads(true/false)与setEnableAdminVirtualThreads(true/false)四种组合的行为。这些开关定义在 DefaultServerFactory 中，即你熟悉的server.applicationConnectors[].type: virtual-thread一类的配置项。

此外，LifecycleEnvironment 还会在启用虚拟线程时通过反射创建Executors.newVirtualThreadPerTaskExecutor()并注册为受管资源，保证应用级异步执行器与 Jetty 侧的虚拟线程开关保持一致。

Jetty 12 核心变更

Jetty 12 对内核做了大量重构，是本次升级中影响面最广的部分，需要重点理解。

servlet 组件模块化与 jetty-ee10-bom

从 Jetty 12 起，servlet 组件不再属于 Jetty 内核，而是通过独立模块引入，从而允许同一个 Jetty 版本搭配不同的 servlet API 版本。Dropwizard 负责管理与其兼容的 EE 组件：5.0.x 通过导入jetty-ee10-bom来锁定 EE10 组件，其中关键是jetty-ee10-servlet工件。这在 dropwizard-dependencies/pom.xml#L309-L315 中可以看到：

<dependency> <groupId>org.eclipse.jetty.ee10</groupId> <artifactId>jetty-ee10-bom</artifactId> <version>${jetty.version}</version> <type>pom</type> <scope>import</scope> </dependency>

同时，dropwizard-jetty/pom.xml 等模块显式依赖了jetty-ee10-servlet，保证各模块引用的是同一版本族。

Handler#handle 方法签名变更

Jetty 12 最核心的 API 变化是Handler#handle(...)的签名重写，从旧式的：

void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException

变为：

boolean handle(Request request, Response response, Callback callback) throws Exception

两个语义变化需要牢记：

1. “已处理”状态不再通过request.setHandled(boolean)设置，而是由handle方法的返回值表达；
2. 新增的Callback对象要求：当且仅当请求由该 Handler 处理时，必须将其 complete 或 abort。

如果你在项目中自定义了 JettyHandler（例如自定义请求过滤链、健康探针前置处理），这段代码在 5.0.x 下必然无法编译，需要按新签名重写。

GZIP 错误状态码：500 改 400

Jetty 在收到非法 GZIP 字节时默认返回 500。Dropwizard 的职责是区分“客户端错误”与“服务端错误”，因此捕获这类异常并改写为 400。由于 GZIP 处理发生在 Jetty Handler 层而非 servlet 层，5.0.x 的实现需要同时覆盖 servlet 与非 servlet 场景，相关类集中在 dropwizard-jetty 模块：

• ZipExceptionHandlingGzipHandler：Handler 层捕获ZipException/EOFException，由 GzipHandlerFactory 按server.gzipHandler配置挂入 Handler 链；
• ZipExceptionHandlingRequestWrapper：记录读取输入流时发生的 GZIP 异常；
• ZipExceptionHandlingServletFilter：servlet 环境下的过滤器，当请求为 JettyServletApiRequest且包装器中记录了 GZIP 异常时，抛出携带HttpStatus.BAD_REQUEST_400的BadMessageException。

迁移要点：如果你在 4.x 中曾手动注册过ZipExceptionHandlingGzipHandler，升级到 5.0.x 后建议同时注册ZipExceptionHandlingServletFilter，以在 servlet 环境中重新启用 500→400 的状态码改写。测试用例 GzipServletHandlerTest 验证了这条 Handler + Filter 组合的工作路径。

新增 unix-socket 连接器

5.0.x 新增类型为unix-socket的连接器，仓库中对应独立的 dropwizard-unix-socket 模块。具体的配置参数（如socketPath等）请参阅配置指南中 unix sockets 一节。典型用途是通过反向代理（如 nginx、Caddy）以 unix domain socket 承接本地流量，减少 TCP 栈开销。

移除 Server Push 支持

Jetty 早已对PushCacheFilter弃用（其承载的 HTTP 特性本身已被弃用），Jetty 12 最终移除了 server push 能力。因此 Dropwizard 5.0.x 一并删除了该特性的配置类。如果你的 4.x 配置中使用了server.pushCacheFilters，升级时须删除该配置段，并在构建日志中确认相关类引用已被清理。

移除 server.maxQueuedRequests

配置项server.maxQueuedRequests在 5.0.x 中被移除且没有替代项。这与 Jetty 12 的线程架构演进一致——旧版本中请求队列长度可显式控制，而新架构下该维度由 Jetty 12 的线程池与执行策略自行管理（可参考 Jetty 12 官方文档中 Threading Architecture 一节的说明）。迁移时只需从 YAML 配置中删除该键即可，无需寻找等价配置。

Jackson 2.20.x

Jackson 从 2.15.x 升级到 2.20.x（当前分支 BOM 中实际锁定为 2.22.2，见 dropwizard-dependencies/pom.xml#L40），属于跨度显著的升级，包含性能优化、对 Java 17+ 特性的增强以及 databind/core/annotations 各模块的持续更新。

官方判断是：多数应用不需要修改代码，但自定义序列化器/反序列化器建议重点复查，尤其是依赖了内部 API 或旧版本特有行为的实现。

JUnit 5.13.x

JUnit 从 5.9.x 升级到 5.13.x（当前分支 BOM 锁定为 5.14.4），带来与现代 Java 版本更好的集成、更强的并行测试执行能力和更新的 Jupiter API 与测试引擎。需要注意：如果你的测试仍在使用 JUnit 4 API，请确保已完成向 JUnit 5 的迁移，或引入了合适的兼容依赖（如 vintage 引擎）。Dropwizard 自身的测试基座（dropwizard-testing模块）也已基于 JUnit 5 的 Jupiter API 编写。

Hibernate 6.6.x

Hibernate 从 6.1.x 升级到 6.6.x（当前分支 BOM 锁定为 6.6.57.Final），亮点包括类型系统的持续改进、性能增强、缺陷修复，以及更强的 Jakarta Persistence 3.1 支持（对应 dropwizard-dependencies/pom.xml#L44 中的jakarta.persistence-api3.1.0）。

对使用 DropwizardHibernateBundle封装的应用，大部分变化应是透明的；但如果你直接使用了 Hibernate 原生 API，需要对照 Hibernate 6.6 官方迁移指南检查 6.1 → 6.6 之间的变更。4.0.x 阶段 Hibernate 5 → 6 的变更点（Criteria移除、Serializable键限制移除、USE_NEW_ID_GENERATOR_MAPPINGS移除，见 4.0.x 升级说明）在此版本上不再适用，但仍值得作为历史背景了解。

Liquibase 4.33.x

Liquibase 从 4.20.x 升级到 4.33.x（BOM 锁定 4.33.0），涵盖 changelog 解析与校验增强、数据库支持改进和性能优化。迁移时建议检查 changelog 文件（XML/YAML/SQL）中是否使用了已废弃的特性，并参考 Liquibase 官方 release notes 了解 4.20 → 4.33 的细节。相关配置入口见 迁移指南。

Jersey 3.1.x 与 HK2 Binder 语义变化

Jersey 从 3.0.x 升级到 3.1.x（BOM 锁定 3.1.12）。一个需要留意的语义变化是：Jersey 3.1 将 HK2 binder 视为 provider。这改变了 binder 在 Jersey 与 HK2 中的处理语义——如果你自定义过Binder（例如向 HK2 容器注册额外服务），其注册时机与生效方式可能不同，升级后建议对依赖 HK2 注入的功能做一次回归验证。Dropwizard 的 Jersey 集成层（dropwizard-jersey模块）与 HK2 的锁定版本（hk2.version3.0.6，见 dropwizard-dependencies/pom.xml#L37）已经适配了这一变化。

请求日志：logback-access 与 Jetty 12 的新协作

历史上，基于logback-access的请求日志一直存在一些特殊问题，Dropwizard 为此提供了 workaround。Jetty 12 配套的新版logback-access实现提供了一个 request wrapper，它只为部分“相关”方法从 JettyRequest构造HttpServletRequest，这意味着日志模式里能取到的字段受限。

Dropwizard 5.0.x 的对策是提供自定义 workaround：通过解析 servlet 上下文，直接使用当前活跃的HttpServletRequest进行请求日志记录，从而支持HttpServletRequest的全部方法，并在后续 servlet API 更新中保持更稳定的行为。实现位于 dropwizard-request-logging 模块，其 BOM 中锁定的是logback-access-jetty12（版本 2.0.15，见 dropwizard-dependencies/pom.xml#L397-L401）。如果你自定义过请求日志格式，建议对照 e2e 中的 请求日志集成测试 验证各模式字段的行为。

升级检查清单

结合以上全部内容，从 4.0.x 迁移到 5.0.x 的实操清单如下：

1. JDK 提升至 17+，确认maven.compiler.release/<release>与基线一致；
2. 删除 YAML 中的server.maxQueuedRequests（无替代项）；
3. 移除server.pushCacheFilters配置及相关代码引用；
4. 如曾手动使用ZipExceptionHandlingGzipHandler，补充注册ZipExceptionHandlingServletFilter；
5. 自定义 JettyHandler的代码按boolean handle(Request, Response, Callback)新签名重写，注意Callback的 complete/abort 语义；
6. 依赖 HK2 binder 的自定义 provider 注册做回归测试（Jersey 3.1 语义变化）;
7. 复查自定义 Jackson 序列化器/反序列化器（2.15 → 2.20+）；
8. 直接调用 Hibernate 原生 API 的代码对照 6.6 迁移指南；检查 Liquibase changelog 中的废弃特性；
9. 使用虚拟线程时确认enableVirtualThreads/enableAdminVirtualThreads配置（DefaultServerFactory），理解其执行模型已从“虚拟线程池”变为“平台线程池 + 虚拟线程 executor”；
10. 测试框架若含 JUnit 4 用例，确认 JUnit 5 迁移或兼容依赖。

完成上述步骤后，5.0.x 的绝大部分升级对业务代码是透明的——真正的代码改动集中在 Jetty Handler 适配与配置项清理两处，其余主要是依赖版本对齐与回归验证。

• 后端
• Web框架