NATS Go客户端技术文档

本文档旨在帮助用户安装和使用NATS Go客户端，并提供API使用文档，以下为详细内容：

1. 安装指南

要获取最新版本的NATS Go客户端，可以使用以下命令：

go get github.com/nats-io/nats.go@latest

如果您需要获取特定版本，可以指定版本号：

go get github.com/nats-io/nats.go@v1.38.0

请注意，NATS服务器的最新主要版本为v2，如果您需要与此版本兼容，请使用以下命令：

go get github.com/nats-io/nats-server/v2@latest

2. 项目使用说明

以下为NATS Go客户端的基本使用方法：

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

// 连接到服务器
nc, _ := nats.Connect(nats.DefaultURL)

// 简单发布者
nc.Publish("foo", []byte("Hello World"))

// 简单异步订阅者
nc.Subscribe("foo", func(m *nats.Msg) {
    fmt.Printf("Received a message: %s\n", string(m.Data))
})

// 响应请求消息
nc.Subscribe("request", func(m *nats.Msg) {
    m.Respond([]byte("answer is 42"))
})

// 简单同步订阅者
sub, err := nc.SubscribeSync("foo")
m, err := sub.NextMsg(timeout)

// 通道订阅者
ch := make(chan *nats.Msg, 64)
sub, err := nc.ChanSubscribe("foo", ch)
msg := <- ch

// 取消订阅
sub.Unsubscribe()

// 排空
sub.Drain()

// 请求
msg, err := nc.Request("help", []byte("help me"), 10*time.Millisecond)

// 响应
nc.Subscribe("help", func(m *nats.Msg) {
    nc.Publish(m.Reply, []byte("I can help!"))
})

// 排空连接（响应者推荐使用）
nc.Drain()

// 关闭连接
nc.Close()

3. 项目API使用文档

NATS Go客户端提供了多种API以支持不同的使用场景，以下为一些常用的API：

JetStream

NATS的内置持久化系统，nats.go 提供了管理JetStream资产和发布/消费持久化消息的API。

// 连接到NATS服务器
nc, _ := nats.Connect(nats.DefaultURL)

// 创建JetStream上下文
js, _ := jetstream.New(nc)

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

// 获取现有流的句柄
stream, _ := js.Stream(ctx, "foo")

// 从流中检索消费者句柄
cons, _ := stream.Consumer(ctx, "cons")

// 在回调中从消费者中消费消息
cc, _ := cons.Consume(func(msg jetstream.Msg) {
    fmt.Println("Received jetstream message: ", string(msg.Data()))
    msg.Ack()
})
defer cc.Stop()

更多关于JetStream API的信息，请访问 jetstream/README.md。

Service API

Service API (micro) 允许您轻松构建NATS服务，目前此API处于测试阶段。

新的认证机制（Nkeys和用户凭证）

此功能需要服务器版本大于等于2.0.0。NATS服务器提供了一种新的安全认证机制，使用用户凭证和Nkeys进行认证。

nc, err := nats.Connect(url, nats.UserCredentials("user.creds"))

此助手方法会创建两个回调处理器来展示用户JWT和签署服务器挑战。核心客户端库不会直接访问您的私钥，只是执行签署服务器挑战的回调。

TLS

NATS客户端支持使用TLS进行安全连接。

// 使用TLS方案默认启用安全连接
nc, err := nats.Connect("tls://nats.demo.io:4443")

// 如果服务器使用自签名证书，需要设置RootCAs
nc, err = nats.Connect("tls://localhost:4443", nats.RootCAs("./configs/certs/ca.pem"))

// 如果服务器需要客户端证书，也有助手方法提供
cert := nats.ClientCert("./configs/certs/client-cert.pem", "./configs/certs/client-key.pem")
nc, err = nats.Connect("tls://localhost:4443", cert)

野卡订阅

使用 * 和 > 可以匹配不同的主题模式。

// "*" 匹配任何标记，任何级别的主题
nc.Subscribe("foo.*.baz", func(m *Msg) {
    fmt.Printf("Msg received on [%s] : %s\n", m.Subject, string(m.Data));
})

// ">" 匹配任何长度的主题尾部，且只能作为最后一个标记
nc.Subscribe("foo.>", func(m *Msg) {
    fmt.Printf("Msg received on [%s] : %s\n", m.Subject, string(m.Data));
})

队列组

使用相同的队列名称的所有订阅将形成一个队列组，每个消息只会发送到队列组中的一个订阅者。

nc.QueueSubscribe("foo", "job_workers", func(_ *Msg) {
  received += 1;
})

高级用法

NATS Go客户端提供了多种高级选项，例如重试连接、自定义重连策略等。

nc, err := nats.Connect(nats.DefaultURL,
    nats.RetryOnFailedConnect(true),
    nats.MaxReconnects(10),
    nats.ReconnectWait(time.Second),
    nats.ReconnectHandler(func(_ *nats.Conn) {
        // 首次异步连接时调用
    }))
if err != nil {
    // 连接失败时不会返回错误，但仍然需要检查以防止配置错误。
}

// 将连接刷新到服务器，等待所有消息处理完成
nc.Flush()
fmt.Println("All clear!")

// 指定超时时间的刷新
err := nc.FlushTimeout(1*time.Second)
if err != nil {
    fmt.Println("All clear!")
} else {
    fmt.Println("Flushed timed out!")
}

// 接收到MAX_WANTED条消息后自动取消订阅
const MAX_WANTED = 10
sub, err := nc.Subscribe("foo")
sub.AutoUnsubscribe(MAX_WANTED)

// 多个连接
nc1 := nats.Connect("nats://host1:4222")
nc2 := nats.Connect("nats://host2:4222")

nc1.Subscribe("foo", func(m *Msg) {
    fmt.Printf("Received a message: %s\n", string(m.Data))
})

nc2.Publish("foo", []byte("Hello World!"));

4. 项目安装方式

请参考以下命令安装NATS Go客户端：

go get github.com/nats-io/nats.go@latest

或者，您可以指定版本号进行安装：

go get github.com/nats-io/nats.go@v1.38.0

以上就是关于NATS Go客户端的详细技术文档，希望对您有所帮助。