Play 2.9 迁移指南:从 Play 2.8 升级到 Play 2.9 的完整实战手册
Play 2.9 迁移指南:从 Play 2.8 升级到 Play 2.9 的完整实战手册
导读
本文基于 Play Framework 官方仓库中的《Play 2.9 Migration Guide》整理编写,完整覆盖从 Play 2.8 升级到 Play 2.9 的所有关键动作:构建工具与 JDK 版本升级、API 重命名与移除、JPA 向 Jakarta Persistence 的过渡、配置项变更(应用密钥长度校验、Logback 新格式、play.akka.config 移除)、默认行为变化(测试服务器随机端口、自签名证书问题、空请求体处理)以及依赖与库版本更新。阅读本文后,你将能按部就班地完成一次安全、平滑的 Play 2.9 迁移,并理解这些变更背后的源码级原理。
本文所引用的仓库源码均位于当前仓库(
gh_mirrors/pl/playframework),迁移指南原文见 documentation/manual/releases/release29/migration29/Migration29.md。若你已从 2.7 升级到 2.8,请先参考 Play 2.8 迁移指南;若你希望在 2.9 基础上继续升级到基于 Pekko 与 Pekko HTTP 的 Play 3.0,请参阅 Play 3.0 迁移指南。
一、升级前准备:如何开始迁移
在启动 sbt 之前,请先完成以下四类基础升级,它们是后续所有 API 与配置迁移的前提。
1.1 Play 版本升级
更新 project/plugins.sbt 中的 sbt 插件版本号:
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.9.x")
其中 2.9.x 中的 x 是你要使用的 Play 次版本号,例如 2.9.0。具体次版本的发布说明请查阅 Play 官方 Release Notes。
1.2 sbt 版本升级
Play 2.9 只支持 sbt 1.9 或更新版本。修改 project/build.properties:
sbt.version=1.9.6
1.9.6 是撰写本文时 sbt 1.x 系列的最新版本,你也可以使用更新的 1.x 版本。
1.3 最低 Java 与 sbt 版本要求
| 项目 | 要求 |
|---|---|
| Java 最低版本 | Java 11(已移除 Java 8 支持) |
| 其他受支持 Java 版本 | 17 与 21 |
| 官方建议 | 至少升级到 Java 17 LTS |
需要注意两点:
- 在随后的 Play 2.10 中,官方很可能停止支持 Java 11,建议尽早规划 Java 版本升级路径;
- 在 Java 17 与 Java 21 上,用自签名证书绑定 HTTPS 端口可能会出问题,详见下文「自签名证书生成在 Java 17 与 Java 21 上失败」一节。
1.4 移除 Jetty ALPN Agent
由于 Play 2.9 的最低 Java 版本是 Java 11,而 Java 11 原生支持 ALPN,因此 Jetty ALPN Agent 不再是必需品。如果你通过 SBT_OPTS 等环境变量向应用传过 -javaagent:jetty-alpn-agent-*.jar,现在必须移除该参数。
1.5 升级 Akka 与 Akka HTTP
如果你想升级超过 Akka 2.6 与 Akka HTTP 10.2 的版本,可参考 Play 官方文档中的 Scala 版或 Java 版 Akka 更新指南,并强烈建议阅读仓库文档 How Play Deals with Akka's License Change(Play 如何处理 Akka 许可证变更)。
二、API 变更详解
Play 2.9 包含多项 API 变更。Play 一如既往地遵循「先弃用、后移除」的策略,本节逐项说明这些变化。
2.1 Scala 2.12 支持终止
Play 2.9 支持 Scala 2.13 与 Scala 3.3,不再支持 Scala 2.12。Scala 3 需要额外的迁移步骤,参见 Scala 3 迁移指南。
2.2 在项目中设置 scalaVersion
Java 与 Scala 用户都必须配置 sbt 使用受支持的 Scala 版本——即使你的项目没有任何 Scala 代码,Play 自身基于 Scala 实现,也必须配置正确的 Scala 库。
单项目构建直接在 build.sbt 中设置:
scalaVersion := "2.13.18"
Play 2.9 也支持 Scala 3:
scalaVersion := "3.3.6"
重要:Play 只官方支持 Scala LTS(长期支持) 版本。因此,处于 Scala 3.3 LTS 与下一个 LTS 版本之间的任何 Scala 发布版都不会被 Play 官方支持(尽管实际使用可能可行)。
多项目构建中,scalaVersion 必须设置在每个项目上。通常的做法是把该设置放进所有项目共享的公共设置中:
def commonSettings = Seq(
scalaVersion := "2.13.18"
)
val projectA = (project in file("projectA"))
.enablePlugins(PlayJava)
.settings(commonSettings)
val projectB = (project in file("projectB"))
.enablePlugins(PlayJava)
.settings(commonSettings)
2.3 更一致的方法命名:旧方法已弃用
Play 2.9 重命名了部分类与方法,以增强不同 API(尤其是增、删、清空数据相关方法)之间的一致性。旧方法现在已标记 @deprecated,将在未来版本中移除。
play.api.i18n.MessagesApi trait 中的方法重命名(源码见 Messages.scala):
| 弃用方法 | 新方法 |
|---|---|
clearLang(result: Result) |
withoutLang(result: Result) |
play.api.mvc.Results 对象中的方法重命名(源码见 Results.scala):
| 弃用方法 | 新方法 |
|---|---|
clearingLang(result: Result) |
withoutLang(result: Result) |
play.api.libs.typedmap.TypedMap 中的方法重命名(源码见 TypedMap.scala):
| 弃用方法 | 新方法 |
|---|---|
+ |
updated |
- |
removed |
从源码看,TypedMap 的 + 与 - 符号方法仍被保留为 updated 与 removed 的别名(override def +(entries: TypedEntry[?]*): TypedMap = updated(entries*)),并支持 1~3 个参数及可变参数的重载形式,你可以逐步将符号运算迁移为语义更明确的命名方法。
类名重命名:
| 弃用类 | 新类 |
|---|---|
HttpExecutionContext |
ClassLoaderExecutionContext |
HttpExecution |
ClassLoaderExecution |
从源码结构看,新类位于 play/core/j/ClassLoaderExecutionContext.scala,同时保留了 play/core/j/HttpExecutionContext.scala 作为兼容别名;BuiltinModule.scala 中仍绑定 HttpExecutionContext 到其自身以维持依赖注入的向后兼容。
2.4 移除早期版本中已弃用的 API
Play 2.9 移除了大量早期版本中已弃用的 API。如果你仍在使用它们,建议在升级前先迁移到新 API。请查阅 Javadocs 与 Scaladocs 中的迁移说明,以及 Play 2.8 迁移指南 获取更多信息。
2.5 CSP 报告类型变更
根据 W3C CSP 规范,Play 2.9 起 CSP 报告中的 lineNumber 与 columnNumber 字段类型变为 Long。如果你的实现基于这两个字段是 String 的假设,Play 会回退到「将 String 解析为 Long」,只有解析失败时才抛出错误。但仍建议使用数字类型而非 String,因为 CSP3 发布后这一行为可能再次变化。
仓库中的 CSPReportActionBuilder.scala 印证了这一点:Scala 侧报告构造参数 lineNumber、columnNumber 均为 Option[Long],Java 侧对应字段也是 Optional[Long]。
2.6 Request.asJava 现在总是将请求体包装进 RequestBody
使用 Scala 请求的 asJava 方法转换为 Java 请求时,转换后的 Java 请求总是将请求体包装在 Http.RequestBody 类中。这一改动保证了与 Play Java 的一致性——在 Play Java 中请求体总是被该类包装。
此前该转换并不彻底,转换出的 Java 请求可能直接包含 Scala 请求体而没有 RequestBody 包装。
需要特别注意的是:尽管请求体被包装进 RequestBody,但其内容不会被自动转换为 Java 等价类型。例如:
- Scala 的
play.api.mvc.RawBuffer不会转换为 Java 的play.mvc.Http.RawBuffer; - Scala 的
AnyContentAsEmpty不会转换为java.util.Optional.empty()(即 Play Java 中空请求体的等价物); - 因此
request.asJava.body().asRaw()、.asJson()等辅助方法很可能无法按预期工作。
要取出存储的 Play Scala 请求体对象,请使用 request.asJava.body().as(classOf[Object])。
2.7 从 Java Persistence API 过渡到 Jakarta Persistence API
为了支持 Hibernate ORM 6+ 与 EclipseLink 3+,Play 将其 JPA 模块迁移到了 Jakarta Persistence API。迁移步骤如下:
第一步:先在 build.sbt 的 libraryDependencies 中升级 Hibernate 或 EclipseLink;
第二步:调整 Java 文件中的导入:
// 之前
import javax.persistence.*;
// 之后
import jakarta.persistence.*;
仓库中的 JPA 模块已全面采用新命名空间,例如 DefaultJPAApi.java 与 JPAApi.java 均已使用 import jakarta.persistence.* / jakarta.persistence.EntityManager。
第三步:更新 persistence.xml 的命名空间与 schema 版本:
<!-- 之前 -->
<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
version="2.1">
...
<!-- 之后 -->
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="https://jakarta.ee/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd"
version="3.0">
...
虽然使用了
version="3.0"与persistence_3_0.xsd,这个 XML 声明对最新的 Jakarta Persistence 3.1 同样正确——因为 Jakarta Persistence 3.1 中persistence.xml的 schema 未变,为免重复,版本升级复用了 3.0 schema。
第四步:更新所有配置参数的前缀,将 javax.persistence 替换为 jakarta.persistence:
<!-- 之前 -->
<property name="javax.persistence.jdbc.driver" value="..."/>
<!-- 之后 -->
<property name="jakarta.persistence.jdbc.driver" value="..."/>
第五步(按需):根据社区反馈,若配置中包含旧的 Hibernate provider 类,需要改为:
<!-- 之前 -->
<provider>org.hibernate.ejb.HibernatePersistence</provider>
<!-- 之后 -->
<provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
以保证 Hibernate 在 Play 2.9 下正常工作。
JPA Bean Validation 在 Play 2.9 中暂不支持
需要留意的是,Bean Validation 目前在 Play 2.9 中不受支持,详见 JavaJPA 文档 中的相关说明。
2.8 JNotify watch service 不再可用
play-file-watch 中移除了 JNotifyFileWatchService,因此:
play.dev.filewatch.FileWatchService.jnotify
不再可作为 PlayKeys.fileWatchService 的值。
2.9 移除 PlayKeys 中的部分设置
playOmnidoc、playDocsName、playDocsModule、playDocsJar 这四个设置已从 PlayKeys 中移除。这些设置已长期没有实际用途——Play 文档已无法在本地运行。
2.10 FluentLenium 命名空间变更:org.fluentlenium → io.fluentlenium
FluentLenium 已将其命名空间从 org.fluentlenium 迁移到 io.fluentlenium,你需要相应更新相关 import。
三、配置变更
本节列出 Play 2.9 中的配置项变更与弃用。
3.1 Application Secret 强制最小长度
play.http.secret.key 配置现在在所有模式(prod、dev、test)下都强制进行最小长度校验。若不满足,会抛出错误,配置视为无效,应用无法启动。
最小长度取决于用于签名 session/flash cookie 的算法,可通过 play.http.session.jwt.signatureAlgorithm 与 play.http.flash.jwt.signatureAlgorithm 配置设置:
| 算法 | 最小位数 | 最小字节数 |
|---|---|---|
HS256(默认) |
256 bits | 32 bytes |
HS384 |
384 bits | 48 bytes |
HS512 |
512 bits | 64 bytes |
这两个配置的默认值均为 HS256(见 reference.conf 与 HttpConfiguration.scala)。
出错时会给出详细的解决信息:
Configuration error [
The application secret is too short and does not have the recommended amount of entropy for algorithm HS256 defined at play.http.session.jwt.signatureAlgorithm.
Current application secret bits: 248, minimal required bits for algorithm HS256: 256.
To set the application secret, please read https://playframework.com/documentation/latest/ApplicationSecret
]
从源码看,该校验逻辑位于 HttpConfiguration.scala:通过 SignatureAlgorithm.forName(signatureAlgorithm).getMinKeyLength 取得当前算法的密钥最小位数,与实际密钥位数 applicationSecretLengthBits 对比,不足时构造上述配置错误。
解决方式:确保证密包含要求的位数/字节数。例如用完全随机的输入生成至少 32 字节的密钥:
head -c 32 /dev/urandom | base64
也可以使用 Play 自带的密钥生成命令 playGenerateSecret 或 playUpdateSecret。关于应用密钥的更多配置说明见 ApplicationSecret 文档。
3.2 新的 Logback 配置格式
从版本 1.3 起,Logback 使用新的规范配置格式,Play 已升级到最新 Logback 版本,因此你需要将 Logback 配置文件更新到新格式。可以使用 Logback 团队提供的在线转换器完成(GitHub 登录后粘贴旧配置即可转换)。旧格式仍能工作,但鉴于转换过程简单,官方建议现在就升级。
此外,Play 特有的 coloredLevel 转换器已弃用——Logback 早已提供内置的着色模式。请从 Logback 配置中移除下面这一行:
<conversionRule conversionWord="coloredLevel" converterClass="play.api.libs.logback.ColoredLevel" />
并把 %coloredLevel 替换为 %highlight(%-5level):
<!-- 弃用: -->
<pattern>... %coloredLevel ...</pattern>
<!-- 推荐: -->
<pattern>... %highlight(%-5level) ...</pattern>
3.3 移除 play.akka.config 设置
引导 actor system 时,Akka 会从提供给它的「根配置」中的硬编码 akka 前缀查找自己的设置,这是 Akka 的固有行为,并非 Play 特有。默认情况下 Play 让 Akka 直接从应用配置根路径加载设置,因此你通常在 application.conf 的 akka.* 命名空间下配置 Play 的 actor system。
在 Play 2.9 之前,你可以用 play.akka.config 指定一个替代位置来加载 Akka 设置(若你想把 akka.* 设置留给另一个独立的 Akka actor system 使用)。该配置被移除有两个关键原因:
- 缺乏文档:
play.akka.config从未被充分文档化,文档没有说明即使你设置play.akka.config = "my-akka",根路径下的akka.*设置仍会作为回退被加载。这导致对akka.*配置的任何修改同样会影响my-akka.akka.*中的 actor system,两个 actor system 并未真正独立,play.akka.config隐含的承诺(把akka.*完全留给另一个 actor system)无法兑现; - 配置预期:Play 期望 actor system 配置位于
akka.*命名空间内,并会在该前缀下设置各种配置以确保正常运行。如果你为 Play 使用完全不同的 actor system,应用很可能无法正常工作。
因此,从 Play 2.9 起,akka.* 前缀专属于 Play 的 Akka 配置且不可更改。你仍可实现自己的 actor system,但必须确保它们不从根路径的 akka 前缀读取配置。
直接定义在 akka.* 配置中的 Dispatcher 不再自动加载
作为移除 play.akka.config 的副作用,不再允许直接在 akka.* 配置键内定义 dispatcher——默认 actor system 不会自动加载它们,你会遇到类似异常:
play.api.http.HttpErrorHandlerExceptions$$anon$1: Execution exception[[ConfigurationException: Dispatcher [my-context] not configured]]
...
Caused by: akka.ConfigurationException: Dispatcher [my-context] not configured
...
现在你有三种处理方式:
- 查找 dispatcher 时显式指定
akka.*前缀(例如lookup("akka.my-context")); - 将
my-contextdispatcher 配置直接放在配置根路径; - 把 dispatcher 放到其他子键并从那里查找(例如在配置
contexts.my-context { ... }中,用lookup("contexts.my-context"))。
实际上 Play 2.9 及更新版本的行为才是正确的:dispatcher 本就不应该自动从 akka.* 键读取,这在纯 Akka 应用中同样不成立。能把 dispatcher 放进 akka.* 键只是破损的 play.akka.config 实现的 Play 特有副作用。
四、默认行为变更
Play 2.9 中多项默认值发生变化,可能会影响你的应用。
4.1 自签名证书生成在 Java 17 与 Java 21 上失败
绑定 HTTPS 端口时,Play 通常会默认生成自签名证书。但在 Java 17 下,该操作可能抛出如下异常:
java.lang.IllegalAccessError: class com.typesafe.sslconfig.ssl.FakeKeyStore$ (in unnamed module @0x68c8dd0e) cannot access class sun.security.x509.X509CertInfo (in module java.base) because module java.base does not export sun.security.x509 to unnamed module @0x68c8dd0e (FakeKeyStore.scala:89)
com.typesafe.sslconfig.ssl.FakeKeyStore$.createSelfSignedCertificate(FakeKeyStore.scala:89)
com.typesafe.sslconfig.ssl.FakeKeyStore$.generateKeyStore(FakeKeyStore.scala:79)
play.core.server.SelfSigned$.x$1$lzycompute(SelfSigned.scala:24)
play.core.server.SelfSigned$.x$1(SelfSigned.scala:23)
play.core.server.SelfSigned$.sslContext$lzycompute(SelfSigned.scala:23)
play.core.server.SelfSigned$.sslContext(SelfSigned.scala:23)
play.core.server.SelfSignedSSLEngineProvider.sslContext(SelfSigned.scala:36)
...
测试中的自签名证书
为规避该异常,测试默认不再绑定 HTTPS 端口(这是对旧行为的回归——HTTPS 端口绑定是在早前版本被我们无意中重新激活的)。若你确实要针对使用 Play 生成的自签名证书的 HTTPS 端口运行测试,在 Java 17 下需要一个变通方案:给 Java 17 命令行添加 --add-export 标志,并且必须 fork 一个新的 JVM 实例:
Test / javaOptions += "--add-exports=java.base/sun.security.x509=ALL-UNNAMED"
// Test / fork := true // 这是 Play 中的默认行为;若你之前改成了 false,这里提醒你恢复
或者设置 JAVA_TOOL_OPTIONS 环境变量:
export JAVA_TOOL_OPTIONS="$JAVA_TOOL_OPTIONS --add-exports=java.base/sun.security.x509=ALL-UNNAMED";
DEV 模式下的自签名证书
如果你出于某种原因要通过 Play 生成的自签名证书在 DEV 模式下以 HTTPS 提供服务,也需要给 sbt 命令添加 --add-export 标志(sbt 最终会启动一个运行你应用的 Java 进程):
# 例如,进入交互式 sbt shell:
sbt -J"--add-exports=java.base/sun.security.x509=ALL-UNNAMED"
# 或者,与其他参数混用并直接运行应用:
sbt -J"-Dhttp.port=disabled" -J"-Dhttps.port=9443" -J"--add-exports=java.base/sun.security.x509=ALL-UNNAMED" run
除了命令行传参,你也可以把标志写进项目根目录的 .jvmopts 文件:
--add-exports=java.base/sun.security.x509=ALL-UNNAMED
或写进项目根目录的 .sbtopts 文件(注意 -J 前缀):
-J--add-exports=java.base/sun.security.x509=ALL-UNNAMED
最后也可以再次使用 JAVA_TOOL_OPTIONS 环境变量。
生产环境中的自签名证书
生产环境不建议使用自签名证书提供服务。但如果你确实需要(例如在本地测试打包后的应用),则需给启动 Java 进程的脚本添加 --add-export 标志:
<my-project-script> -J--add-exports=java.base/sun.security.x509=ALL-UNNAMED #-Dhttp.port=disabled -Dhttps.port=9443
也可以不通过命令行传参,而是在 build.sbt 中设置一次,它会被自动追加到启动脚本:
Universal / javaOptions += "-J--add-exports=java.base/sun.security.x509=ALL-UNNAMED"
或使用上面描述的 JAVA_TOOL_OPTIONS 环境变量。
Java 21 下的自签名证书
遗憾的是,上述变通方案对 Java 21 并不足够,你可能会遇到如下异常:
java.lang.NoSuchMethodError: 'void sun.security.x509.X509CertInfo.set(java.lang.String, java.lang.Object)' (FakeKeyStore.scala:92)
com.typesafe.sslconfig.ssl.FakeKeyStore$.createSelfSignedCertificate(FakeKeyStore.scala:92)
com.typesafe.sslconfig.ssl.FakeKeyStore$.generateKeyStore(FakeKeyStore.scala:79)
play.core.server.SelfSigned$.x$1$lzycompute(SelfSigned.scala:24)
play.core.server.SelfSigned$.x$1(SelfSigned.scala:23)
play.core.server.SelfSigned$.sslContext$lzycompute(SelfSigned.scala:23)
play.core.server.SelfSigned$.sslContext(SelfSigned.scala:23)
play.core.server.SelfSignedSSLEngineProvider.sslContext(SelfSigned.scala:36)
...
截至目前,在 Play 中无法使用 Java 21 生成自签名证书,官方建议继续使用 Java 17 做这件事。通常自签名证书并非用于对外提供服务,更完整的 HTTPS 配置请参阅 Configuring HTTPS 与 Production。
4.2 AnyContent 请求体解析器对空请求体的处理变更
如果你使用 AnyContent 请求体解析器(Play Scala 中的 parse.anyContent,或 Play Java 中的 @BodyParser.Of(BodyParser.AnyContent.class)),需要注意:当解析过程产生空请求体时,行为已更新——Play Scala 中请求体将被赋值为 AnyContentAsEmpty,Play Java 中则为 Optional.empty()。
此前,空请求体会根据 Content-Type 头关联一个特定的「空」类型。例如,如果 Play 把空请求体解析为原始缓冲区,请求会包含一个 size 为 0 的 RawBuffer 对象。
从源码看,BodyParsers.scala 中各类解析器(text、xml、json、form-urlencoded、multipart、raw)对空内容均统一归约为 AnyContentAsEmpty,这正是新语义的底层实现。
4.3 不正确的百分号编码 URI 字符处理
自 akka-http 10.2.0 起,不正确的百分号编码 URI 字符会被 akka-http 立即视为 400 Bad Request,Play 没有机会处理该错误。为保证两个 HTTP 后端行为兼容,Play 让 Netty 采用相同行为——解析不正确的百分号编码字符时不再经过错误处理器。这样设计是为了在一个后端替换为另一个后端时最大化兼容性。
4.4 Caffeine 新默认值:play.cache.caffeine.defaults.maximum-size
如果你的应用随时间向缓存添加大量条目,基于 Caffeine 的缓存可能导致 JVM 最终因 Out of Memory 崩溃。Play 2.9 将 Caffeine 配置的默认最大尺寸定义为 10,000(配置键 play.cache.caffeine.defaults.maximum-size)。
4.5 Caffeine 内部改用 Play 默认 dispatcher
Caffeine 内部默认使用的 dispatcher 现在改为 Play 的默认 dispatcher(在 Play 2.9.0 之前使用 Java 公共线程池 ForkJoinPool.commonPool())。你可以通过配置 play.cache.dispatcher 更改所使用的 dispatcher,也可以按 Scala cache API 或 Java cache API 中的说明为不同缓存设置不同 executor。
4.6 测试服务器现在使用随机端口
使用 Play Java、Play Scala specs2 或 ScalaTest + Play 编写功能测试时,如果不显式指定测试服务器端口,现在默认使用随机端口(之前默认是 19001)。这一变更旨在支持并行测试。
相关 API 的源码注释也印证了这一点:play/test/src/main/java/play/test/Helpers.java 中说明「Starting with Play 2.9, if this property is not set, the port by default is 0, which means the operating system will assign a random port」。
迁移要点:
- 不要再用硬编码端口假设;如要恢复旧行为,可设置系统属性
testserver.port(例如设为19001); - 使用随机端口时,务必在测试中获取实际端口。除了
running(TestServer(...))(block(..)),现在可以使用新引入的方法runningWithPort(TestServer(...))(port => block(..)),它会把实际使用的端口作为参数传入。该方法的实现位于 play/api/test/Helpers.scala,并提供了带 WebDriver 的重载变体。
4.7 测试服务器默认不再绑定 HTTPS 端口
与上一条相关,测试服务器默认不再绑定 HTTPS 端口。你可以通过系统属性 testserver.httpsport 重新启用该行为。如果绑定了 HTTPS 端口,将使用自签名证书。
五、依赖图变更
play-jdbc-api 构件不再依赖 play 核心构件。
六、库版本更新
Play 2.9 升级了以下自有库:
| 依赖 | 从 | 到 |
|---|---|---|
| Play File Watch | 1.1.16 | 1.2.0 |
| Play JSON | 2.8.2 | 2.10.0 |
| Play WS | 2.1.11 | 2.2.0 |
| Twirl | 1.5.1 | 1.6.0 |
此外,许多重要的第三方依赖也升级到了最新版本:
| 依赖 | 从 | 到 | 备注 |
|---|---|---|---|
| Akka HTTP | 10.1.15 | 10.2.10 | |
| Guice | 4.2.3 | 6.0.0 | 使用 guice 时 |
| HikariCP | 3.4.5 | 5.0.1 | 使用 jdbc 时 |
| scala-xml | 1.3.1 | 2.2.0 | |
| Jackson 与 Jackson Module Scala | 2.11.4 | 2.14.3 | |
| SBT Native Packager | 1.5.2 | 1.9.16 | |
| Logback | 1.2.12 | 1.4.11 | |
| SLF4J API | 1.7.36 | 2.0.7 | |
| Caffeine | 2.8.8 | 3.1.7 | 使用 caffeine 时 |
| sbt-web | 1.4.4 | 1.5.0 | |
| sbt-js-engine | 1.2.3 | 1.3.0 | |
| Guava | 30.1.1 | 32.1.2 | |
| Lightbend SSL Config | 0.4.3 | 0.6.1 | |
| Java JSON Web Token (JJWT) | 0.9.1 | 0.11.5 | |
| TypeTools | 0.5.0 | 0.6.3 | 用于 Java 路由 DSL |
| FluentLenium | 3.7.1 | 6.0.0 | 现在是 io.fluentlenium |
| Selenium | 3.141.59 | 4.11.0 | |
| Selenium HtmlUnitDriver | 2.36.0 | 4.11.0 | 与 Selenium 同版本 |
| specs2 | 4.8.3 | 4.20.2 | |
| JUnit Interface | 0.11 | 0.13.3 | |
| Joda-Time | 2.10.14 | 2.12.5 | 使用 jodaForms 时 |
| Hibernate Validator | 6.1.7 | 6.2.5.Final | 使用 PlayJava 插件时 |
6.1 groupId 变更
Play 现在统一在 com.typesafe.play 命名空间下发布所有构件,涉及以下调整:
| 构件 | 旧 groupId | 新 groupId |
|---|---|---|
play-file-watch |
com.lightbend.play |
com.typesafe.play |
sbt-twirl |
com.typesafe.sbt |
com.typesafe.play |
6.2 构件名变更
为保证所有构件命名一致(均以 play- 为前缀),以下 artifactId 做了调整:
| 旧 artifactId | 新 artifactId |
|---|---|
build-link |
play-build-link |
filters-helpers |
play-filters-helpers |
routes-compiler |
play-routes-compiler |
run-support |
play-run-support |
七、移除的库
Play 2.9 移除了以下依赖:
"org.scala-lang.modules" %% "scala-java8-compat":因为 Play 2.9 放弃了对 Scala 2.12 的支持,不再需要引入该依赖。请改用 Scala 2.13 标准库中新增的scala.jdk下的类。"jakarta.xml.bind" % "jakarta.xml.bind-api":升级后的 JJWT 依赖不再使用 JAXB。"org.mortbay.jetty.alpn" % "jetty-alpn-agent"与"com.lightbend.sbt" % "sbt-javaagent":Java 11 是 Play 2.9 的最低 Java 版本且原生支持 ALPN,这些依赖不再需要。"jakarta.transaction" % "jakarta.transaction-api":它一直未被使用,似乎是漏网之鱼,现在被清理掉了。
八、迁移清单与注意事项总结
完成 Play 2.9 迁移时,可按以下清单逐项核对:
- 构建环境:
project/plugins.sbt中 sbt-plugin 升级到2.9.x;project/build.properties中 sbt 升级到1.9.6+;JDK 至少 Java 11(建议 17 LTS);移除 Jetty ALPN Agent 的-javaagent参数。 - Scala 版本:
scalaVersion设置为2.13.18或3.3.6(仅支持 Scala LTS);多项目构建需在每个项目上设置。 - API 迁移:
clearLang/clearingLang→withoutLang;TypedMap的+/-→updated/removed;HttpExecutionContext→ClassLoaderExecutionContext;清理早期已弃用的 API。 - JPA 迁移:导入与
persistence.xml全面切换到jakarta.persistence,Hibernate provider 类名按需更新。 - 配置调整:应用密钥满足算法最小长度(HS256 至少 32 字节);Logback 配置切换新格式并移除
coloredLevel;不再使用play.akka.config,dispatcher 不要定义在akka.*下。 - 测试行为:测试服务器端口改为随机(可用
testserver.port恢复,或用runningWithPort获取实际端口);测试默认不绑定 HTTPS;若在 Java 17 上测试自签名证书 HTTPS,需要--add-exports标志并 fork JVM。 - 依赖核对:按新 groupId/artifactId 更新依赖坐标(如
play-file-watch、sbt-twirl、play-routes-compiler等),移除已废弃的四个依赖。
完成以上步骤后,你的应用即可在 Play 2.9 上运行;如需继续升级到 Play 3.0(基于 Pekko 与 Pekko HTTP),请参考 Play 3.0 迁移指南 与 Scala 3 迁移指南。