Dropwizard 2.0.x 升级迁移指南：Maven BOM、Jetty/Jersey/TLS 行为变更与破坏性 API 迁移详解

后端Web框架【免费下载链接】dropwizardA damn simple library for building production-ready RESTful web services.项目地址https://gitcode.com/gh_mirrors/dr/dropwizard点击查看免费下载Dropwizard 2.0.x 是从 1.x 迁移过程中破坏性变更最集中的大版本依赖管理方式dropwizard-bom与dropwizard-dependencies的分工、Jetty 配置项soLingerTime、blockingTimeout、minRequestDataRate的移除与更名、Jersey 2.29 的注册方式、TLS 默认安全基线、Jackson 默认行为、JDBI 2.x 模块的拆分以及Task.execute的签名变更都在此版本一次性落地。读完本篇你可以按章节逐项核对配置与代码完成一次有依据、可验证的 1.x → 2.0.x 升级并理解每项变更在源码中的实际落点。Maven 依赖管理dropwizard-bom 与 dropwizard-dependencies 的分工2.0.0 起io.dropwizard:dropwizard-bom这个构件只锁定官方 Dropwizard 各模块的版本不再锁定传递依赖。如果你的目标不只是让 Jersey、Jetty、Logback 等传递依赖版本一致还需要锁定它们就必须改用io.dropwizard:dropwizard-dependencies。方式一作为 parent POM可用 Maven 属性覆盖传递依赖版本dropwizard-dependencies可以作为父 POM 使用此时它允许你通过设置对应的 Maven 属性来覆盖个别传递依赖的版本例如使用旧版 Guavaparent groupIdio.dropwizard/groupId artifactIddropwizard-dependencies/artifactId version2.0.0/version /parent properties !-- Use older version of Google Guava -- guava.version28.0-jre/guava.version /properties可覆盖的属性清单可以直接查看 dropwizard-dependencies/pom.xml 的properties区块。当前仓库中该区块列出了完整的外部依赖属性如guava.version、jackson.version、jetty.version、jersey.version、hk2.version、jdbi3.version、logback.version等以及测试与插件属性。例如 Guava 的锁定就是通过guava.version属性配合dependencyManagement中的guava/guava-testlib声明实现的这正是“设置属性即可改版本”的机制所在。方式二以 BOM 方式 import版本不可覆盖如果不想继承该 POM 的全部构建配置可以只把它当作普通 BOM 导入。注意此时无法再像 parent 方式那样用 Maven 属性覆盖个别传递依赖版本dependencyManagement dependencies dependency groupIdio.dropwizard/groupId artifactIddropwizard-dependencies/artifactId version2.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement从 dropwizard-dependencies/pom.xml 的结构看它本身以dropwizard-bom为 parent并在dependencyManagement中导入了一批上游 BOMjackson-bom、jetty-bom、jersey-bom、metrics-bom、slf4j-bom、junit-bom、mockito-bom 等再以显式依赖条目锁定其余传递依赖的版本。这解释了两种用法的差异作为 parent 时属性会参与插值因此可以覆盖以import方式引入时属性插值只发生在 BOM 构建时消费方无法再介入。Jetty 连接器配置项移除与更名以下三个配置选项在 2.0 中被移除或更名配置文件YAML里不应再出现旧写法旧配置处置说明soLingerTime移除该选项在 Jetty 层面本就会退化为无效操作noop因此直接删除blockingTimeout移除此前是 Jetty 内部的阻塞失败保护机制官方已判定该用例不再必要。如果你之前用它来丢弃慢速客户端请改用minRequestDataPerSecond和minResponseDataPerSecondminRequestDataRate更名并改变类型更名为minRequestDataPerSecond取值从纯数字变为带单位的大小size例如100 bytesminRequestDataPerSecond / minResponseDataPerSecond 的源码实现在 HttpConnectorFactory.java 中这两个新选项被声明为DataSize类型默认值为 0 字节即不限制private DataSize minResponseDataPerSecond DataSize.bytes(0); private DataSize minRequestDataPerSecond DataSize.bytes(0);Javadoc 参数表给出的语义是最小请求/响应数据速率字节/秒小于等于 0 表示不限制。实际装配时它们被换算成字节数后交给 Jetty 的HttpConfigurationhttpConfig.setMinResponseDataRate(minResponseDataPerSecond.toBytes()); httpConfig.setMinRequestDataRate(minRequestDataPerSecond.toBytes());也就是说minRequestDataPerSecond承接旧minRequestDataRate的语义负责丢弃慢速客户端minResponseDataPerSecond负责控制服务端发送速率——这正是 1.x 时代用blockingTimeout手工实现的“丢弃慢速客户端”能力的官方替代方案。测试资源 http-connector.yml 展示了 YAML 中的真实写法minRequestDataPerSecond: 42 bytes minResponseDataPerSecond: 200 bytes迁移检查点在你的应用 YAML 的connectors列表中搜索这三个旧键把blockingTimeout相关的防慢速客户端意图改写为速率限制配置。Jersey 2.29 升级带来的注册方式变更Dropwizard 2.0 升级到 Eclipse Jersey 2.29迁移成本集中在三类代码上自定义消息 Provider如果你写过自定义 Provider例如自定义 JSON 的解析/序列化自研一个类似JacksonJaxbJsonProvider的类必须给类标注合适的Consumes和Produces注解通过 JerseyFeature注册该 Provider而不能再像以前那样用AbstractBinderHK2 binder注册。HK2 内部 API 变更如果你之前实现了AbstractValueFactoryProvider需要迁移到AbstractValueParamProvider。HK2 内部 API 在 2.29 中已更新旧基类不再可用。RxClient 移除Jersey Reactive Client API 更新后移除了RxClient因为 rx 能力已内建于客户端本身。只有在想把默认 reactive 类型切换为例如 RxJava 2 的Flowable时才需要使用 Dropwizard 客户端的buildRx相关方法。资源类实例中的 Context 字段注入不再生效这是 2.0 中一个隐蔽但影响面大的行为变更同一个资源类在 1.3 和 2.0 中的行为取决于注册方式。看这个例子Path(/) Produces(MediaType.APPLICATION_JSON) public class InfoResource { Context UriInfo requestUri; GET public String getInfo() { return requestUri.getRequestUri().toString(); } }有两种注册方式Override public void run(InfoConfiguration configuration, Environment environment) { // 1. 注册资源实例 environment.jersey().register(new InfoResource()); // 2. 注册资源类 environment.jersey().register(InfoResource.class); }方式一注册实例在 2.0 中不再工作字段上的Context UriInfo requestUri不会被注入运行期将得到null。官方给出的迁移方案是把字段下沉为端点方法的参数Path(/) Produces(MediaType.APPLICATION_JSON) public class InfoResource { - Context - UriInfo requestUri; GET - public String getInfo() { public String getInfo(Context UriInfo requestUri) { return requestUri.getRequestUri().toString(); } }迁移检查点全局搜索资源类中以Context修饰的字段逐一改为方法参数注入若你坚持注册实例则只能保证不依赖字段注入。TLS 默认更严格只允许前向保密密码套件、默认仅 TLS 1.22.0 对默认 TLS 策略做了两处收紧密码套件默认只允许支持前向保密forward secrecy的套件新禁用的正是TLS_RSA_*家族。不支持前向保密的少量旧客户端将无法再与 2.0 服务通信必要时可用excludedCipherSuites配置项覆盖默认的黑名单。协议版本默认只支持 TLS 1.2。1.x 虽然因可用密码套件实际也只有 TLS 1.2 可用但理论上仍可配置出或协商出 TLS 1.0/1.1 连接2.0 用excludedProtocols黑名单从默认值上消除了这种可能。这两个选项在 HttpsConnectorFactory.java 中定义并参与连接器装配测试 HttpsConnectorFactoryTest.java 覆盖了excludedCipherSuites与excludedProtocols的装配断言可作为行为佐证。启动日志从“可能启用”到“实际启用”1.x 启动时会打印类似这样一行Supported protocols: [SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2]这句话技术上没错但具有误导性它列出的是 JVM可能启用的协议让人误以为 Dropwizard 默认极不安全。2.0 重写了日志逻辑只打印 Dropwizard实际会暴露的协议与套件同时打印被拒绝的协议与套件意味着你可以通过配置把它们暴露出来。2.0 的启动日志变成Enabled protocols: [TLSv1.2] Disabled protocols: [SSLv2Hello, SSLv3, TLSv1, TLSv1.1]排障建议升级后若有客户端连接失败先看这两行日志确认当前 Enabled/Disabled 集合再决定是否需要调整excludedCipherSuites/excludedProtocols而不是盲目放宽。Jackson 默认行为FAIL_ON_UNKNOWN_PROPERTIES 默认关闭2.0 起DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES在 Dropwizard 的ObjectMapper上默认禁用即反序列化时无法识别的字段会被静默忽略。这在 API 响应演进客户端忽略服务端新增字段场景下更友好但也会掩盖字段名拼写错误。源码层面这一默认值位于 Jackson.java 的configure方法中mapper.setPropertyNamingStrategy(new AnnotationSensitivePropertyNamingStrategy()); mapper.setSubtypeResolver(new DiscoverableSubtypeResolver()); mapper.disable(FAIL_ON_UNKNOWN_PROPERTIES);如需回到 1.x 的严格行为可在initialize阶段开启public void initialize(BootstrapExampleConfiguration bootstrap) { bootstrap.getObjectMapper().enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES); }需要注意一个细节虽然通用ObjectMapper默认宽松但配置文件解析路径是严格的。在 DefaultConfigurationFactoryFactory.java 中用于读取 YAML 配置的 ObjectMapper 会显式开启FAIL_ON_UNKNOWN_PROPERTIES其 Javadoc 说明这是“防止配置写错misconfiguration”的保护。因此YAML 里写错配置键名依然会让应用启动失败这条防线没有随 2.0 放宽。JDBI 2.x 支持移出核心模块dropwizard-jdbi模块在 2.0 中移出了 Dropwizard 核心模块。原因是 JDBI 2.x 自 2017 年 1 月起不再有更新而面向其继任者 JDBI 3.x 的dropwizard-jdbi3模块仍然保留在核心模块中当前仓库内即为 dropwizard-jdbi3 目录。如果项目要继续使用 JDBI 2.x只需更换 Maven 坐标groupId 从io.dropwizard变为io.dropwizard.modules!-- 旧坐标 -- dependency groupIdio.dropwizard/groupId artifactIddropwizard-jdbi/artifactId version2.0.0/version /dependency!-- 新坐标 -- dependency groupIdio.dropwizard.modules/groupId artifactIddropwizard-jdbi/artifactId version2.0.0/version /dependency反之直接使用dropwizard-jdbi3的用户不受影响。其他变更校验消息改进与 Task.execute 签名MinDuration / MaxDuration 的校验消息改进MinDuration/MaxDuration注解的默认校验消息不再出现括号式的条件表述而是根据inclusive属性直接给出对应措辞。改进前messageRate must be less than (or equal to, if in inclusive mode) 1 MINUTES改进后inclusive true时messageRate must be less than or equal to 1 MINUTESinclusive false时messageRate must be less than 1 MINUTES相关实现位于 MinDuration.java、MaxDuration.java 及对应的MinDurationValidator/MaxDurationValidator消息生成逻辑集中在 DurationRange.java行为由 DurationValidatorTest.java 断言。如果你依赖旧消息文本做过日志解析或告警匹配需要同步更新。Task.execute 的 parameters 参数类型变更Task.execute方法的parameters参数换了一个略有不同的Map类型。所有继承 Task 抽象类的任务都需要把Override public void execute(ImmutableMultimapString, String parameters, PrintWriter output) throws Exception {改为Override public void execute(MapString, ListString parameters, PrintWriter output) throws Exception {从源码结构看新签名MapString, ListString与HttpServletRequest.getParameterMap()的原生返回类型一致Task.java 中execute的 Javadoc 也明确 parameters 为 “the query string parameters”——即TaskServlet不再需要在传递前把请求参数 map 复制/转换成 Guava 的ImmutableMultimap。附带一提Task在 2.0 还新增了可选的responseContentType构造参数since 2.0让任务可以声明自定义响应内容类型。升级核对清单把上面的章节压缩成一份可直接执行的迁移检查单Maven确认你的 BOM/parent 策略——只锁官方模块用dropwizard-bom需要锁传递依赖并支持属性覆盖改用dropwizard-dependencies作为 parent属性清单见 dropwizard-dependencies/pom.xml。YAML 配置移除soLingerTime、blockingTimeout把minRequestDataRate更名为minRequestDataPerSecond并改为带单位写法如100 bytes如需限制服务端发送速率补充minResponseDataPerSecond。Jersey 代码自定义 Provider 补Consumes/Produces并改为Feature注册AbstractValueFactoryProvider迁移为AbstractValueParamProvider删除对RxClient的依赖。资源类把Context字段注入改为方法参数注入注册实例的场景必改。TLS确认 Enabled/Disabled 协议与密码套件日志符合预期确有旧客户端时用excludedCipherSuites/excludedProtocols做最小化放行。Jackson决定 API 层是否需要重新启用FAIL_ON_UNKNOWN_PROPERTIES记住配置文件解析始终严格。JDBIJDBI 2.x 用户更换坐标到io.dropwizard.modules:dropwizard-jdbi。Task 子类更新execute方法签名如依赖旧校验消息文本更新解析逻辑。按这份清单逐项完成后1.x 应用到 2.0.x 的升级即可做到既有文档依据、又有源码与测试可查证。赞分享后端Web框架【免费下载链接】dropwizardA damn simple library for building production-ready RESTful web services.项目地址https://gitcode.com/gh_mirrors/dr/dropwizard点击查看免费下载相关推荐Puerts Unity 升级指南1.4.x 到 2.0.x 破坏性变更详解与迁移实践Puerts Unity 升级指南1.4.x 到 2.0.x 破坏性变更详解与迁移实践 本指南基于 doc/unity/en/other/upgrade.md游戏开发跨平台psutil 2.0 API 迁移指南从 1.x 升级到 2.x 的破坏性变更与移植策略psutil 2.0 API 迁移指南从 1.x 升级到 2.x 的破坏性变更与移植策略 导读 psutil 是一个跨平台的进程与系统监控库其 2.0 版本可观测性系统编程Browserless 1.x迁移2.0破坏性变更完整清单与平滑迁移指南Browserless 1.x迁移2.0破坏性变更完整清单与平滑迁移指南 Browserless 是一个在 Docker 中部署无头浏览器Headless后端API网关上一篇gh_mirrors/caf/caffe2实战项目从零构建图像分割系统下一篇Dragonboat存储引擎终极选择Pebble vs RocksDB性能对比完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考