Spring WebFlux 与 WebClient 使用指南及最佳实践_Java

spring webflux 与 webclient 使用指南

1. webclient 概述

webclient 是 spring webflux 模块提供的非阻塞、响应式 http 客户端，基于 project reactor 实现，适用于高并发场景。
核心优势：

支持异步非阻塞 i/o，提升吞吐量。
链式 api 设计，便于组合操作。
集成 spring 生态，支持自动编解码（json、xml）。

2. 核心依赖配置

在 pom.xml 中添加依赖：

<dependency>
    <groupid>org.springframework.boot</groupid>
    <artifactid>spring-boot-starter-webflux</artifactid>
</dependency>

3. webclient 的创建与配置

3.1 全局配置（推荐）

@configuration
public class webclientconfig {
    @bean
    public webclient webclient() {
        return webclient.builder()
            .baseurl("https://api.example.com") // 基础 url
            .defaultheader("accept", "application/json")
            .clientconnector(new reactorclienthttpconnector(
                httpclient.create()
                    .responsetimeout(duration.ofseconds(30)) // 响应超时
            )
            .build();
    }
}

3.2 临时创建（按需使用）

webclient client = webclient.create("https://api.example.com");

4. 发送 http 请求

4.1 get 请求（携带 token）

public mono<user> getuser(string id, string token) {
    return webclient.get()
        .uri("/users/{id}", id) // 路径参数
        .header("token-test", token) // 自定义 token
        .retrieve()
        .bodytomono(user.class); // 解析为对象
}

4.2 post 请求（发送数组 body）

public mono<string> postusers(list<user> users, string token) {
    return webclient.post()
        .uri("/users/batch")
        .header("token-test", token)
        .contenttype(mediatype.application_json)
        .bodyvalue(users) // 发送 list 集合
        .retrieve()
        .bodytomono(string.class);
}

5. 错误处理

5.1 http 错误处理（onstatus）

.onstatus(httpstatus::iserror, response ->
    response.bodytomono(string.class)
        .flatmap(errorbody -> {
            string msg = string.format("状态码: %d, 错误信息: %s", 
                response.rawstatuscode(), errorbody);
            log.error(msg);
            return mono.error(new serviceexception(msg));
        })
)

5.2 非 http 错误处理（doonerror）

.doonerror(error -> {
    if (!(error instanceof serviceexception)) {
        log.error("非 http 错误: {}", error.getmessage());
    }
})

6. 同步与异步调用

6.1 异步调用（subscribe）

webclient.get()
    .uri("/data")
    .retrieve()
    .bodytomono(string.class)
    .subscribe(
        data -> log.info("成功: {}", data),
        error -> log.error("失败: {}", error)
    );

6.2 同步调用（block，仅用于测试或特殊场景）

try {
    string result = webclient.get()
        .uri("/data")
        .retrieve()
        .bodytomono(string.class)
        .block(duration.ofseconds(10)); // 阻塞等待
} catch (exception e) {
    log.error("请求失败", e);
}

7. 统一响应结构

7.1 定义统一响应类

public class apiresponse<t> {
    private int code;
    private string message;
    private t data;
    public static <t> apiresponse<t> success(t data) {
        return new apiresponse<>(200, "success", data);
    }
    public static <t> apiresponse<t> error(int code, string message) {
        return new apiresponse<>(code, message, null);
    }
}

7.2 转换响应

public mono<apiresponse<user>> getuser(string id) {
    return webclient.get()
        .uri("/users/{id}", id)
        .retrieve()
        .bodytomono(user.class)
        .map(apiresponse::success) // 包装为成功响应
        .onerrorresume(e -> 
            mono.just(apiresponse.error(500, e.getmessage()))
        );
}

8. 日志与监控

8.1 成功日志

.doonsuccess(response -> 
    log.info("请求成功: {}", response)
)

8.2 错误日志

.doonerror(error -> 
    log.error("请求失败: {}", error.getmessage())
)

9. 高级配置

9.1 超时与重试

.clientconnector(new reactorclienthttpconnector(
    httpclient.create()
        .responsetimeout(duration.ofseconds(30)) // 响应超时
)
.retrywhen(retry.backoff(3, duration.ofseconds(1))) // 指数退避重试

9.2 连接池配置

httpclient.create()
    .baseurl("https://api.example.com")
    .tcpconfiguration(tcpclient -> 
        tcpclient.option(channeloption.connect_timeout_millis, 5000)
    )

10. 常见问题与最佳实践

10.1 避免手动调用subscribe

错误示例：

// service 层中手动调用 subscribe（不推荐）
public void senddata() {
    webclient.post().subscribe(); // 可能导致资源泄漏
}

正确做法：
在 controller 或调用方返回 mono/flux，由框架处理订阅。

10.2 统一异常处理

@controlleradvice
public class globalexceptionhandler {
    @exceptionhandler(serviceexception.class)
    @responsestatus(httpstatus.internal_server_error)
    public mono<apiresponse<?>> handleserviceexception(serviceexception e) {
        return mono.just(apiresponse.error(500, e.getmessage()));
    }
}

10.3 性能优化

复用 webclient 实例：避免频繁创建新实例。
合理设置超时：根据接口 sla 调整响应和连接超时。

附录：完整代码示例

发送 post 请求并处理错误

public mono<apiresponse<string>> syncdata(list<user> users, string token) {
    string uri = uricomponentsbuilder.fromuristring("https://api.example.com")
        .path("/batch")
        .queryparam("source", "web")
        .queryparamifpresent("type", optional.ofnullable("test".equals(activeprofile) ? "test" : null))
        .build()
        .touristring();
    return webclient.post()
        .uri(uri)
        .header("token-test", token)
        .headers(headers -> {
             if ("test".equals(activeprofile)) {
                 headers.add("type", "test"); // 仅测试环境添加
             }
         })
        .contenttype(mediatype.application_json)
        .bodyvalue(users)
        .retrieve()
        .onstatus(httpstatus::iserror, response ->
                response.bodytomono(string.class)
                        .flatmap(error -> {
                            string msg = string.format("状态码：%d, 错误信息: %s", response.rawstatuscode(), error);
                            log.error(msg);
                            return mono.error(new runtimeexception(msg));
                        })
        )
        .bodytomono(apiresponse.class)  // 解析为自定义响应对象
         // 检查业务状态码
        .flatmap(result -> {
            if (result.getstatuscode() != 200) {
                string msg = string.format("业务错误: code=%d, message=%s",
                        result.getstatuscode(), result.getmessage());
                log.error(msg);
                return mono.error(new serviceexception(msg));
            }
            return mono.just(result);
        })
         // 成功记录日志
        .doonsuccess(success -> log.info("请求成功"))
         // 失败记录日志
        .doonerror(error -> log.error("失败", error.getmessage()))
        .onerrorresume(e -> 
           mono.just(apiresponse.error(500, e.getmessage()))
        );
}

通过本文档，您可全面掌握 webclient 的核心用法、错误处理策略及性能优化技巧。建议结合项目需求灵活调整配置，遵循响应式编程最佳实践。

到此这篇关于spring webflux 与 webclient 使用指南及最佳实践的文章就介绍到这了,更多相关spring webflux webclient 使用内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

Spring WebFlux 与 WebClient 使用指南及最佳实践

2025年07月03日 • Java •我要评论