Golang用NATS搭建轻量消息总线

本文深入剖析了使用Golang与NATS构建轻量级消息总线时，JetStream功能落地的关键陷阱与最佳实践：从服务端必须显式启用JetStream（-js参数或配置文件），到客户端需主动校验、定义持久化Stream、设置合理Ack策略与投递策略，再到事件契约设计（强制type/version字段、规范时间戳序列化）和幂等处理，直击本地调试正常而生产环境消息丢失、重复消费、静默解析失败等高频痛点——真正难的不是发送消息，而是确保每条消息在故障、升级与扩缩容后仍能被精准识别、可靠投递、安全去重与完整追溯。

用 nats.Connect 连不上？先确认 JetStream 是否启用

默认 nats-server 启动是纯内存模式，不带持久化能力——这意味着你调用 js.Publish 会直接 panic："jetstream not enabled"。这不是代码写错了，是服务端没开 JetStream。

• 启动时必须加 -js 参数：nats-server -js
• 或用配置文件显式启用：jetstream: { store_dir: "/data/jetstream" }
• 连接后建议立刻检查：js, err := nc.JetStream()，err 非空就说明 JetStream 没生效

很多团队卡在第一步，以为客户端库有问题，其实只是 nats-server 还在“裸奔”状态。

js.Publish 发出去就消失？默认不持久化

NATS 默认是“即发即忘”，没订阅者、没启用 JetStream、没创建 Stream，消息就真没了——连日志都捞不到。

• 必须先定义 Stream：js.AddStream(&nats.StreamConfig{Name: "ORDERS", Subjects: []string{"order.*"}})
• 发布时用完整 subject：js.Publish("order.created", data)，不能漏掉前缀匹配规则
• 消费者重启后想重播历史消息？订阅时得设 DeliverPolicy: nats.DeliverAll，否则只收新消息

常见错误：本地调试时一切正常，上生产一断网，订单事件全丢——因为压根没建 Stream，JetStream 根本没接管这条链路。

为什么 msg.Ack() 不调就重复消费？NATS 不替你记账

NATS JetStream 的 ACK 是手动的，不是 Kafka 那种自动 offset 提交。不调 msg.Ack()，消息就会在 AckWait 超时后重投——这是设计，不是 bug。

• 订阅时必须设 AckWait: 30 * time.Second，太短容易误重发，太长影响吞吐
• 业务逻辑出 panic 或 panic 恢复失败？msg.Ack() 就不会执行，下次必然重来
• 幂等不是可选项：用 order_id 做 Redis SETNX 键，或数据库唯一约束拦截重复

最容易被忽略的是：哪怕只做日志打印，也得包一层 defer msg.Ack()，否则只要 handler 函数提前 return，消息就进重试队列。

事件结构体里没 Type 和 Version 字段？等于裸奔

用 map[string]interface{} 或 json.RawMessage 接事件，短期内很爽；但加个字段、改个语义、升级一个服务，就可能全链路静默失败。

• 强制每个事件 struct 嵌入公共头：Type string `json:"type"` + Version string `json:"version"`
• 反例：{"event":"order_created","data":{"id":123}} —— 没 type，消费者无法路由；没 version，v2 消费者解析 v1 数据可能 panic
• 时间戳用 time.Time 字段 + json:"timestamp,string" 标签，别存字符串，避免时区/格式错乱

这事没法靠测试覆盖，只能靠约定和代码审查卡住。上线后出问题，往往不是功能缺陷，而是事件契约崩了。

事情说清了就结束。真正难的从来不是“怎么发消息”，而是怎么让每条消息在故障、升级、扩缩容之后，依然能被正确识别、去重、追溯。

今天关于《Golang用NATS搭建轻量消息总线》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！