springboot3 WebClient

1 介绍

        在 Spring 5 之前，如果我们想要调用其他系统提供的 HTTP 服务，通常可以使用 Spring 提供的 RestTemplate 来访问，不过由于 RestTemplate 是 Spring 3 中引入的同步阻塞式 HTTP 客户端，因此存在一定性能瓶颈。根据 Spring 官方文档介绍，在将来的版本中它可能会被弃用。​ 作为替代，Spring 官方已在 Spring 5 中引入了 WebClient 作为非阻塞式 Reactive HTTP 客户端。

1.1 什么是 WebClient

        从 Spring 5 开始，Spring 中全面引入了 Reactive 响应式编程。而 WebClient 则是 Spring WebFlux 模块提供的一个非阻塞的基于响应式编程的进行 Http 请求的客户端工具。由于 WebClient 的请求模式属于异步非阻塞，能够以少量固定的线程处理高并发的 HTTP 请求。因此，从 Spring 5 开始，HTTP 服务之间的通信我们就可以考虑使用 WebClient 来取代之前的 RestTemplate。

1.2 WebClient 的优势

        与 RestTemplate 相比，WebClient 有如下优势：

• 非阻塞，Reactive 的，并支持更高的并发性和更少的硬件资源。
• 提供利用 Java 8 lambdas 的函数 API。
• 支持同步和异步方案。
• 支持从服务器向上或向下流式传输。

        RestTemplate 不适合在非阻塞应用程序中使用，因此 Spring WebFlux 应用程序应始终使用 WebClient。在大多数高并发场景中，WebClient 也应该是 Spring MVC 中的首选，并且用于编写一系列远程，相互依赖的调用。

2 使用 WebClient

2.1 创建 WebClient 实例

        添加 Spring WebFlux 依赖，从而可以使用 WebClient。

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

        有三种方式可供选择。第一种是使用默认设置创建 WebClient 对象：

WebClient client = WebClient.create();

        第二种方式是使用给定的基本 URI 初始化 WebClient 实例：

WebClient client = WebClient.create("http://localhost:8080");

        第三种方式（推荐）是使用 DefaultWebClientBuilder 类构建客户端，该类允许完全自定义：

WebClient client = WebClient.builder().baseUrl("http://localhost:8080").defaultCookie("cookieKey", "cookieValue").defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) .defaultUriVariables(Collections.singletonMap("url", "http://localhost:8080")).build();

2.2 指定超时时间

        通常情况下，默认的 30 秒 HTTP 超时时间太慢，无法满足需要，要自定义这种行为，可以创建一个 HttpClient 实例，并配置 WebClient 使用它。

• 通过 ChannelOption.CONNECT_TIMEOUT_MILLIS 选项设置连接超时。
• 分别使用 ReadTimeoutHandler 和写 WriteTimeoutHandler 设置读、写超时。
• 使用 responseTimeout 指令配置响应超时。

        所有这些都必须在要配置的 HttpClient 实例中指定：

      HttpClient httpClient = HttpClient.create().option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000).responseTimeout(Duration.ofMillis(5000)).doOnConnected(conn ->conn.addHandlerLast(new ReadTimeoutHandler(5000, TimeUnit.MILLISECONDS)).addHandlerLast(new WriteTimeoutHandler(5000, TimeUnit.MILLISECONDS)));WebClient client = WebClient.builder().clientConnector(new ReactorClientHttpConnector(httpClient)).build();

        注意，虽然也可以在客户端请求中调用 timeout，但这是信号超时，而不是 HTTP 连接、读/写或响应超时；这是 Mono / Flux Publisher 的超时。

2.3 准备请求 - 定义方法

        首先，需要通过调用 method(HttpMethod method) 来指定请求的 HTTP 方法：

UriSpec<RequestBodySpec> uriSpec = client.method(HttpMethod.POST);

        或调用其快捷方法，如 get、post 和 delete：

        WebClient.RequestHeadersUriSpec<?> get = client.get();WebClient.RequestBodyUriSpec post = client.post();WebClient.RequestBodyUriSpec put = client.put();WebClient.RequestHeadersUriSpec<?> delete = client.delete();

        注意：虽然看起来重用了 Request Spec 变量（WebClient.UriSpec、WebClient.RequestBodySpec、WebClient.RequestHeadersSpec、WebClient.ResponseSpec），但这只是为了简化演示不同的方法。这些指令不应该在不同请求中重复使用，因为它们会检索引用，因此后面的操作会修改在前面步骤中所定义的内容。

2.4 准备请求 - 定义 URL

        下一步是提供 URL。同样，也有不同的方法。可以将其作为字符串传递给 uri API：

RequestBodySpec bodySpec = uriSpec.uri("/resource");

        使用 UriBuilder Function 接口：

RequestBodySpec bodySpec = uriSpec.uri(uriBuilder -> uriBuilder.pathSegment("/resource").build());

        或者，传递一个 java.net.URL 实例：

RequestBodySpec bodySpec = uriSpec.uri(URI.create("/resource"));

        注意，如果为 WebClient 定义了默认的基本 URL，那么最后一个方法将覆盖该值。

2.5 准备请求 - 定义请求体

        然后，可以根据需要设置请求体（Body）、Content Type、Length、Cookie 或 Header。例如，如果要设置请体，有几种可用的方法。最常见、最直接的方法可能就是使用 bodyValue 方法：

RequestHeadersSpec<?> headersSpec = bodySpec.bodyValue("data");

        或者通过将一个 Publisher（以及将要发布的元素类型）传递给 body 方法来实现：

RequestHeadersSpec<?> headersSpec = bodySpec.body(Mono.just(new Foo("name")), Foo.class);

        另外，还可以使用 BodyInserters 工具类。例如，来看看如何像使用 bodyValue 方法那样，使用一个简单的对象来作为请求体。

RequestHeadersSpec<?> headersSpec = bodySpec.body(BodyInserters.fromValue("data"));

        同样，如果使用的是 Reactor 实例，也可以使用 BodyInserters#fromPublisher 方法：

RequestHeadersSpec headersSpec = bodySpec.body(BodyInserters.fromPublisher(Mono.just("data")),String.class);

        该类还提供其他直观的功能，以覆盖更高级的应用场景。例如，发送 multipart 请求：

LinkedMultiValueMap map = new LinkedMultiValueMap();
map.add("key1", "value1");
map.add("key2", "value2");
RequestHeadersSpec<?> headersSpec = bodySpec.body(BodyInserters.fromMultipartData(map));

        所有这些方法都会创建一个 BodyInserter 实例，然后可以将其作为请求体（Request Body）。

• BodyInserter 是一个接口，负责用给定的输出消息和插入时使用的 Context 填充 ReactiveHttpOutputMessage。
• Publisher 是一个响应式组件，负责提供数量可能无限的序列化元素。它也是一个接口，最常用的实现是 Mono 和 Flux。

2.6 准备请求 - 定义 Header

        设置 body 后，可以设置 Header、Cookie 和可接受的媒体类型。这些值将添加到实例化客户端时已设置的值中。此外，还为 If-None-Match、If-Modified-Since、Accept 和 Accept-Charset 等最常用的 Header 提供了额外支持。示例如下：

ResponseSpec responseSpec = headersSpec.header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE).accept(MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML).acceptCharset(StandardCharsets.UTF_8).ifNoneMatch("*").ifModifiedSince(ZonedDateTime.now()).retrieve();

2.7 获取响应

        最后一个阶段是发送请求并接收响应。可以使用 exchangeToMono / exchangeToFlux 或 retrieve 方法来实现。exchangeToMono 和 exchangeToFlux 方法允许访问 ClientResponse 及其 HTTP 状态码和 Header：

Mono<String> response = headersSpec.exchangeToMono(response -> {if (response.statusCode().equals(HttpStatus.OK)) {return response.bodyToMono(String.class);} else if (response.statusCode().is4xxClientError()) {return Mono.just("Error response");} else {return response.createException().flatMap(Mono::error);}
});

        而 retrieve 方法是直接获取响应 Body 的最便捷的方式：

Mono<String> response = headersSpec.retrieve().bodyToMono(String.class);

        需要注意 ResponseSpec.bodyToMono 方法，如果状态码为 4xx（客户端错误）或 5xx（服务器错误），该方法将抛出 WebClientException。

        将response body 转换为对象/集合

• bodyToMono：如果返回结果是一个Object，WebClient将接收到响应后把JSON字符串转换为对应的对象，并通过Mono流弹出。

• bodyToFlux：如果响应的结果是一个集合，则不能继续使用bodyToMono()，应该改用bodyToFlux()，然后依次处理每一个元素，并通过Flux流弹出。