本文说明响应式编程模型与 Spring WebFlux 的落地方式。虚拟线程作为另一条异步化路径的机制与取舍见 虚拟线程在 Web 应用中的落地,同步模型的请求处理链路见 Spring MVC 请求处理链路,容器线程模型见 Servlet 容器运行时,IO 模型与事件驱动的基础见 IO 模型与 Netty,并发基础见 并发编程,服务间响应式调用见 gRPC 与 HTTP 客户端,推送场景的实现见 实时通信在集群下的落地。

一、起源

1.1 阻塞模型的两项约束

每请求一线程的模型中,线程在等待下游响应期间无法服务其他请求,因此并发上限由线程数决定,而线程数受内存与调度成本约束。约束体现在两处:

约束 表现 影响
线程成本 每个线程需要独立的栈空间 线程数达到数千后内存占用显著
等待占比 请求处理的大部分时间消耗在等待下游 资源被"等待"占用,而非被计算占用

1.2 异步化的两条路径

路径 做法 代价
响应式数据流 用数据流与算子描述处理过程,IO 就绪时由事件驱动推进 编程模型改变,调试与排障难度上升,生态要求全链路非阻塞
虚拟线程 保留同步写法,由 JVM 在阻塞时切换载体线程 依赖 JDK 版本与固定操作的消除,仍需处理上下文传递

两条路径解决的是同一个问题(等待期间不占用昂贵资源),但改变了不同的东西:响应式改变编程模型以换取资源效率,虚拟线程改变运行时调度以保留编程模型。

1.3 取舍

响应式仍有独立价值的场景:

  • 需要背压:消费者处理能力不足时,需要一种机制让生产端降速,这在流式传输与事件流中不可替代。
  • 流式与推送:需要按需产生数据并从同一连接持续输出的场景,数据流模型表达更自然。
  • 连接数极高且单请求内存敏感:事件循环模型下每连接的常驻内存更低。

不适合的场景:CPU 密集型任务、上下游存在阻塞驱动、团队缺少响应式排障经验且业务并发未达阈值。

二、原理

2.1 发布者与订阅者

响应式的执行由订阅触发,而不是由数据源创建触发:

Publisher(数据源,声明"如何产生数据")
   ^
   |  subscribe(subscriber)
   |
Subscriber(消费方)
   |  onSubscribe(subscription)
   |  request(n)          <- 声明可接收的数量
   |< onNext(item) x n
   |< onComplete() / onError(e)

三个要点:

  • 没有订阅就没有执行。返回数据流的方法只是装配了处理管道,真正的执行发生在订阅时,因此"方法返回了但日志没有输出"通常是因为未订阅。
  • 订阅关系只有一条:一个数据流被订阅多次会执行多次,共享结果需要显式转换(如 share()、cache())。
  • 错误与完成是终止信号:任一方发出后,订阅关系结束,后续不再有元素。

2.2 冷流与热流

类型 行为 典型来源
冷流 每个订阅者独立触发一次数据产生过程 数据库查询、HTTP 请求、集合遍历
热流 数据产生与订阅无关,订阅者只接收订阅之后的事件 事件总线、传感器数据、广播流

区分意义在于重复执行成本与丢帧行为:冷流被多次订阅会重复执行查询;热流在无订阅者时产生的事件会丢失。把冷流转为热流需要显式操作,且要明确"订阅前的数据是否需要缓存"。

2.3 背压

背压是消费者与生产者之间的请求量协商,通过 request(n) 表达。它解决的问题是:当生产速度快于消费速度时,数据在哪里堆积。

处理策略 行为 代价
缓冲 放入内存或磁盘队列 内存增长,极端情况下溢出
丢弃 丢弃装不下的元素 数据不完整,需要业务上可接受
保留最新 只保留最后一个元素 中间元素丢失
报错 超出容量即终止 需要调用方处理该错误

失控的表现有三种可观察形态:内存持续增长(无界缓冲)、响应时间随负载线性上升(排队)、下游出现超时或拒绝(压力被传递)。判断方式是把背压策略与下游容量一起核对,而不是只看上游是否设置了容量参数。

2.4 调度器与线程边界

数据流的执行发生在哪个线程由调度器决定,两个位置语义不同:

操作 作用位置 效果
订阅位置 影响数据源与上游的执行线程 只对最靠近数据源的订阅生效,多次设置以最靠近数据源的为准
发布位置 影响其下游算子的执行线程 可多次设置,每次只影响其后的算子

常用调度器:

调度器 线程特征 适用
单线程 单一线程顺序执行 需要严格顺序且低并发的场景
并行 固定大小,通常等于处理器数 CPU 密集型计算
有界弹性 弹性伸缩但有上限与队列约束 必须执行的阻塞调用
立即 不切换线程,在当前线程执行 明确知道当前线程可用的场景

结论:计算类工作放在并行调度器上,阻塞类工作放在有界弹性调度器上,且必须为阻塞工作设置容量上限,避免弹性线程无界增长。

2.5 算子中的隐藏阻塞

响应式的收益依赖"整条链路不阻塞"。链路上出现阻塞调用的后果比同步模型更严重:阻塞的不是一个请求线程,而是事件循环线程,会影响该线程上所有请求。

常见隐藏位置:

位置 表现 识别方式
算子内同步调用 map 中执行了阻塞查询 阻塞检测工具会在运行时报告
同步驱动 使用了阻塞式数据库或 HTTP 客户端 链路中缺少非阻塞驱动
日志与序列化 同步文件写入、大对象序列化 压测时事件循环线程占用高
锁与同步块 在事件循环线程上竞争锁 线程转储中出现等待状态

处理方式是把阻塞调用隔离到有界弹性调度器,而不是在事件循环上执行;但这只是隔离,若阻塞占比高,收益会被弹性线程的上限抵消。

2.6 WebFlux 的执行模型

WebFlux 运行在非阻塞服务器之上,请求处理默认在事件循环线程上执行:

事件循环线程(数量通常等于处理器数)
  |  接收连接、解析请求、执行处理链
  |  遇到 IO -> 注册回调并释放线程
  v
IO 就绪 -> 事件循环继续推进该请求的后续处理

与同步模型的四点差异:

维度 同步(每请求一线程) 响应式(事件循环)
请求并发上限 由线程数决定 由事件循环数量与下游容量决定
阻塞后果 影响该请求 影响该线程上的全部请求
上下文载体 线程局部变量 数据流上下文
排障方式 线程转储可看到请求栈 需借助算子级日志与检查点

阻塞检测通常借助运行时插桩工具实现,它在检测到事件循环线程上的阻塞调用时抛出异常或记录堆栈,是上线前必须启用的一项检查。

2.7 非阻塞驱动的边界

响应式的完整收益要求从入口到存储全链路非阻塞:

环节 是否具备非阻塞实现 说明
HTTP 服务端 具备 响应式服务器
HTTP 客户端 具备 响应式客户端
关系型数据库 具备但生态受限 需要响应式驱动,SQL 能力与成熟度弱于同步驱动
缓存 具备 响应式客户端
消息中间件 部分具备 部分客户端为阻塞实现,需要隔离
文件与对象存储 部分具备 部分 SDK 为阻塞实现

结论:链路上存在阻塞实现的环节越多,响应式的收益越低,而此时隔离到弹性调度器又会使线程数重新成为约束。因此响应式的适用判断应先做链路盘点,而不是先选框架。

2.8 与虚拟线程的取舍

维度 响应式 虚拟线程
编程模型 数据流与算子,需重写业务逻辑 同步写法
背压 原生支持 无对应机制,需要自行限流
调试 调用栈断裂,需专门手段 调用栈完整
生态要求 全链路非阻塞 无额外要求
内存特征 每连接常驻更低 每任务一个虚拟线程,栈按需增长
适用 流式与推送、需要背压、连接数极高 传统同步栈、希望保留可读性

判断顺序:先看是否需要背压与流式语义(需要则选响应式),再看能否接受编程模型改变(不能则选虚拟线程),最后才比较吞吐数据。

2.9 上下文传递

响应式链路中线程会切换,线程局部变量不可靠,因此上下文载体改为数据流上下文:

方式 做法 说明
流上下文 在装配阶段写入,在算子中读取 跟随数据流传播,与线程无关
自动传播 开启后由框架把已知上下文写入流上下文 需配合链路追踪与日志框架的适配
显式传递 把上下文作为参数在方法间传递 最稳定,适合少量关键字段

日志链路标识的处理需要在装配阶段完成:在入口把标识写入流上下文,并在写日志前从流上下文中取出,否则会出现同一请求的日志分散在不同标识下。

三、实现

3.1 依赖与基础配置

<!-- 响应式 Web:不要同时引入同步 Web 依赖,否则会以同步栈启动 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

<!-- 响应式数据访问(按需) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-r2dbc</artifactId>
</dependency>
server:
  port: 8080
spring:
  webflux:
    base-path: /
  r2dbc:
    pool:
      enabled: true
      max-size: 20          # 与同步连接池不同:并发上限由连接池容量决定
      initial-size: 5
# 确认启动的是响应式栈而不是同步栈(同时存在时同步栈优先)
java -jar application.jar --debug 2>&1 | grep -iE 'webflux|netty|tomcat' | head

要点:两个 Web 依赖同时存在时,框架按固定优先级选择同步栈,表现为"配置了响应式但没有生效",这是上手阶段最常见的误区。

3.2 阻塞调用的隔离

// 错误做法:在事件循环线程上执行阻塞调用
public Mono<Order> loadWrong(String id) {
    return Mono.fromCallable(() -> legacyRepository.findBlocking(id));   // 仍会占用事件循环
}

// 正确做法:把阻塞调用隔离到有界弹性调度器,并限制并发
private final Semaphore permits = new Semaphore(32);
private static final Scheduler BLOCKING = Schedulers.newBoundedElastic(16, 100_000, "blocking");

public Mono<Order> load(String id) {
    return Mono.fromCallable(() -> {
                permits.acquire();
                try {
                    return legacyRepository.findBlocking(id);
                } finally {
                    permits.release();
                }
            })
            .subscribeOn(BLOCKING);        // 订阅位置决定数据源在哪个线程执行
}

// CPU 密集型计算放到并行调度器
public Mono<BigDecimal> calculate(Flux<OrderItem> items) {
    return items.map(OrderItem::subtotal)
            .reduce(BigDecimal.ZERO, BigDecimal::add)
            .subscribeOn(Schedulers.parallel());
}
# 启用阻塞检测:在事件循环线程上出现阻塞调用时立即暴露
# 启动参数中加入代理,或在测试中显式安装检测工具
java -javaagent:blockhound.jar -jar application.jar

要点:隔离只是把阻塞搬到弹性线程池,若阻塞调用占比高,弹性线程上限会成为新的瓶颈;因此隔离用于过渡期,长期方向是替换为具备非阻塞实现的驱动。

3.3 背压与限流的配合

// 下游处理能力有限时,用并发数而不是无界缓冲控制压力
public Flux<OrderView> query(Flux<String> orderIds) {
    return orderIds
            .flatMap(this::loadOrder, 8)                 // 显式限制并发订阅数
            .onBackpressureBuffer(1_000,
                    dropped -> log.warn("背压缓冲溢出,丢弃 {}", dropped),
                    BufferOverflowStrategy.DROP_OLDEST)
            .timeout(Duration.ofSeconds(5))
            .onErrorResume(e -> Mono.empty());
}
// 全局限流的候选实现:以信号量控制进入下游的并发数
private final Semaphore downstreamPermits = new Semaphore(200);

public Mono<Response> callDownstream(Request request) {
    return Mono.defer(() -> {
                if (!downstreamPermits.tryAcquire()) {
                    return Mono.error(new ServiceBusyException("下游繁忙"));
                }
                return client.invoke(request)
                        .doFinally(signal -> downstreamPermits.release());
            });
}

要点:flatMap 的并发参数是控制下游压力的第一手段,其次才是缓冲区;缓冲区只是把压力的表现从"下游拒绝"改为"内存增长",需要与容量上限一起设置。

3.4 流式响应

@RestController
public class StreamController {

    // 服务端事件流:适合单向推送与进度反馈
    @GetMapping(value = "/tasks/{id}/progress", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<ServerSentEvent<String>> progress(@PathVariable String id) {
        return progressService.watch(id)
                .map(p -> ServerSentEvent.<String>builder()
                        .id(String.valueOf(p.version()))       // 供客户端断点续传
                        .event("progress")
                        .data(p.percent() + "%")
                        .build())
                .timeout(Duration.ofHours(1));
    }

    // 流式下载:避免把整个文件读入内存
    @GetMapping("/files/{id}")
    public Mono<ResponseEntity<Flux<DataBuffer>>> download(@PathVariable String id) {
        FileMeta meta = fileService.meta(id);
        Flux<DataBuffer> body = fileService.stream(id);         // 分块读取,逐块写出
        return Mono.just(ResponseEntity.ok()
                .header(HttpHeaders.CONTENT_TYPE, meta.contentType())
                .header(HttpHeaders.CONTENT_LENGTH, String.valueOf(meta.size()))
                .body(body));
    }
}

要点:流式响应需要中间层关闭缓冲,否则数据会被缓冲而失去流式效果,代理层的相应配置见 Nginx 反向代理与负载均衡实践;事件流应携带递增标识,供客户端在重连后补拉。

3.5 错误处理与重试

public Mono<Order> loadWithFallback(String id) {
    return orderClient.get(id)
            .timeout(Duration.ofSeconds(2))
            .retryWhen(Retry.backoff(3, Duration.ofMillis(200))
                    .filter(e -> e instanceof TimeoutException)      // 只对可重试错误重试
                    .jitter(0.5))                                    // 抖动避免重试同步
            .onErrorMap(TimeoutException.class, e -> new UpstreamTimeoutException(id))
            .onErrorResume(CacheMissException.class, e -> cacheFallback(id));
}

要点:重试条件必须限定为可重试错误,且只对幂等操作重试;重试次数与退避要与下游容量一起设计,否则重试本身会成为故障放大器。

3.6 上下文传递

// 在装配阶段写入上下文
public Mono<Response> handle(Request request) {
    return service.process(request)
            .contextWrite(Context.of("traceId", resolveTraceId(request)));
}

// 在算子中读取上下文,用于日志
public Mono<Result> process(Request request) {
    return Mono.deferContextual(ctx -> {
        String traceId = ctx.get("traceId");
        log.info("开始处理 traceId={}", traceId);
        return doProcess(request);
    });
}
// 开启自动传播,使日志与链路追踪框架能读取流上下文
// 在启动时启用;具体可用性取决于所用版本与集成组件
Hooks.enableAutomaticContextPropagation();

要点:ThreadLocal 在响应式链路中不可靠,因此统一改用流上下文;若必须使用依赖线程本地的组件,需要在调度器切换处显式捕获与恢复上下文。

3.7 验证与排查

# 1. 确认启动的是响应式栈
java -jar application.jar --debug 2>&1 | grep -iE 'webflux|netty' | head

# 2. 确认无阻塞调用(启用检测后,观察是否有阻塞报告)
grep -iE 'Blocking call|blockhound' /var/log/application/app.log | head

# 3. 观察事件循环线程是否被占满(响应式栈下线程名包含事件循环标识)
jcmd $(pgrep -f 'java.*application.jar') Thread.print | grep -oE '^"[^"]*"' | sort | uniq -c | sort -rn | head

# 4. 压测并观察内存是否随并发增长(背压失控的主要信号)
wrk -t4 -c2000 -d60s --latency http://localhost:8080/api/orders
jcmd $(pgrep -f 'java.*application.jar') GC.heap_info

# 5. 验证流式响应是否真的流式输出(应按时间逐条到达,而非一次性到达)
curl -N http://localhost:8080/tasks/1/progress

# 6. 需要算子级追踪时临开启检查点(开销大,仅用于定位)
#    在可疑链路上插入 checkpoint(),或开启算子调试钩子

3.8 常见问题对照

现象 常见原因 处置
配置了响应式但启动的是同步栈 两个 Web 依赖同时存在 排除同步 Web 依赖
方法返回数据流但日志无输出 未订阅,装配未触发执行 检查调用链末端是否有订阅或返回给框架
事件循环线程被阻塞告警 算子中存在阻塞调用 隔离到有界弹性调度器并逐步替换驱动
内存随并发持续增长 无界缓冲导致背压失控 设置并发参数与缓冲区上限,明确溢出策略
吞吐未提升且下游报错增多 瓶颈在下游,响应式放大了并发 用并发参数与限流控制压力
下游出现大量超时 重试策略过激 限定可重试错误并加退避与抖动
日志中的链路标识错乱 依赖线程局部变量传递上下文 改用流上下文并在装配阶段写入
流式接口一次性返回全部数据 中间层开启了响应缓冲 关闭代理与应用侧的缓冲
冷流被重复执行 同一数据流被多次订阅 明确订阅次数,必要时转为热流或缓存结果
调试时看不到完整调用栈 数据流装配与执行分离 使用算子级日志与检查点,定位到具体算子

四、总结

  1. 响应式与虚拟线程解决同一个问题(等待期间不占用昂贵资源),前者改变编程模型,后者改变运行时调度。
  2. 响应式的独立价值集中在背压、流式与推送语义,以及连接数极高且单请求内存敏感的场景;CPU 密集型任务不适用。
  3. 执行由订阅触发,未订阅则链路不执行;一个数据流被订阅多次会执行多次,冷流与热流的差别决定重复执行成本与丢帧行为。
  4. 背压是请求量协商,失控表现为内存增长、排队延迟上升与下游拒绝;缓冲区只是改变压力的表现方式,必须与容量上限一起设置。
  5. 订阅位置决定数据源的执行线程且只生效一次,发布位置影响其下游算子且可多次设置;阻塞调用必须放在有界弹性调度器上并限制并发。
  6. 响应式链路上出现阻塞调用的后果比同步模型更严重,会影响事件循环上的全部请求,因此上线前必须启用阻塞检测。
  7. 响应式的完整收益要求全链路非阻塞,链路上存在阻塞实现的环节越多收益越低,因此适用性判断应先做链路盘点。
  8. 与虚拟线程的取舍依据是是否需要背压与流式语义、是否接受编程模型改变,而不是吞吐数字的比较。
  9. 上下文载体从线程局部变量改为数据流上下文,日志链路标识需要在装配阶段写入,否则会出现标识错乱。
  10. 重试必须限定错误类型与幂等范围并加入退避抖动,否则重试会成为故障放大器;流式响应需要中间层关闭缓冲才能保持流式效果。