webflux-reactive-patterns

WebFlux 响应式模式

当整个请求路径都能从非阻塞 I/O 中受益时，使用 WebFlux。

依赖项和流水线规则

• 使用专用的 Boot 4 WebFlux 和 WebFlux 测试启动器。
• 返回 Mono 或 Flux；绝不要在请求处理代码中调用 subscribe()。
• 根据顺序要求选择 flatMap、concatMap 或顺序组合。
• 不要让 JDBC、文件系统和阻塞式 SDK 调用运行在 Reactor 事件循环上。
• 在适配器边界使用 boundedElastic 隔离不可避免的阻塞操作。
• 为外部调用设置超时，并保留取消能力。

上下文和错误

• 将请求范围的元数据放入 Reactor Context，而不是 ThreadLocal。
• 有意识地配置可观测性上下文传播。
• 在中心位置转换领域错误，同时不要吞掉取消信号。
• 仅在存在明确回退方案时使用 onErrorResume，并避免使用 onErrorContinue。

持久化和流式处理

• 使用 R2DBC 进行响应式数据库访问。
• 根据下游容量限制扇出并发数。
• 明确背压、缓冲和最大内存占用。
• 绝不要仅为简化下游代码而收集无界流。

测试

• 使用 StepVerifier 测试发布者行为，使用 WebTestClient 测试契约。
• 测试取消、超时、空结果、错误、顺序和背压。
• 在可行时，于测试中检测阻塞调用。

示例

• 参见 examples/good-reactive-service.java 和 examples/bad-reactive-service.java。

官方来源

• Spring WebFlux：https://docs.spring.io/spring-framework/reference/web/webflux.html
• Reactor 参考文档：https://projectreactor.io/docs/core/release/reference/
• Spring Data R2DBC：https://docs.spring.io/spring-data/relational/reference/r2dbc.html

注意事项

• Agent 意外添加 MVC 和 WebFlux 启动器——选择预期的 Web 技术栈。
• Agent 在应用程序流程中调用 block() 或 subscribe()——让运行时负责订阅。
• Agent 使用 ThreadLocal 保存租户或跟踪数据——改用 Reactor Context。
• Agent 使用无界 flatMap——根据下游限制设置并发数。
• Agent 使用 Mono.just 包装 JDBC——这仍会阻塞事件循环。