文档

§Play 3.0 迁移指南

本指南介绍了如何从 Play 2.9 迁移到 Play 3.0。如果您需要从更早版本的 Play 迁移，则必须首先遵循 Play 2.9 迁移指南。

§如何迁移

除了从 Akka 切换到 Pekko（更多详细信息 此处）之外，Play 3.0 提供与 Play 2.9 相同的功能和错误修复。Play 3.0 和 2.9 将接收相同的功能和错误修复，并并行维护。由于这两个主要版本几乎相同，因此我们建议您参考 Play 2.9 迁移指南。请通读它并按照其步骤从 Play 2.8 迁移到 Play 2.9。之后，继续使用以下 Play 3.0 特定迁移说明来完成迁移到 Play 3.0。我们还建议您通读 Play 2.9 亮点 和 Play 3.0 亮点 页面。

如 Play 2.9 亮点 和 2.9 迁移指南 中所述，Play 2.9 和 Play 3.0 都提供 Scala 3 支持。如果您想将您的应用程序迁移到 Scala 3，请在完成迁移到 Play 3.0 之后，遵循 Scala 3 迁移指南。

§Play 3.0 特定迁移步骤

除了 Play 2.9 迁移指南 中描述的迁移步骤外，您还需要采取一些特定步骤才能迁移到 Play 3.0。

§更改的 groupId

在 Play 3.0 中，我们将 groupId 从 com.typesafe.play 更改为 org.playframework，以强调 Play 是完全 社区驱动 的。如果您使用 Play 库作为依赖项或使用 Play sbt 插件，则必须更新这些依赖项的 groupId。在某些情况下，尽管很少见，但您可能需要调整代码中的导入。请参阅此比较，了解如何更新您的构建文件和代码。

Play 3.0 
// Dependencies:
libraryDependencies += "org.playframework" ...
// sbt plugins:
addSbtPlugin("org.playframework" ...
// Source code:
import org.playframework.*
Play 2.9 
// Dependencies:
libraryDependencies += "com.typesafe.play" ...
// sbt plugins:
addSbtPlugin("com.typesafe.play" ...
// Source code:
import com.typesafe.play.*

§Play 升级

除了 groupId 更改之外，您还需要在 project/plugins.sbt 中更新 Play 版本号。

addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.x")

其中“x”在3.0.x中代表你想要使用的 Play 的次要版本，例如3.0.0。
查看 Play 次要版本的发布说明 releases。

§从 Akka 迁移到 Pekko

Play 3.0 从 Akka 迁移到 Pekko。迁移过程相当简单。你主要需要将导入、包、类名、方法名和配置键从 Akka 重命名为 Pekko。不需要进行任何重大的代码重构。Pekko 项目提供了详细的迁移指南

以下是一些与 Pekko 相关的其他有用链接，你可能会发现它们很有趣

为了让你大致了解，以下是最常见的需要执行的迁移步骤。如前所述，它本质上是一个重命名的过程。最后，如果你在项目源代码中不区分大小写地搜索“akka”，或者不区分大小写地搜索名为“Akka”的文件和文件夹，你应该不会找到任何匹配项。

Scala 和 Java 源文件中的常见重命名

使用 Pekko 的 Play 3.0 
// Imports:
import org.apache.pekko.*
// Changed packages in code:
org.apache.pekko.pattern.after(...)
// Class names:
Pekko.providerOf(...)
class MyModule extends AbstractModule with PekkoGuiceSupport { ... }
// Method names:
headers.convertRequestHeadersPekko(...)
使用 Akka 的 Play 2.9 
// Imports:
import akka.*
// Changed packages in code:
akka.pattern.after(...)
// Class names:
Akka.providerOf(...)
class MyModule extends AbstractModule with AkkaGuiceSupport { ... }
// Method names:
headers.convertRequestHeadersAkka(...)

常见的配置键重命名（通常在conf/application.conf中）

使用 Pekko 的 Play 3.0 
pekko { }
pekko {
  loggers = ["org.apache.pekko.event.slf4j.Slf4jLogger"]
  logging-filter = "org.apache.pekko.event.slf4j.Slf4jLoggingFilter"
}
pekko.serialization { }
pekko.coordinated-shutdown { }
pekko.remote { }
play.pekko { }
play.pekko.dev-mode { }
play.pekko.dev-mode.pekko { }
promise.pekko.actor { }
使用 Akka 的 Play 2.9 
akka { }
akka {
  loggers = ["akka.event.slf4j.Slf4jLogger"]
  logging-filter = "akka.event.slf4j.Slf4jLoggingFilter"
}
akka.serialization { }
akka.coordinated-shutdown { }
akka.remote { }
play.akka { }
play.akka.dev-mode { }
play.akka.dev-mode.akka { }
promise.akka.actor { }

如果你之前使用的是 Akka HTTP（默认值），请特别注意服务器后端配置

使用 Pekko 的 Play 3.0 
play.server {
  provider = "play.core.server.PekkoHttpServerProvider"
  pekko {
      server-header="PekkoHTTP Server"
      # With Http2 enabled:
      #server-header="PekkoHTTP Server Http2"
  }
}
使用 Akka 的 Play 2.9 
play.server {
  provider = "play.core.server.AkkaHttpServerProvider"
  akka {
      server-header="AkkaHTTP Server"
      # With Http2 enabled:
      #server-header="AkkaHTTP Server Http2"
  }
}

确保在conf/logback.xml中调整日志配置中的包名和类名

使用 Pekko 的 Play 3.0 
<logger name="org.apache.pekko" level="WARN"/>
使用 Akka 的 Play 2.9 
<logger name="akka" level="WARN"/>

如果你的项目适用，请考虑将文件夹和文件从 Akka 重命名为 Pekko

使用 Pekko 的 Play 3.0 
app/mymodule/pekkomagic/
app/mymodule/MorePekkoMagic.scala
使用 Akka 的 Play 2.9 
app/mymodule/akkamagic/
app/mymodule/MoreAkkaMagic.scala

§更改的工件

由于切换到 Pekko，两个工件名称也发生了变化。请注意，这除了groupId更改为org.playframework之外。

使用 Pekko 的 Play 3.0 
"org.playframework" %% "play-pekko-http-server" % "3.0.0"
"org.playframework" %% "play-pekko-http2-support" % "3.0.0"
使用 Akka 的 Play 2.9 
"com.typesafe.play" %% "play-akka-http-server" % "2.9.0"
"com.typesafe.play" %% "play-akka-http2-support" % "2.9.0"

下一步：Scala 3 迁移指南

发现文档中的错误？此页面的源代码可以在这里找到。阅读完文档指南后，请随时贡献一个拉取请求。有疑问或建议要分享？前往我们的社区论坛与社区进行交流。