Go NATS Go 客户端 Drain 与 Close 有什么区别

服务要正常下线时，Go NATS 客户端通常应该优先考虑 Drain；只有不需要等待订阅和发布收尾，或者排水已经失败、必须立即释放资源时，才使用 Close。两者最终都会让连接进入关闭状态，但中间是否给消息处理留下收尾机会，完全不同。

官方文档：https://docs.nats.io/

故障现场：为什么服务退出时不能只看 Close

一次服务滚动发布中，进程收到停止信号后直接执行 nc.Close()。连接确实很快消失了，但正在回调里的响应还没有完成，等待中的 NextMsg 也被释放。问题不在于 Close “失效”，而在于它表达的是“现在就结束连接”，并不表达“让已经接收的工作先完成”。

官方 nats.go 对 Close 的定义很直接：关闭到服务器的连接，并释放包括 Flush 和 NextMsg 在内的阻塞调用。它适合硬关闭，但不适合把“剩余消息是否需要被处理完”交给库替你猜。

Drain 的语义则是先让连接进入排水状态，订阅立即进入排水状态；订阅完成后，发布端也会被排空，之后不能再发布新消息，最后连接关闭。官方 README 还特别把连接 Drain 标为 responder 的优先收尾方式，并说明调用 Drain 后不需要再调用 Close。

Drain 和 Close 的差异，关键在“是否给收尾留时间”

这里最容易写错的是把两者串成固定模板：nc.Drain(); nc.Close()。正常路径只需要 Drain；如果 Drain 返回错误，或者业务明确接受丢弃剩余工作的代价，再执行 Close 作为兜底。不要用“最后总要 Close”来掩盖自己没有定义退出策略。

把退出动作写成可解释的故障时间线

一个可维护的退出过程应该能回答三个问题：停止信号到来后，新的工作是否还会进入；已经进入回调的工作由谁完成；连接最终关闭时，进程如何知道结果。对应到 nats.go，可以把观察点放在 IsDraining、DrainTimeout 和 ClosedCB 上。

package main

import (
    "log"
    "time"

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

func connect() (*nats.Conn, error) {
    opts := nats.GetDefaultOptions()
    opts.Servers = []string{"nats://127.0.0.1:4222"}
    opts.DrainTimeout = 10 * time.Second // 给订阅和发布收尾设置明确上限。
    opts.ClosedCB = func(nc *nats.Conn) {
        // ClosedCB 表示连接不再保持打开，可在这里记录退出结果。
        log.Printf("nats connection closed: draining=%v", nc.IsDraining())
    }
    return opts.Connect()
}

这个配置不是把 Drain 变成带 context 的同步函数，而是给客户端的排水过程设置上限。ClosedCB 用来接收最终关闭通知；IsDraining 适合在状态记录或退出协调中识别当前连接是否处在排水阶段。

正常下线时，让 Drain 成为唯一的收尾动作

对于响应型订阅者，回调通常还要向请求方发布回复。此时连接收到停止信号后，直接 Close 会把“回复是否已经写入连接”变成一个竞态；Drain 则把订阅和发布端都纳入同一个结束语义。

import "log"

func shutdown(nc *nats.Conn) {
    // 正常下线优先 Drain；它完成后连接会自动关闭。
    if err := nc.Drain(); err != nil {
        // 排水失败时不再等待，直接释放连接作为硬关闭兜底。
        log.Printf("nats drain failed: %v", err)
        nc.Close()
    }
}

注意这个示例中的 Close 只在 Drain 报错时出现。若 Drain 成功，关闭动作由 Drain 的生命周期完成；如果把 Close 无条件放在成功路径后面，就很难从日志里分辨“优雅完成”还是“直接中断”。

三种场景怎么选

如果业务要求“任何消息都不能丢”，仅仅选择 Drain 还不够，还要给回调处理时间、控制发布方的退出顺序，并为超时后的重试或补偿定义策略。Drain 是客户端连接的收尾语义，不是业务消息可靠性的替代品。

常见问题

Drain 成功后还要再调用 Close 吗？

正常不需要。nats.go 的 Conn.Drain 文档说明，发布端排水完成后连接会关闭；官方 README 也提示 Drain 后不需要 Close。

Close 会不会等待当前回调执行完？

不要把 Close 当成等待回调完成的机制。它的文档重点是关闭连接并释放 Flush、NextMsg 等阻塞调用；需要优雅收尾时应使用 Drain。

DrainTimeout 应该设置多长？

按回调的正常处理时长、发布缓冲量和进程退出预算共同决定。默认值是 30 秒；如果服务只能在更短窗口内退出，就显式设置并准备好 Close 兜底。

IsDraining 能代替 ClosedCB 吗？

不能。IsDraining 反映排水状态，ClosedCB 用于接收连接最终关闭的通知；一个是过程状态，一个是结束信号。