Spring Boot 集成 WebClient 调用第三方接口实战指南

方式二：直接创建实例

如果不需要全局配置，也可以在需要的地方直接构建：

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

3. 构建 HTTP 请求与处理响应

WebClient 支持 GET、POST、PUT、DELETE 等方法，采用链式调用来设置 URL、头信息、查询参数和请求体。

GET 请求示例

调用第三方 API 获取数据时，记得添加认证头：

import reactor.core.publisher.Mono;

public Mono<String> getData(String apiPath) {
    return webClient.get()
            .uri(apiPath) // 例如："/users"
            .header("Authorization", "Bearer your_token")
            .retrieve()
            .bodyToMono(String.class);
}

POST 请求示例

发送 JSON 数据到第三方 API，bodyValue 会自动序列化为 JSON：

public Mono<String> postData(String apiPath, Object requestBody) {
    return webClient.post()
            .uri(apiPath)
            .header("Content-Type", "application/json")
            .bodyValue(requestBody)
            .retrieve()
            .bodyToMono(String.class);
}

反序列化为对象

如果第三方 API 返回 JSON，可以直接映射到 Java 对象：

public class User {
    private Long id;
    private String name;
    // Getters and setters
}

public Mono<User> getUserObject(String apiPath) {
    return webClient.get()
            .uri(apiPath)
            .retrieve()
            .bodyToMono(User.class);
}

4. 异步处理与错误控制

WebClient 返回 Mono 或 Flux 对象，你需要订阅来处理响应。在生产环境中，建议保持响应式风格，避免使用 block()。

Controller 中的异步处理

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {
    private final ApiClient apiClient;

    public UserController(ApiClient apiClient) {
        this.apiClient = apiClient;
    }

    @GetMapping("/user")
    public Mono<String> getUser() {
        return apiClient.getData("/users/1")
                .onErrorResume(e -> Mono.just("Error: " + e.getMessage()));
    }
}

超时与异常处理

设置请求超时，避免阻塞线程：

import io.netty.handler.timeout.ReadTimeoutException;
import reactor.netty.http.client.HttpClient;
import reactor.netty.resources.ConnectionProvider;

WebClient.builder()
        .clientConnector(new ReactorClientHttpConnector(
                HttpClient.create().responseTimeout(Duration.ofSeconds(10))))
        .build();

处理 HTTP 错误状态码（如 404 或 500）：

return webClient.get()
        .uri("/invalid-path")
        .retrieve()
        .onStatus(status -> status.is4xxClientError(), response -> Mono.error(new RuntimeException("Client error")))
        .bodyToMono(String.class);

5. 完整示例结构

以下是一个完整的 Spring Boot 应用示例，包含配置、服务和控制器：

主应用 (DemoApplication.java):

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

API 客户端 (ApiClient.java):

import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

@Component
public class ApiClient {
    private final WebClient webClient;

    public ApiClient(WebClient webClient) {
        this.webClient = webClient;
    }

    public Mono<String> getPosts() {
        return webClient.get()
                .uri("/posts")
                .retrieve()
                .bodyToMono(String.class);
    }
}

配置类 (WebClientConfig.java):

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.WebClient;

@Configuration
public class WebClientConfig {
    @Bean
    public WebClient webClient() {
        return WebClient.builder()
                .baseUrl("https://jsonplaceholder.typicode.com") // 免费测试 API
                .build();
    }
}

6. 抽象化设计与最佳实践

在实际项目中，建议对 WebClient 进行封装，以统一管理日志、异常和配置。

全局配置与日志

通过过滤器记录请求和响应日志：

import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.web.reactive.function.client.ClientRequest;
import org.springframework.web.reactive.function.client.ClientResponse;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import org.springframework.web.reactive.function.client.WebClient;

@Configuration
public class WebClientConfig {
    @Bean
    public WebClient webClient() {
        return WebClient.builder()
                .filter(logRequest())
                .filter(logResponse())
                .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
                .build();
    }

    private ExchangeFilterFunction logRequest() {
        return (request, next) -> {
            System.out.println("Request: " + request.method() + " " + request.url());
            return next.exchange(request);
        };
    }

    private ExchangeFilterFunction logResponse() {
        return ExchangeFilterFunction.ofResponseProcessor(response -> {
            System.out.println("Response status: " + response.statusCode());
            return Mono.just(response);
        });
    }
}

通用 API Service 封装

创建一个通用的 ApiService 来简化同步和异步调用，并统一异常处理：

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Mono;

@Service
@Slf4j
@RequiredArgsConstructor
public class ApiService {
    private final WebClient webClient;

    // 同步调用
    public <T, R> R callSync(String url, HttpMethod method, T requestBody, Class<R> responseType) {
        try {
            WebClient.RequestBodySpec requestSpec = webClient.method(method)
                    .uri(url)
                    .bodyValue(requestBody);
            return requestSpec.retrieve()
                    .onStatus(HttpStatusCode::isError, this::handleError)
                    .bodyToMono(responseType)
                    .block();
        } catch (Exception e) {
            log.error("API call failed", e);
            throw new ApiException("API 调用失败", e);
        }
    }

    // 异步调用
    public <T, R> Mono<R> callAsync(String url, HttpMethod method, T requestBody, Class<R> responseType) {
        return webClient.method(method)
                .uri(url)
                .bodyValue(requestBody)
                .retrieve()
                .onStatus(HttpStatusCode::isError, this::handleError)
                .bodyToMono(responseType);
    }

    private Mono<Throwable> handleError(ClientResponse response) {
        return response.bodyToMono(String.class)
                .flatMap(body -> Mono.error(new RuntimeException("API Error: " + body)));
    }
}

业务层调用

业务 Service 只需关注自身 DTO 定义，调用时传入 URL、方法类型和响应类型即可：

@Service
public class BusinessService {
    private final ApiService apiService;

    public BusinessResponse executeBusinessLogic(String param) {
        BusinessRequest request = new BusinessRequest(param, 100);
        return apiService.callSync(
                "https://api.thirdparty.com/endpoint",
                HttpMethod.POST,
                request,
                BusinessResponse.class
        );
    }
}

7. 总结

通过上述步骤，你可以在 Spring Boot 项目中高效地使用 WebClient 调用第三方接口。其优势在于高吞吐量、低资源消耗和现代化的 API 设计。在实际开发中，记得添加日志和监控以跟踪请求状态，并根据业务需求选择合适的同步或异步处理方式。