Go JetStream PubAck 的 Duplicate 字段怎样判断服务器去重结果

Go JetStream 发布消息后拿到的 PubAck，最容易被误读的是 Duplicate 字段。它回答的是“服务器是否把这次发布识别成已有消息”，不是“消费者是否已经处理完成”。因此，Duplicate=true 通常应进入幂等成功或已存在分支；真正的网络、超时和服务端拒绝仍要看 err。

官方地址：https://pkg.go.dev/github.com/nats-io/nats.go/jetstream

判断顺序可以固定为：先判断 err，再读取 PubAck.Stream、PubAck.Sequence 和 PubAck.Duplicate。只有业务事件重试时复用了同一个消息标识，Duplicate 才能成为可靠的去重信号。

Duplicate 先看成发布幂等结果

JetStream 会把匹配 subject 的消息写入 stream，并为消息分配 stream sequence。Go 客户端的 PubAck 暴露了 stream、sequence 和 duplicate 三类信息。它处在生产者到 JetStream 的发布边界，和消费端收到消息后的 Ack 是两条不同链路。

这里的关键不是把重复当成异常，而是把它和“发布失败”分开。业务日志最好同时保存事件 ID、subject、stream、sequence 和 duplicate，后面排查重试时才知道是首次写入还是重复确认。

最小 Go 判断方式：同时读取 Sequence 和 Duplicate

jetstream.WithMsgID 用于设置消息去重标识。重试同一个业务事件时，标识必须保持稳定；如果每次都生成新 ID，客户端就无法要求服务端把它们视为同一发布。

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/nats-io/nats.go"
    "github.com/nats-io/nats.go/jetstream"
)

func main() {
    // 用超时上下文约束发布确认，避免请求无限等待。
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    nc, err := nats.Connect(nats.DefaultURL)
    if err != nil {
        log.Fatal(err)
    }
    defer nc.Close()

    js, err := jetstream.New(nc)
    if err != nil {
        log.Fatal(err)
    }

    // 重试同一个业务事件时复用 event-1001，服务端才能判断重复发布。
    ack, err := js.Publish(ctx, "orders.new", []byte("order-1001"),
        jetstream.WithMsgID("event-1001"))
    if err != nil {
        log.Fatalf("发布失败: %v", err)
    }

    // PubAck 是发布确认，不代表下游消费者已经 Ack。
    fmt.Printf("stream=%s sequence=%d duplicate=%t\n",
        ack.Stream, ack.Sequence, ack.Duplicate)
}

示例里最重要的判断点是：先处理 err，确认对象存在后再读字段。Sequence 可用于关联 stream 中的位置，Duplicate 则用于说明这次确认是否命中了服务端的消息标识去重。

把重复与错误放进不同分支

生产代码不应只打印 duplicate。发布失败时没有可靠的 PubAck，不能因为本地请求超时就直接断言“消息没有写入”；相反，拿到 Duplicate=true 时，也不应再次无条件发布。更稳妥的做法是把确认结果映射为三种状态：published、already-published 和 publish-error。

业务事件 ID 要和 Nats-Msg-Id 的值一一对应，但不要把 stream sequence 当成业务唯一键。sequence 是 stream 内的位置，可能随着不同 subject 和保留策略变化；业务去重仍由事件 ID 负责。

日志和重试的四个检查点

• 同一业务事件重试时复用同一个消息标识，不能只复用 payload。
• 先检查 err，再读取 Duplicate；超时是待确认状态，不是重复确认。
• 记录 Stream 与 Sequence 便于定位发布位置，但不要用 sequence 替代业务幂等键。
• 发布端的 PubAck 和消费端的 Ack 分开记录，避免把“已写入”误报成“已处理”。

常见问题

Duplicate=true 还需要重新发送吗？

通常不需要。它表示服务端已经按消息标识识别到重复发布，应用应把它作为幂等结果记录；只有后续业务动作失败时，才针对后续动作设计补偿。

为什么有了 Sequence 还要保存业务事件 ID？

Sequence 解决的是 stream 内定位，事件 ID 解决的是业务重试时的身份一致性。两者一起保存，才能同时回答“写到哪里”和“是不是同一件事”。

把 Duplicate 当成发布边界上的幂等信号，把 err 当成传输与服务端结果，把消费 Ack 留给消费者链路，Go JetStream 的重试日志就不会混成一个真假难辨的成功状态。