Play 2.9 迁移指南:从 Play 2.8 升级到 Play 2.9 的完整实战手册

原创2026-09-23 13:06:131,736 阅读
文章标签:后端Web框架

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

需要注意两点:

  1. 在随后的 Play 2.10 中,官方很可能停止支持 Java 11,建议尽早规划 Java 版本升级路径;
  2. 在 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 使用)。该配置被移除有两个关键原因:

  1. 缺乏文档:play.akka.config 从未被充分文档化,文档没有说明即使你设置 play.akka.config = "my-akka",根路径下的 akka.* 设置仍会作为回退被加载。这导致对 akka.* 配置的任何修改同样会影响 my-akka.akka.* 中的 actor system,两个 actor system 并未真正独立,play.akka.config 隐含的承诺(把 akka.* 完全留给另一个 actor system)无法兑现;
  2. 配置预期: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-context dispatcher 配置直接放在配置根路径;
  • 把 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 迁移时,可按以下清单逐项核对:

  1. 构建环境:project/plugins.sbt 中 sbt-plugin 升级到 2.9.x;project/build.properties 中 sbt 升级到 1.9.6+;JDK 至少 Java 11(建议 17 LTS);移除 Jetty ALPN Agent 的 -javaagent 参数。
  2. Scala 版本:scalaVersion 设置为 2.13.18 或 3.3.6(仅支持 Scala LTS);多项目构建需在每个项目上设置。
  3. API 迁移:clearLang/clearingLang → withoutLang;TypedMap 的 +/- → updated/removed;HttpExecutionContext → ClassLoaderExecutionContext;清理早期已弃用的 API。
  4. JPA 迁移:导入与 persistence.xml 全面切换到 jakarta.persistence,Hibernate provider 类名按需更新。
  5. 配置调整:应用密钥满足算法最小长度(HS256 至少 32 字节);Logback 配置切换新格式并移除 coloredLevel;不再使用 play.akka.config,dispatcher 不要定义在 akka.* 下。
  6. 测试行为:测试服务器端口改为随机(可用 testserver.port 恢复,或用 runningWithPort 获取实际端口);测试默认不绑定 HTTPS;若在 Java 17 上测试自签名证书 HTTPS,需要 --add-exports 标志并 fork JVM。
  7. 依赖核对:按新 groupId/artifactId 更新依赖坐标(如 play-file-watch、sbt-twirl、play-routes-compiler 等),移除已废弃的四个依赖。

完成以上步骤后,你的应用即可在 Play 2.9 上运行;如需继续升级到 Play 3.0(基于 Pekko 与 Pekko HTTP),请参考 Play 3.0 迁移指南 与 Scala 3 迁移指南。

登录后查看全文
playframework