JAVA：Spring WebClient 的应用指南

1、简述

随着微服务架构的普及，服务间的 HTTP 通信需求也越来越多。Spring 提供的 WebClient 是 RestTemplate 的替代方案，支持响应式编程，具有非阻塞的特点，非常适合处理高并发的 HTTP 请求。本文将介绍 WebClient 的基本用法及其在实际项目中的使用场景。

2、核心特点

WebClient 是 Spring 5 引入的一个新的 HTTP 客户端，作为 RestTemplate 的替代方案。RestTemplate 是基于同步阻塞的模型，而 WebClient 是基于响应式编程的模型，提供了更好的性能和扩展性，特别适合在微服务架构中处理非阻塞、高并发的 HTTP 请求。

非阻塞 IO：使用 Reactor 作为响应式框架，具有很好的并发性能。
灵活性：支持 GET、POST、PUT、DELETE 等多种请求方式。
更丰富的功能：支持同步、异步请求，且易于集成 OAuth2 等安全认证机制。

3、基本用法

WebClient 的创建方式有两种：通过 WebClient.create() 创建无参的默认客户端，或者使用 WebClient.builder() 创建带自定义配置的客户端。

3.1 基本 GET 请求

bash 复制代码

WebClient webClient = WebClient.create("https://api.example.com");

String result = webClient.get()
        .uri("/data")
        .retrieve()
        .bodyToMono(String.class)
        .block(); // 阻塞方法，等待响应
System.out.println("Result: " + result);

在上面的例子中，retrieve() 方法用于获取响应体，bodyToMono(String.class) 表示将响应体解析为 String 类型。调用 block() 方法会阻塞当前线程，直到拿到响应。

3.2 基本 POST 请求

bash 复制代码

Mono<String> response = webClient.post()
        .uri("/submit")
        .header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
        .bodyValue(new MyRequestObject("sampleData"))
        .retrieve()
        .bodyToMono(String.class);

response.subscribe(result -> System.out.println("Response: " + result));

这里使用了 subscribe() 方法，可以实现异步非阻塞的请求处理。

4、使用场景

以下是一些 WebClient 的常见使用场景，并提供了相应的代码示例。

4.1 微服务间的 RESTful 通信

在微服务架构中，不同服务之间需要通过 HTTP 互相调用。WebClient 提供了异步调用的能力，非常适合在微服务中作为 HTTP 客户端使用。

bash 复制代码

@Service
public class OrderService {

    private final WebClient webClient;

    public OrderService(WebClient.Builder builder) {
        this.webClient = builder.baseUrl("http://inventory-service").build();
    }

    public Mono<Product> getProductById(String productId) {
        return webClient.get()
                .uri("/products/{id}", productId)
                .retrieve()
                .bodyToMono(Product.class);
    }
}

在这里，OrderService 调用了 inventory-service 微服务的 /products/{id} 接口。通过 Mono 类型返回，整个请求是异步执行的，不会阻塞主线程，从而提升了系统的并发处理能力。

4.2 批量并发请求

有时候我们需要对多个接口或同一个接口进行批量调用。WebClient 的非阻塞特性非常适合处理这种高并发的请求。

bash 复制代码

public List<Mono<Product>> getProducts(List<String> productIds) {
    return productIds.stream()
            .map(id -> webClient.get()
                    .uri("/products/{id}", id)
                    .retrieve()
                    .bodyToMono(Product.class))
            .collect(Collectors.toList());
}

public List<Product> getAllProducts(List<String> productIds) {
    return Flux.merge(getProducts(productIds))
            .collectList()
            .block();  // 阻塞等待所有请求完成
}

在上例中，getProducts 方法返回每个请求的 Mono，Flux.merge 将所有的请求合并为一个响应流，从而并发地执行这些请求，并最终返回结果列表。

4.3 处理超时和重试机制

在分布式系统中，网络问题可能导致请求超时或失败。WebClient 支持通过 timeout 和 retry 方法来设置超时和重试机制。

bash 复制代码

public Mono<String> fetchWithTimeoutAndRetry() {
    return webClient.get()
            .uri("/unstable-endpoint")
            .retrieve()
            .bodyToMono(String.class)
            .timeout(Duration.ofSeconds(3)) // 设置超时时间为 3 秒
            .retry(3) // 最多重试 3 次
            .onErrorReturn("Fallback response"); // 如果仍然失败则返回默认值
}

在此示例中，如果请求超过 3 秒未响应，将触发 timeout，并进行最多 3 次重试操作。若所有尝试都失败，则返回 "Fallback response"。

4.4 异步文件上传

WebClient 支持文件上传，适用于处理异步文件传输的场景，比如上传用户头像、导入 CSV 文件等。

bash 复制代码

public Mono<String> uploadFile(Resource fileResource) {
    return webClient.post()
            .uri("/upload")
            .contentType(MediaType.MULTIPART_FORM_DATA)
            .body(BodyInserters.fromMultipartData("file", fileResource))
            .retrieve()
            .bodyToMono(String.class);
}

在此示例中，我们使用 BodyInserters.fromMultipartData 将文件资源上传到指定接口。整个上传过程是非阻塞的，非常适合高并发上传的场景。

4.5 OAuth2 认证集成

在调用第三方 API 时，通常需要 OAuth2 认证。WebClient 支持通过 OAuth2 来配置认证，简化了与安全 API 的集成。

bash 复制代码

@Configuration
public class WebClientConfig {

    @Bean
    public WebClient webClient(ReactiveOAuth2AuthorizedClientManager authorizedClientManager) {
        ServerOAuth2AuthorizedClientExchangeFilterFunction oauth2 =
                new ServerOAuth2AuthorizedClientExchangeFilterFunction(authorizedClientManager);
        oauth2.setDefaultOAuth2AuthorizedClient(true);
        
        return WebClient.builder()
                .filter(oauth2)
                .baseUrl("https://api.oauth-provider.com")
                .build();
    }
}

在这里，通过 ReactiveOAuth2AuthorizedClientManager 配置了 WebClient 的 OAuth2 认证，确保请求会携带认证 token，从而实现了安全访问。

5、总结

WebClient 是一个强大且灵活的 HTTP 客户端，特别适合在微服务架构中处理复杂的 HTTP 通信需求。相比 RestTemplate，WebClient 提供了更高效的异步和非阻塞能力，支持流式数据处理和多种认证方式。对于高并发、多请求和需要保证响应时效的应用场景，WebClient 提供了更高效的解决方案。