本文详解 reactor 中 `log()`、`doonnext`、`doonerror` 等操作符的日志实践策略，对比适用场景，推荐生产环境安全、低侵入、可追溯的日志方案，并提供可直接复用的代码示例。
在基于 Spring WebFlux 和 Project Reactor 的响应式应用中，调试和可观测性高度依赖对数据流（Mono/Flux）生命周期的清晰日志记录。由于响应式链是异步、非阻塞且无显式调用栈的，盲目添加日志极易引发副作用或掩盖真实问题。因此，选择语义明确、无副作用、可精准定位阶段的日志方式至关重要。
✅ 推荐首选：.log() —— 零侵入、全生命周期洞察
log() 是 Reactor 内置的最轻量级日志工具，无需手动编写日志语句，自动输出订阅、请求、onNext、onError、onComplete 等关键事件及上下文（如线程名、操作符名称、元素值）。它默认使用 SLF4J 的 DEBUG 级别，且完全无副作用——不修改数据、不中断流、不引入阻塞。
return repositoryName.findById(event.eventId())
.filter(event -> event.completedDate() == null)
.filterWhen(event -> externalService.getEventSummary(event.getUser().userId()))
.doOnNext(e -> log.info("Event found and pending completion: {}", e.id()))
.log("EVENT_PROCESSING") // ← 建议添加分类标签，便于日志聚合检索
.onErrorResume(e -> {
log.warn("Failed to process event {}, falling back", event.eventId(), e);
return Mono.empty();
});✅ 优势：开箱即用、线程安全、支持 MDC 自动继承（配合 Loggers.withMdc 可增强追踪）、支持按 Category 过滤（如 -Dreactor.trace.log=true -Dreactor.trace.log.category=EVENT_PROCESSING） ⚠️ 注意：生产环境慎用全局 .log()（尤其未加 tag），建议仅在关键链路或调试期启用，并通过日志级别（如 DEBUG）控制输出。
✅ 按需补充：doOnNext / doOnError / doOnFinally —— 精准业务语义日志
当需在特定阶段执行带业务含义的记录（如“订单已创建”“库存扣减失败”），或需结合 MDC 设置上下文时，应选用副作用操作符：
- doOnNext: 元素成功发出后执行（推荐用于「处理成功」类日志）
- doOnError: 异常发生但尚未被 onErrorResume/onErrorContinue 处理前（适合「预警+诊断」）
- doOnFinally: 无论成功或失败，流终止前必执行（适合资源清理 + 统一耗时统计）
return repositoryName.findById(event.eventId())
.doOnSubscribe(s -> MDC.put("eventId", String.valueOf(event.eventId()))) // 埋点
.doOnNext(event -> {
log.info("✅ Event {} loaded, status: {}", event.id(), event.status());
Metrics.counter("event.loaded").increment(); // 同时上报指标
})
.doOnError(e -> {
log.error("❌ Failed to load event {}: {}", event.eventId(), e.getMessage(), e);
Sentry.captureException(e); // 集成错误监控
})
.doOnFinally(signalType -> MDC.clear()); // 清理 MDC 避免脏数据✅ 关键原则：所有 doOn* 操作符必须是纯函数式、无阻塞、无副作用（例如：不修改入参对象状态、不调用远程服务、不写数据库）。Reactor 保证它们不会影响主数据流。
立即学习“Java免费学习笔记（深入）”；
❌ 不推荐单独用于日志的方案
- onErrorResume: 主要用途是异常恢复（返回替代值或 fallback 流），日志只是附带行为；若仅需记录而不恢复，应优先用 doOnError。
- 在 map/flatMap 内部手动 log.info()：破坏函数式纯洁性，难以维护，且可能因异步调度导致 MDC 丢失或日志乱序。
- tap（旧版）或自定义 Subscriber：过度复杂，Reactor 已提供更简洁的语义化替代。
? 最佳实践总结
- 开发/测试阶段：全局启用 log("CATEGORY") 快速定位问题；
- 生产环境：仅在核心链路使用 doOnNext/doOnError 记录关键业务事件，配合结构化日志（JSON）与唯一 traceId；
- 统一可观测性：将日志 + Micrometer 指标 + 分布式追踪（如 Brave/Sleuth）结合，实现从「哪条流失败」到「哪个服务节点耗时高」的端到端分析；
- 性能兜底：避免在高频流中记录完整对象（用 toString() 或字段白名单），必要时增加 log.isDebugEnabled() 判断。
通过合理组合 log() 与语义化 doOn* 操作符，你既能获得响应式流的透明度，又不牺牲性能与可维护性——这才是真正面向生产的 Reactor 日志之道。
