附录 A:Reactor/RxJava 操作符速查
按 Reactor 3.8.8 与 RxJava 3.1.12 的实际 API 核对过的操作符速查表:涵盖创建、变换、组合、错误处理、背压控制与实用工具六大类,标注了两库并不对等的操作符(如 first、mergeOrdered、throttleFirst)和已废弃的重载,避免把「名字像」当成「语义相同」。
tag
按 Reactor 3.8.8 与 RxJava 3.1.12 的实际 API 核对过的操作符速查表:涵盖创建、变换、组合、错误处理、背压控制与实用工具六大类,标注了两库并不对等的操作符(如 first、mergeOrdered、throttleFirst)和已废弃的重载,避免把「名字像」当成「语义相同」。
按仓库真实状态做验收,而不是把计划全部打勾:编译通过(约 3 秒),但仓库里没有 TCK 测试类、没有 eventd-app 入口、没有 README,因此合规与可运行两项尚未达成。列出实际命令与真实失败输出,区分「章节中验证过的独立实验」和「仓库内可重复的测试」,并给出补齐验收所需的最小工作清单。
给出一套可复现的小型测量方法,而不是编造吞吐数字:1M 元素的 Flux.range、1M 次 Mono.just 订阅、1M 次 SyncSinglePublisher 订阅各跑 5 轮取中位数;另用 publishOn 测 10 万元素的调度延迟分位数。本机实测 Flux.range 约 6ms、Mono.just 单次订阅约 24ns、手写订阅约 6ns,p50 调度延迟 5μs、p99 11μs。同时说明为什么 onBackpressureBuffer 加在 Flux.range 上、totalMemory 差值和 delayElements 都不能当作有效的性能证据。
把第 2、3、13 章的手写实现逐个映射到 Reactor:SyncSinglePublisher 对应 Mono.just,AsyncRangePublisher 对应 Flux.range + subscribeOn,SensorSimulatorPublisher 对应 Flux.create + sink.onRequest。重点不是行数,而是语义差异:Mono.just(null) 直接抛 NPE,raw Subscription.request(0) 报 §3.9 错误而 BaseSubscriber.request(0) 被静默忽略,scheduleAtFixedRate 不等于有背压的传感器源。
用同一套指标对比 BUFFER、DROP、LATEST 三种策略:上游 10ms 一个元素,下游每次请求 1 个并处理 50ms。实测 BUFFER(10, DROP_LATEST) 丢弃 76 个、仍有 10 个留在缓冲区,DROP 丢弃 85 个,LATEST 通过 doOnDiscard 计数丢弃 84 个。重点说明 onBackpressureBuffer 两参数重载在溢出时会发 OverflowException,而不是静默丢弃。
实现一个真正响应 request 的 SensorSimulatorPublisher:指数分布间隔、饱和需求累加、wip 串行化、取消时中断工作线程、非正请求转 onError。给出 request(5)、request(0)、取消与慢消费者的实测输出,并说明为什么总耗时接近 max(到达时间, 处理时间) 而不是简单的「生产者等待」。最后给出使用 Flux.create + onRequest 的 Reactor 等价写法及其适用边界。
按仓库当前真实状态介绍 eventd v1:父 POM + eventd-core + eventd-app 三个模块,eventd-core 目前只有 SyncSinglePublisher 与 LoggingSubscriber 两个类。给出本机 mvn clean compile 的真实结果和 dependency:tree 原始输出,并解释一个容易踩的坑:这两个类实现的是 java.util.concurrent.Flow 接口,而 RS TCK 验证的是 org.reactivestreams 接口,两者形状相似但不能直接互传,需要适配。
用 Scannable 的实际输出说明装配阶段只是生成 Publisher 链:两个 map 是两个步骤,Reactor 不会把 lambda 合并。用 AtomicInteger 实测 Flux.just(load()) 在装配时立即执行、defer 在每次订阅时重新执行;并澄清 map 里的副作用不是装配时执行,log() 的两个位置都在订阅时打印、请求方向与数据方向相反。
用同一段代码的实测栈对比三种手段:默认 subscribe() 会把错误交给 onErrorDropped 并只打印操作符内部帧;Hooks.onOperatorDebug() 增加 Assembly trace 与 Error has been observed 站点;checkpoint() 只在标记处报告,且 3.8.8 只有三个重载,没有所谓「条件检查点」。同时给出 log() 的真实输出格式、MDC 跨线程失效的原因,以及为什么不能用一次计时估算调试开销。
用实测输出纠正几个常见误解:doOnTerminate 在下游收到 onComplete/onError 之前执行,doAfterTerminate 在下游处理完之后执行;doOnEach 只看到 onNext/onError/onComplete,看不到 onSubscribe 和 cancel;doOnRequest 报告的是请求量而不是实际产量。同时给出 doFinally 的 SIGNAL 类型、取消路径的顺序、钩子所在线程,以及为什么不能用一次 nanoTime 测量钩子开销。
分清 SubscriberWhiteboxVerification 与 SubscriberBlackboxVerification 的真实抽象方法:白盒通过 WhiteboxSubscriberProbe 注册 onSubscribe/onNext/onError/onComplete,并用 SubscriberPuppet 控制 request 与 cancel;黑盒的 triggerRequest 默认是空实现。给出可编译、14 个必测项全部通过的白盒骨架,用实测失败信息解释 spec205 要求取消的是「新收到的重复订阅」而不是旧订阅,并展示 IdentityProcessorVerification 的四个抽象方法与 PublishProcessor 的 14 项实败。
按真实方法名梳理 PublisherVerification 的必测项:createPublisher 精确元素数、spec101 请求与发射数量、spec102 可少发、spec103 串行信号、spec105 完成信号、spec107 终止后静默、spec109 订阅规则、spec302 同步 request、spec303 递归深度、spec306/307 取消后 no-op、spec309 非正请求、spec312/313 取消语义、spec317 长整型需求。实测 38 个用例中 29 通过、7 个 untested、2 个因无失败 Publisher 跳过,并给出两条真实失败信息与定位方法。
搭建 Reactive Streams TCK 1.0.4 测试环境:确认它依赖 TestNG 7.3.0、存在独立的 reactive-streams-tck-flow 构件与 FlowPublisherVerification 类,给出普通 Publisher 与 java.util.concurrent.Flow 两套最小依赖和验证基类的真实抽象方法。实测 TestEnvironment 默认超时为 100ms(可用 DEFAULT_TIMEOUT_MILLIS 覆盖),并用一次真实运行说明 38 个用例中 29 通过、9 跳过的构成。
给出 RxJava 3 到 Project Reactor 的逐项映射:Observable/Single/Maybe/Completable 与 Flux/Mono 的类型对应,doOnEach、throttleFirst、throttleLast、sample、debounce、onErrorReturn、retryWhen 的真实差异,以及调度器命名对照。重点列出六个迁移陷阱:Observable 无背压、Reactor 没有 onErrorReturn(Function)、Subject 需要 toSerialized、Sinks 返回 FAIL_NON_SERIALIZED、flatMap 默认并发 2147483647 对 256、trampoline 不等于 immediate。示例基于 RxJava 3.1.12 与 reactor-core 3.8.8。
对比 RxJava 的 ConnectableObservable 与 Reactor 的 ConnectableFlux:publish/connect 的延迟连接、refCount 在订阅归零时断开并在下次订阅时重新订阅源、autoConnect(n) 只在凑够 n 个订阅者时连接一次。实测 RxJava refCount 重连后 starts=2、interval 从 0 重新计时,autoConnect(2) 在只有一个订阅者时完全不启动;并纠正「Reactor 的 connect() 没有返回值」的错误说法。示例基于 RxJava 3.1.12 与 reactor-core 3.8.8。
对比 RxJava 3 的五种 Subject(PublishSubject、BehaviorSubject、ReplaySubject、AsyncSubject、UnicastSubject)与 Reactor Sinks 的语义映射。实测 late subscriber 在 PublishSubject 下丢失历史、BehaviorSubject 补最新值、AsyncSubject 只在完成时发射,并用并发探针证明裸 Subject 的 onNext 不会串行化(maxConcurrent=2),必须 toSerialized()(maxConcurrent=1)。示例基于 RxJava 3.1.12 与 reactor-core 3.8.8。
讲解 Sinks.Many.replay() 的五种策略:all() 无限历史、limit(n) 保留最近 n 个、limit(Duration) 按 TTL 淘汰、limit(n, Duration) 同时受限、latest() 只留最新值。实测 late subscriber 在 limit(3) 下只收到 [2,3,4]、只 request(1) 时只收到 1 个元素,证明重放仍受下游背压约束;并给出 latestOrDefault、过期后无新元素、完成后订阅的真实输出。示例基于 reactor-core 3.8.8。
用实跑对比 Sinks.Many 多播的三种背压策略:directBestEffort 只丢慢订阅者自己的元素,directAllOrNothing 只要一人无需求就让所有人收不到并返回 FAIL_OVERFLOW,onBackpressureBuffer 用共享队列导致队头阻塞,慢订阅者不补齐需求时快订阅者也拿不到元素。实测缓冲区容量取整(1→1、2/3/5→8、10→16)、默认 256,以及 busyLooping 只重试 FAIL_NON_SERIALIZED、不挽救 FAIL_OVERFLOW。示例基于 reactor-core 3.8.8。
讲解 Reactor Sinks API 的设计目标——在 Publisher 外部程序化地发射数据。对比 unicast、multicast、replay 三种 Many 工厂的订阅模型与零订阅者行为,实测 tryEmitNext 的 EmitResult 语义、emitNext 在 FAIL_OVERFLOW 时会终止整条 sink,以及并发发射实测出现的 FAIL_NON_SERIALIZED,纠正「Sinks 线程安全、可任意线程发射」的误解。示例基于 reactor-core 3.8.8。
对比 refCount(n)、autoConnect(n)、replay()、replay(n) 与 cache() 的启动时机、断开条件、后订阅者行为与内存代价。实测 refCount(1) 在订阅归零时取消源、在源完成后重新订阅源,autoConnect(1) 在订阅者全部取消后仍持续运行,replay(2) 只给后订阅者回放最近 2 个元素,cache(2) 只保留最近 2 个元素给后订阅者。示例基于 reactor-core 3.8.8。