Watermill 仅是消息路由框架，需与 outbox 库组合实现事务一致性：outbox.Writer 同事务写库，Watermill Router 异步轮询 outbox 表并发布消息，不可裸调 Publisher 或手写 subscriber 循环。
Watermill 本身不是网关，也不是 Outbox 模式实现；它只是消息路由框架。真正承担事务一致性保障的是 outbox 库（如 github.com/ThreeDotsLabs/watermill-sql-outbox 或轻量级 github.com/google/uuid 配合自建表），而 Watermill 负责把“已落库”的消息发出去。想用它做事务性 Outbox 网关，必须组合两者，且不能跳过 Router。
为什么不能直接 new Publisher 后 Publish？
因为 kafka.NewPublisher 或 amqp.NewPublisher 是纯网络客户端，和数据库事务完全隔离。你先 tx.Commit() 再调 publisher.Publish()，中间若网络失败、进程崩溃，消息就丢了——数据库写成功了，但事件没发出去。
常见错误现象：order_created 事件在 DB 里有记录，下游服务却始终收不到；日志里查不到任何 Publish 错误，但消息就是不出现。
- 本地开发用
gochannel.NewPublisher会掩盖问题，上线后立刻暴露 - 哪怕加了重试，也无法解决“事务已提交但消息未发出”这个根本断层
-
Publisher的Close()和生命周期管理也容易被忽略，导致 goroutine 泄漏
必须用 outbox.Writer + Watermill Router 组合
核心是两段分离但强耦合的逻辑：写库阶段用 outbox.Writer 把消息和业务数据一起落库；发消息阶段由 Watermill 的 Router 启动独立 reader 协程轮询 outbox 表并调用 Publisher。
典型结构：
立即学习“go语言免费学习笔记（深入）”；
db → [outbox.Writer.Write(ctx, msg, insertEntityFn)] → outbox_events 表 ↑（同一 tx） ↓（异步） Watermill Router → outbox.Reader → kafka.NewPublisher
-
outbox.Writer必须传入支持事务的sql.Tx或封装好的txQueryer，确保INSERT INTO outbox_events和业务 INSERT 在同一个事务里 -
outbox.Reader要配好 polling interval、max batch size、error handler（比如把 failed 消息推到 dead letter topic） - Reader 发出的消息，必须经
message.NewRouter注册 handler 处理，不能裸调Publisher.Publish
Router.AddHandler 是唯一安全的消费入口
手写 for range subscriber.Subscribe() 看似简单，但会绕过所有 Watermill 的可靠性机制。一旦 handler panic，整个循环退出；没有中间件（Retry、Tracing、Timeout）；ConsumerGroup 配置失效；Ack 行为不可控。
正确姿势：
- 用
router.AddHandler("order_handler", "order_topic", subscriber, publisher, handlerFunc) -
handlerFunc签名必须是func(*message.Message) ([]*message.Message, error) - 返回
nil, nil表示成功消费且不发新消息；返回[]*message.Message, nil才触发下游 Publish - 若启用
ManualAck，必须显式调msg.Ack()，否则消息永远卡在 pending 状态
Router 启动后要 router.Run(context.Background())，并监听 router.Running() 确保它真正在跑——很多人忘了这步，程序静默退出。
Outbox 表结构和 Reader 配置容易踩坑
表字段必须包含 status（pending/published/failed）、created_at、published_at、retry_count，否则 outbox.Reader 无法判断是否该重试或跳过。
常见配置失误：
-
polling_interval设成 100ms → 高频空轮询拖垮 DB - 没设
max_retries→ 某条坏消息反复失败，阻塞后续所有消息 - 没配
dead_letter_topic→ failed 消息丢进黑洞，无监控无告警 - Reader 使用的 DB 连接没设
SetMaxOpenConns→ 连接池耗尽，整个服务夯住
最易被忽略的一点：Reader 和 Writer 必须共用同一套 SQL dialect（比如都用 outbox.SQLDialectPostgres），否则字段映射错乱，SELECT 出来的 payload 是空字节或乱码。
