本文详解 reactor 中 log()、doonnext、doonerror 等日志操作符的适用场景与最佳实践，帮助你在 spring webflux 项目中实现可调试、低侵入、生产友好的响应式流水线日志。
在基于 Project Reactor 的响应式 Java 应用（如 Spring WebFlux）中，缺乏可观测性是生产问题排查的最大障碍之一。由于响应式链天然异步、非阻塞且无显式调用栈，传统日志方式（如在 service 方法入口/出口打印）往往无法覆盖中间状态或错误上下文。幸运的是，Reactor 提供了多层级、语义明确的日志支持机制，关键在于按需选择合适的方式。
✅ 推荐首选：.log() —— 零侵入、全生命周期观测
log() 是最轻量、最安全的开箱即用日志方案。它自动记录订阅、请求、onNext/onError/onComplete 事件、取消信号及耗时统计（启用 DEBUG 级别时），不改变数据流结构，无副作用，适合开发与预发布环境快速诊断：
return repositoryName.findById(event.eventId())
.filter(event -> event.completedDate() == null)
.filterWhen(event -> externalService.getEventSummary(event.getUser().userId()))
.doOnNext(e -> log.info("Event found: {}", e.id()))
.log("EventProcessingPipeline") // ← 添加此行即可获得完整链路日志
.onErrorResume(e -> {
log.error("Failed to process event", e);
return Mono.empty();
});⚠️ 注意：生产环境慎用全局 log()（尤其 DEBUG 级别），因其会产生大量日志。建议通过 log(String category, LogLevel level) 控制粒度，例如 .log("biz.event", Level.INFO)。
✅ 场景化增强：doOn* 系列 —— 精确捕获关键节点
当需对特定事件做业务语义化记录（如“成功获取摘要”“跳过已完结事件”），doOnNext / doOnError / doOnFinally 更精准、可控：
- doOnNext: 在每个元素发射后执行（推荐用于成功路径日志）
- doOnError: 在异常传播前执行（适合记录错误上下文，但不拦截异常）
- doOnFinally: 无论成功/失败/取消均执行（类似 finally，适合资源清理或终态标记）
return repositoryName.findById(event.eventId())
.doOnNext(found -> log.debug("Event {} retrieved from DB", found.id()))
.filter(event -> event.completedDate() == null)
.doOnNext(filtered -> log.info("Event {} passed completion check", filtered.id()))
.filterWhen(event -> externalService.getEventSummary(event.getUser().userId()))
.doOnNext(summary -> log.info("Summary fetched for user: {}", summary.userId()))
.doOnError(ex -> log.warn("External service failed for event {}, retrying...", event.eventId(), ex))
.onErrorResume(ex -> fallbackToCachedSummary(event.eventId())); // ← 此处才真正处理异常✅ 关键原则：doOn* 仅用于副作用（如日志、指标埋点、简单状态更新），绝不用于修改数据流逻辑或抛出新异常——它们不改变下游数据，也不影响错误传播。
Java注释规范Skills下载当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
立即学习“Java免费学习笔记（深入）”；
❌ 避免误用：onErrorResume 不是日志工具
onErrorResume 的核心职责是错误恢复（返回替代数据流），而非日志。若仅需记录错误，请用 doOnError；若需记录 + 恢复，应组合使用：
// ✅ 正确：分离关注点
.doOnError(ex -> log.error("DB lookup failed for eventId: {}", event.eventId(), ex))
.onErrorResume(ex -> Mono.just(defaultEvent)) // 恢复逻辑独立清晰
// ❌ 错误：混用导致逻辑耦合、日志缺失
.onErrorResume(ex -> {
log.error("Handling error inline", ex); // 日志被包裹，难以统一管理
return Mono.just(defaultEvent);
});? 最佳实践总结
- 开发阶段：全局启用 .log("category") + DEBUG 日志级别，快速定位卡点；
- 测试/预发：保留关键 doOnNext/doOnError，聚焦业务里程碑事件；
-
生产环境：
- 关闭 log()，仅保留必要 doOn*（INFO/WARN 级别）；
- 结合 Micrometer 记录 Timer（耗时）、Counter（成功/失败次数）提升可观测性；
- 敏感字段（如用户ID、金额）务必脱敏后再日志输出；
- 统一规范：建立团队日志命名约定（如 "webflux.api.v1.order"），便于 ELK/Grafana 聚类分析。
通过分层选用 log() 与 doOn*，你既能获得深度调试能力，又可确保生产环境日志精简、语义清晰、性能无损——这才是响应式系统的日志之道。
