文件

§Play WS 遷移指南

Play WS 現在有獨立版本 - https://github.com/playframework/play-ws - 可在 Play 專案外使用。如果您有 Play sbt 專案，您仍可透過將下列程式碼行加入您的 build.sbt 來新增 WS

libraryDependencies += ws

這包含了 play-ahc-ws 模組，它會以 Play 依賴注入繫結和元件、組態以及任何其他必要的項目來包裝獨立版本，以便更好地整合。

如果您想使用快取支援，您需要新增 ws、ehcache 並啟用並組態快取

libraryDependencies += ws
libraryDependencies += ehcache

如果您想在非 Play 專案中使用它，可以使用以下方式將它新增到 sbt 專案中

libraryDependencies += "com.typesafe.play" %% "play-ahc-ws-standalone" % "1.0.1"
libraryDependencies += "com.typesafe.play" %% "play-ws-standalone-json" % "1.0.1"
libraryDependencies += "com.typesafe.play" %% "play-ws-standalone-xml" % "1.0.1"

§套件變更

Play WS 過去包含兩個函式庫，ws 和 playWs，分別包含 Scala 和 Java API，每個函式庫都會在幕後個別建立一個 AsyncHTTPClient。現在只有一個 play-ahc-ws 函式庫，其中包含 Scala 和 Java WSClient 執行個體，而且兩個都指向單一 AsyncHttpClient 提供者。

§專案變更

Play WS 現在存在於獨立 WS 函式庫之上的 Play 特定包裝器中，不依賴 Play 類別，而且使用已重新命名套件的 AsyncHttpClient、Signpost 和 Netty 4.0 的「遮蔽」版本。

透過提供獨立 WS 版本並使用遮蔽函式庫，WS 更具彈性，而且與其他函式庫和專案的衝突較少。

Play WS API 擴充了 Standalone WS post，並使用僅在 Play 中可用的 Http.Multipart 和 Multipart 類型，例如

def withBody(body: Source[MultipartFormData.Part[Source[ByteString, _]], _]): Self

Signpost OAuth 已變更，因此不再使用 Commons HTTPClient OAuthProvider，現在使用 DefaultOAuthProvider，而 DefaultOAuthProvider 在幕後使用 HTTPURLConnection。

§API 變更

§Scala

WSAPI 類別已移除。WSClient 介面是 WS API 的進入點。

WSRequest 有 withBody[T](body: T)(implicit writable: play.api.http.Writable[T]) 方法已取代，因為難以追蹤 Writable 的行為。現在有一個自訂 BodyWritable[T] 類型類別填補相同功能，而且在 Standalone WS 中定義了類型類別執行個體

override def withBody[T: BodyWritable](body: T)

已移除不建議使用的 Scala 單一物件 play.api.libs.ws.WS。應改用 WSClient 的執行個體。如果使用編譯時期依賴注入，則應混合使用 AhcWSComponents 特質。

對於 Guice，系統中提供了一個 WSClient

class MyService @Inject()(ws: WSClient) {
   def call(): Unit = {     
     ws.url("https://127.0.0.1:9000/foo").get()
   }
}

如果您無法使用注入的 WSClient 實例，那麼您也可以建立自己的 WSClient 實例，但您必須負責管理客戶端的生命週期。

如果您正在執行功能測試，您可以使用 play.api.test.WsTestClient，它會啟動並關閉一個獨立的 WSClient 實例

play.api.test.WsTestClient.withClient { ws =>
  ws.url("https://127.0.0.1:9000/foo").get()
}

ning 套件已被 ahc 套件取代，而 Ning* 類別則被 AHC* 取代。

正常的 WSResponse 實例會從 stream() 傳回，而不是 StreamedResponse。您應該呼叫 response.bodyAsSource 來傳回串流結果。

play.api.libs.ws.WSRequest 中有一些命名變更，並已棄用以讓事情更明確。在遷移這些變更時應特別小心
- WsRequest.withHeaders 現在是 WsRequest.addHttpHeaders（行為相同）或 WsRequest.withHttpHeaders（捨棄現有的標頭）
- WsRequest.withQueryString 現在是 WsRequest.addQueryStringParameters（行為相同）或 WsRequest.withQueryStringParameters（捨棄現有的查詢字串）

§Java

在 Java 中，play.libs.ws.WS 類別已棄用。應該改用注入的 WSClient 實例。

public class MyService {
     private final WSClient ws;

     @Inject
     public MyService(WSClient ws) {
         this.ws = ws;
     }

     public void call() {     
         ws.url("https://127.0.0.1:9000/foo").get();
     }
}

如果您無法使用注入的 WSClient 實例，那麼您也可以建立自己的 WSClient 實例，但您必須負責管理客戶端的生命週期。

如果您正在執行功能測試，您可以使用 play.test.WsTestClient，它將啟動並關閉一個獨立的 WSClient 實例

WSClient ws = play.test.WsTestClient.newClient(19001);
...
ws.close();

一個正常的 WSResponse 實例會從 stream() 返回，而不是 StreamedResponse。您應該呼叫 response.getBodyAsSource() 來返回串流結果。

下一步：快取遷移

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