知識庫 / Web Services RSS 訂閱

例如，讓我們為我們之前的示例添加一個 Consumer 以記錄響應：

ws.url(url)
  .addHeader("key", "value")
  .addQueryParameter("num", "" + 1)
  .get()
  .thenAccept(r -> 
    log.debug("Thread#" + Thread.currentThread().getId() 
      + " Request complete: Response code = " + r.getStatus() 
      + " | Response: " + r.getBody() 
      + " | Current Time:" + System.currentTimeMillis()));

我們隨後在日誌中查看了響應：

[debug] c.HomeControllerTest - Thread#30 Request complete: Response code = 200 | Response: {
  "Result" : "ok",
  "Params" : {
    "num" : [ "1" ]
  },
  "Headers" : {
    "accept" : [ "*/*" ],
    "host" : [ "localhost:19001" ],
    "key" : [ "value" ],
    "user-agent" : [ "AHC/2.1" ]
  }
} | Current Time:1579303109613

值得注意的是，我們使用了 thenAccept，因為它需要一個 Consumer 函數，因為我們不需要在日誌後返回任何內容。

當我們需要當前階段返回一些內容，以便在下一階段使用時，則需要使用 thenApply，它接受一個 Function。

這些用法遵循標準 Java 函數接口的約定。

5.3. 大型響應體

我們目前實現的代碼對於小型響應和大多數用例來説是一個不錯的解決方案。但是，如果需要處理數百兆甚至更大容量的數據，我們需要採用更有效的策略。

需要注意的是：<em style="font-style: italic;">get</em> 和 <em style="font-style: italic;">post</em> 等請求方法會將整個響應加載到內存中。

為了避免可能發生的 <em style="font-style: italic;">OutOfMemoryError</em> 錯誤，我們可以使用 Akka Streams 在不將響應加載到內存中的情況下進行處理。

例如，我們可以將其內容寫入文件：

ws.url(url)
  .stream()
  .thenAccept(
    response -> {
        try {
            OutputStream outputStream = Files.newOutputStream(path);
            Sink<ByteString, CompletionStage<Done>> outputWriter =
              Sink.foreach(bytes -> outputStream.write(bytes.toArray()));
            response.getBodyAsSource().runWith(outputWriter, materializer);
        } catch (IOException e) {
            log.error("An error happened while opening the output stream", e);
        }
    });

stream 方法返回一個 CompletionStage，其中 WSResponse 具有 getBodyAsStream 方法，該方法提供一個 Source<ByteString, ?>。

我們可以通過使用 Akka 的 Sink 來告訴代碼如何處理這種類型的體，在我們的示例中，它將簡單地將通過 OutputStream 傳遞的任何數據寫入。

5.4. 超時設置

當構建請求時，我們可以設置特定的超時時間，如果我們在規定時間內沒有收到完整的響應，則請求會被中斷。

此功能在查詢速度特別慢的服務時尤其有用，可以避免大量連接被阻塞，等待響應。

我們可以使用調優參數為所有請求設置全局超時時間。要為特定請求設置超時時間，可以使用 setRequestTimeout 方法。

ws.url(url)
  .setRequestTimeout(Duration.of(1, SECONDS));

雖然還有一種情況需要處理：我們可能已經接收到了所有數據，但我們的消費者（Consumer）處理這些數據可能會非常緩慢。這可能是由於大量的數據計算、數據庫調用等造成的。

在低吞吐量系統中，我們可以簡單地讓代碼運行直到它完成。但是，我們可能希望中止長時間運行的活動。

為了實現這一點，我們需要用未來（futures）處理我們的代碼。

讓我們在代碼中模擬一個非常耗時的過程：

ws.url(url)
  .get()
  .thenApply(
    result -> { 
        try { 
            Thread.sleep(10000L); 
            return Results.ok(); 
        } catch (InterruptedException e) { 
            return Results.status(SERVICE_UNAVAILABLE); 
        } 
    });

這將返回一個 OK 響應，但我們不想等待這麼長時間。

相反，使用 timeout 包裝器，我們指示代碼最多等待 1 秒。

CompletionStage<Result> f = futures.timeout(
  ws.url(url)
    .get()
    .thenApply(result -> {
        try {
            Thread.sleep(10000L);
            return Results.ok();
        } catch (InterruptedException e) {
            return Results.status(SERVICE_UNAVAILABLE);
        }
    }), 1L, TimeUnit.SECONDS);

現在，無論結果如何，我們的未來都會返回結果：如果消費者在規定時間內完成，則返回計算結果；否則，返回因期貨超時引起的異常。

5.5. 處理異常

在之前的示例中，我們創建了一個函數，該函數要麼返回結果，要麼拋出異常。因此，現在我們需要處理這兩個場景。

我們可以使用 handleAsync 方法來處理成功和失敗的場景。

假設我們想要在獲取到結果時返回結果，或者在發生錯誤時記錄錯誤並返回異常以便進一步處理：

CompletionStage<Object> res = f.handleAsync((result, e) -> {
    if (e != null) {
        log.error("Exception thrown", e);
        return e.getCause();
    } else {
        return result;
    }
});

代碼現在應該返回一個包含 TimeoutException 異常的 CompletionStage。

我們可以通過簡單地在返回的異常對象類上調用 assertEquals 來驗證它。

Class<?> clazz = res.toCompletableFuture().get().getClass();
assertEquals(TimeoutException.class, clazz);

當運行測試時，還會記錄我們接收到的異常：

[error] c.HomeControllerTest - Exception thrown
java.util.concurrent.TimeoutException: Timeout after 1 second
...

6. 請求過濾器

有時，我們需要在請求觸發之前運行一些邏輯。

我們可以初始化後操縱 WSRequest 對象，但更優雅的技術是設置 WSRequestFilter。

過濾器可以在初始化期間、在調用觸發方法之前設置，並附加到請求邏輯中。

我們可以通過實現 WSRequestFilter 接口來定義自己的過濾器，或者添加現成的過濾器。

常見場景是在執行請求之前記錄請求的內容。

在這種情況下，我們只需要設置 AhcCurlRequestLogger：

ws.url(url)
  ...
  .setRequestFilter(new AhcCurlRequestLogger())
  ...
  .get();

結果日誌具有curl 類似格式：

[info] p.l.w.a.AhcCurlRequestLogger - curl \
  --verbose \
  --request GET \
  --header 'key: value' \
  'http://localhost:19001'

我們可以通過修改我們的 logback.xml 配置來設置所需的日誌級別。

7. 響應緩存

WSClient 也支持響應緩存。

此功能在相同的請求被多次觸發時特別有用，並且我們不需要每次都獲取最新數據。

它也有助於在調用服務暫時不可用時提供幫助。

7.1. 添加緩存依賴

為了配置緩存，我們需要首先在我們的 build.sbt 中添加依賴：

libraryDependencies += ehcache

此配置將 Ehcache 用作我們的緩存層。

如果我們不想使用 Ehcache，我們可以使用任何其他 JSR-107 緩存實現。

7.2. 強制緩存啓發式

默認情況下，Play WS 不會緩存 HTTP 響應，除非服務器沒有返回任何緩存配置。

為了規避此限制，我們可以通過在 application.conf 中添加設置來強制啓用啓發式緩存：

play.ws.cache.heuristics.enabled=true

這將配置系統決定何時緩存 HTTP 響應，無論遠程服務是否聲明可以緩存。

8. 額外調整

向外部服務發送請求可能需要一些客户端配置。 我們可能需要處理重定向、慢速服務器或根據用户代理標頭進行過濾。

為了解決這個問題，我們可以調整我們的 WS 客户端，使用在 application.conf 中的屬性：

play.ws.followRedirects=false
play.ws.useragent=MyPlayApplication
play.ws.compressionEnabled=true
# time to wait for the connection to be established
play.ws.timeout.connection=30
# time to wait for data after the connection is open
play.ws.timeout.idle=30
# max time available to complete the request
play.ws.timeout.request=300

還可以配置底層的 AsyncHttpClient 直接。