知識庫 / Reactive RSS 訂閱

1. 概述

WebClient 是一個簡化執行 HTTP 請求過程的接口。與 RestTemplate 不同，它是一個反應式且非阻塞的客户端，可以消費和操作 HTTP 響應。雖然它被設計為非阻塞的，但也可以在阻塞場景中使用。

在本教程中，我們將深入研究 WebClient 接口中的關鍵方法，包括 retrieve()、exchangeToMono() 和 exchangeToFlux()。我們還將探討這些方法之間的差異和相似之處，並提供示例以展示不同的用例。此外，我們還將使用 JSONPlaceholder API 獲取用户數據。

2. 示例配置

首先，讓我們創建一個 Spring Boot 應用程序，並添加 spring-boot-starter-webflux 依賴項到 pom.xml 中：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
    <version>3.2.4</version>
</dependency>

這個依賴項提供WebClient接口，使我們能夠執行HTTP請求。

此外，讓我們來看一個從請求https://jsonplaceholder.typicode.com/users/1返回的示例GET響應：

{
  "id": 1,
  "name": "Leanne Graham",
// ...
}

此外，讓我們創建一個名為 User 的 POJO 類：

class User {

    private int id;
    private String name;

   // standard constructor,getter, and setter

}

來自 JSONPlaceholder API 的 JSON 響應將被反序列化並映射到 User 類的一個實例。

最後，我們創建一個 WebClient 實例，並設置基本 URL：

WebClient client = WebClient.create("https://jsonplaceholder.typicode.com/users");

這裏，我們定義了 HTTP 請求的基URL。

3. exchange() 方法

exchange() 方法直接返回 ClientResponse 對象，從而提供對 HTTP 狀態碼、頭部和響應體訪問。 簡單來説，ClientResponse 代表由 WebClient 返回的 HTTP 響應。

然而，自 Spring 5.3 版本起，此方法已被棄用，並被 exchangeToMono() 或 exchangeToFlux() 方法取代，具體取決於我們發出的內容。這兩個方法允許我們根據響應狀態解碼響應。

3.1. 發射 Mono 對象

下面是一個使用 exchangeToMono() 方法發射 Mono 對象的示例：

@GetMapping("/user/exchange-mono/{id}")
Mono<User> retrieveUsersWithExchangeAndError(@PathVariable int id) {
    return client.get()
      .uri("/{id}", id)
      .exchangeToMono(res -> {
          if (res.statusCode().is2xxSuccessful()) {
              return res.bodyToMono(User.class);
          } else if (res.statusCode().is4xxClientError()) {
              return Mono.error(new RuntimeException("Client Error: can't fetch user"));
          } else if (res.statusCode().is5xxServerError()) {
              return Mono.error(new RuntimeException("Server Error: can't fetch user"));
          } else {
              return res.createError();
           }
     });
}

在上述代碼中，我們檢索用户並根據 HTTP 狀態碼解碼響應。

3.2. 發出 Flux 信號

此外，我們使用 exchangeToFlux() 方法來獲取用户集合：

@GetMapping("/user-exchange-flux")
Flux<User> retrieveUsersWithExchange() {
   return client.get()
     .exchangeToFlux(res -> {
         if (res.statusCode().is2xxSuccessful()) {
             return res.bodyToFlux(User.class);
         } else {
             return Flux.error(new RuntimeException("Error while fetching users"));
         }
    });
}

在這裏，我們使用 exchangeToFlux() 方法將響應體映射為 Flux 中 User 對象，並在請求失敗時返回自定義錯誤消息。

3.3. 直接獲取響應體

值得注意的是，exchangeToMono() 或 exchangeToFlux() 可以無需指定響應狀態碼進行使用：

@GetMapping("/user-exchange")
Flux<User> retrieveAllUserWithExchange(@PathVariable int id) {
    return client.get().exchangeToFlux(res -> res.bodyToFlux(User.class))
      .onErrorResume(Flux::error);
}

在這裏，我們檢索用户，不指定狀態碼。

3.4. 修改響應體

此外，我們來看一個修改響應體的示例：

@GetMapping("/user/exchange-alter/{id}")
Mono<User> retrieveOneUserWithExchange(@PathVariable int id) {
    return client.get()
      .uri("/{id}", id)
      .exchangeToMono(res -> res.bodyToMono(User.class))
      .map(user -> {
          user.setName(user.getName().toUpperCase());
          user.setId(user.getId() + 100);
          return user;
      });
}

在上述代碼中，在將響應體映射到POJO類後，我們通過在id中添加100和將name轉換為大寫來修改響應體。

特別地，我們還可以使用retrieve()方法來修改響應體。

3.5. 提取響應頭信息

此外，我們還可以提取響應頭信息：

@GetMapping("/user/exchange-header/{id}")
Mono<User> retrieveUsersWithExchangeAndHeader(@PathVariable int id) {
  return client.get()
    .uri("/{id}", id)
    .exchangeToMono(res -> {
        if (res.statusCode().is2xxSuccessful()) {
            logger.info("Status code: " + res.headers().asHttpHeaders());
            logger.info("Content-type" + res.headers().contentType());
            return res.bodyToMono(User.class);
        } else if (res.statusCode().is4xxClientError()) {
            return Mono.error(new RuntimeException("Client Error: can't fetch user"));
        } else if (res.statusCode().is5xxServerError()) {
            return Mono.error(new RuntimeException("Server Error: can't fetch user"));
        } else {
            return res.createError();
        }
    });
}

在這裏，我們記錄 HTTP 頭部和內容類型到控制枱。 與需要返回 ResponseEntity才能訪問頭部和響應碼的 retrieve()方法不同，exchangeToMono()由於它返回 ClientResponse，因此我們能夠直接訪問。

4. retrieve() 方法

retrieve() 方法簡化了從 HTTP 請求中提取響應體。它返回 ResponseSpec，允許我們指定響應體應如何處理，而無需訪問完整的 ClientResponse。

ClientResponse 包含響應代碼、頭信息和響應體。因此，ResponseSpec 包含響應體，但不包含響應代碼和頭信息。

4.1. 發出 單聲道 數據包

以下是一個用於檢索 HTTP 響應體示例代碼：

@GetMapping("/user/{id}")
Mono<User> retrieveOneUser(@PathVariable int id) {
    return client.get()
      .uri("/{id}", id)
      .retrieve()
      .bodyToMono(User.class)
      .onErrorResume(Mono::error);
}

在上述代碼中，我們通過向 /users 終點進行 HTTP 調用，並指定一個 id，從基礎 URL 獲取 JSON 數據。然後，我們將響應體映射到 User 對象。

4.2. 發送 Flux</em/> 請求

@GetMapping("/users")
Flux<User> retrieveAllUsers() {
    return client.get()
      .retrieve()
      .bodyToFlux(User.class)
      .onResumeError(Flux::error);
}

@GetMapping("/user-id/{id}")
Mono<ResponseEntity<User>> retrieveOneUserWithResponseEntity(@PathVariable int id) {
    return client.get()
      .uri("/{id}", id)
      .accept(MediaType.APPLICATION_JSON)
      .retrieve()
      .toEntity(User.class)
      .onErrorResume(Mono::error);
}

@GetMapping("/user-status/{id}")
Mono<User> retrieveOneUserAndHandleErrorBasedOnStatus(@PathVariable int id) {
    return client.get()
      .uri("/{id}", id)
      .retrieve()
      .onStatus(HttpStatusCode::is4xxClientError, 
        response -> Mono.error(new RuntimeException("Client Error: can't fetch user")))
      .onStatus(HttpStatusCode::is5xxServerError, 
        response -> Mono.error(new RuntimeException("Server Error: can't fetch user")))
      .bodyToMono(User.class);
}

@State(Scope.Benchmark)
@BenchmarkMode(Mode.AverageTime)
@Warmup(iterations = 3, time = 10, timeUnit = TimeUnit.MICROSECONDS)
@Measurement(iterations = 3, time = 10, timeUnit = TimeUnit.MICROSECONDS)
public class RetrieveAndExchangeBenchmarkTest {
  
    private WebClient client;

    @Setup
    public void setup() {
        this.client = WebClient.create("https://jsonplaceholder.typicode.com/users");
    }
}

@Benchmark
Flux<User> retrieveManyUserUsingRetrieveMethod() {
    return client.get()
      .retrieve()
      .bodyToFlux(User.class)
      .onErrorResume(Flux::error);;
}

@Benchmark
Flux<User> retrieveManyUserUsingExchangeToFlux() {
    return client.get()
      .exchangeToFlux(res -> res.bodyToFlux(User.class))
      .onErrorResume(Flux::error);
}

Benchmark                             Mode  Cnt   Score    Error  Units
retrieveManyUserUsingExchangeToFlux   avgt   15  ≈ 10⁻⁴            s/op
retrieveManyUserUsingRetrieveMethod   avgt   15  ≈ 10⁻³            s/op