文件

§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")

其中 3.0.x 中的「x」是您要使用的 Play 次要版本，例如 3.0.0。
查看 Play 次要版本的發行說明 發行版本。

§從 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 遷移指南

在此文件中發現錯誤？此頁面的原始碼可以在 這裡 找到。在閱讀 文件指南 之後，請隨時貢獻一個拉取請求。有問題或建議要分享嗎？請前往 我們的社群論壇 與社群展開對話。