Go实现NATSJetStream持久化方法

本文深入解析了在 Go 中正确使用 NATS JetStream 实现消息持久化的关键实践与常见陷阱：必须先通过 `nats.Connect()` 建立连接，再显式调用 `jetstream.New(nc)` 初始化 JetStream 客户端并检查错误，而非直接 publish；服务端务必启用 `-js` 参数，否则所有操作将静默失败；持久化依赖显式创建 Stream，且需合理配置 `StorageType`（FileStorage 才真正落盘）、`DeliverPolicy`（避免新消费者收不到历史消息）、`Duplicates` 窗口与全局唯一 `MsgID` 以实现可靠去重；同时强调生产环境需补充凭证、重连策略等健壮性配置——忽略任一环节都可能导致 panic、消息丢失或幂等失效，尤其对金融、订单等强一致性场景至关重要。

必须先建 Stream，否则 Publish 就 panic；JetStream 不是连接后自动可用的“开关”，而是要显式初始化、显式配置存储策略的独立层。

JetStream 连接必须在 nats.Connect() 后立刻初始化

很多人写完 nats.Connect() 就直接调 js.Publish()，结果 runtime panic 报 "JetStream not enabled on server" 或 "nil pointer dereference"。这不是代码写错了，是漏掉了关键一步：JetStream 客户端对象必须主动创建并检查错误。

• 正确顺序是：nats.Connect() → jetstream.New(nc)（或 nc.JetStream()）→ 检查返回的 err
• 不能把初始化延迟到第一次 publish 时——那时错误堆栈已深，难定位
• 生产环境建议加凭证和重连控制：nats.UserCredentials("user.creds")、nats.MaxReconnects(60)、nats.ReconnectJitter(100*time.Millisecond, time.Second)

Stream 必须显式创建，且 StorageType 决定是否真持久化

裸连 NATS 发消息，消费者掉线 5 秒再上线，之前的消息就彻底丢了。这不是 bug，是设计如此——原生 NATS 是无状态 Pub/Sub。要持久化，必须调 js.CreateStream()，且重点看 Storage 字段：

• Storage: jetstream.FileStorage → 消息落盘，断电/重启不丢（默认值，但显式写出更安全）
• Storage: jetstream.MemoryStorage → 仅存内存，服务重启即清空，仅适合开发验证或临时指标
• 别只配 Subjects 和 Name，至少补上 RetentionPolicy 和 Duplicates，否则默认策略可能不符合业务预期

消费者收不到旧消息？大概率是 DeliverPolicy 设错了

流里明明有几百条历史消息，新起的消费者却只收到新发布的那几条——八成是没设 DeliverPolicy，或设成了 DeliverLastPolicy。

• DeliverAllPolicy：从流开头拉取，适合首次同步或补数据
• DeliverNewPolicy：只收后续新消息（默认行为），适合实时告警类场景
• DeliverByStartSequencePolicy 或 DeliverByStartTimePolicy：精准控制回溯点，调试和故障恢复必备
• 注意：Durable 名字必须一致，否则每次都是新消费者，无法延续上次 offset

消息去重靠 MsgID + Duplicates 窗口，不是开箱即用

金融、订单类业务要求幂等，但 JetStream 不会自动给每条消息算 ID。你得自己传 jetstream.WithMsgID("order-123-001")，且流配置里必须设 Duplicates: 2 * time.Minute，否则去重逻辑不生效。

• 重复窗口单位是秒级，太短容易漏判，太长占更多元数据空间
• MsgID 必须全局唯一且稳定（比如用业务单号+时间戳哈希），不能用随机 UUID
• 去重只发生在同一 Stream 内，跨 Stream 不共享重复记录

最易被忽略的一点：JetStream 的持久化能力完全依赖服务端配置。哪怕客户端全写对了，如果启动 nats-server 时没加 -js 参数，或者配置文件里 jetstream.enabled = false，那所有流操作都会静默失败或报错模糊——务必先确认服务端已启用 JetStream。

本篇关于《Go实现NATSJetStream持久化方法》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于Golang的相关知识，请关注golang学习网公众号！