Watermill不是API网关，而是CQRS架构中command bus和event bus的消息骨架；应将其置于服务内部，由HTTP服务器（如gin）处理路由与鉴权，再交由Watermill驱动异步流程。
Watermill 本身不是网关，也不是 CQRS 的“网关层”——它不处理 HTTP 路由、JWT 鉴权或反向代理。把它当 API 网关用，会踩坑。
真正该做的，是把 Watermill 放在**服务内部**，作为 CQRS 中 command bus 和 event bus 的消息骨架；而 HTTP 层（即你所谓“网关”）仍由标准 net/http 或 gin/echo 承担，只负责接收请求、分发到对应 handler，再交由 Watermill 驱动后续异步流程。
为什么不能把 Watermill 当网关用？
Watermill 没有内置 HTTP server、路由匹配、中间件链、TLS 终止、限流熔断等网关能力。它的 Publisher 和 Subscriber 接口只面向消息中间件（Kafka/RabbitMQ/go-channel），不暴露 HTTP endpoint。
常见误操作：试图用 router.AddHandler 直接绑定 /api/orders —— 这行不通，Router 只处理已订阅的消息流，不是 HTTP mux。
真正要拼的架构是：HTTP server（网关职责） → Command handler（CQRS 写侧） → Watermill 发布事件 → Event handler（读侧更新） → 查询接口（独立读库/视图）
Command handler 怎么接入 Watermill Publisher？
别让 handler 直接调 publisher.Publish，否则事务不一致、消息易丢。必须用 OutboxPublisher 封装，并确保它和业务 DB 事务绑定。
立即学习“go语言免费学习笔记（深入）”；
- 初始化时传入 DB 实例和底层 publisher（如
kafka.NewPublisher），得到outbox.NewPublisher(db, publisher, logger) - 在事务内调用：
outboxPub.Publish(ctx, "order_created", msg)—— 这行必须在tx.Commit()之前执行 - handler 函数里不要自己开 goroutine 异步 publish；
OutboxPublisher内部已用轮询协程保障最终一致性 - 若用本地开发，
gochannel.NewPublisher可临时替代，但上线前必须切真实后端，否则无持久化
Event handler 如何避免重复消费或卡死？
Kafka 和 AMQP 的行为差异极大，同一套代码换中间件就出问题，主因是 Ack 和 timeout 配置没对齐。
- Kafka：必须显式设
ConsumerGroup，否则每次启动都从头消费；session.timeout.ms要大于 handler 最大执行时间，否则触发 rebalance 导致停摆 - AMQP（RabbitMQ）：默认
AckMode = amqp.ManualAck，但 handler 忘记调msg.Ack()就会无限重投——要么改用amqp.AutoAck，要么加 defermsg.Ack() - 所有 handler 必须返回
nil, nil表示成功消费且不转发；返回新*Message才触发下游发布 - 日志里反复出现
context deadline exceeded+ 同一条消息反复打印，基本就是 Ack 或 timeout 不匹配
Router 怎么复用而不写一堆 Subscribe 循环？
别为每个 topic 单独起 for range messages goroutine，用 Router 统一接管。
- 创建一个共享的
Subscriber（比如kafka.NewSubscriber），所有 handler 共用它 - 每个 handler 用
router.AddHandler注册，SubscribeTopic设为对应 topic，PublishTopic可空（只消费）或设为另一 topic（转发） - handler 函数签名固定为
func(msg *message.Message) ([]*message.Message, error)，返回非空 slice 才触发转发 -
Router内部用 channel 多路复用，比手动启 N 个 goroutine 更轻量、更可控，也更容易加统一中间件（如重试、日志）
Version 字段支持演进——这些细节漏掉，跑几天就出数据不一致。 
