go-redis：Redis 官方 Go 客户端

Redis 官方为 Go 语言提供的客户端库 go-redis，目前在 GitHub 上获得超过 2.2 万个 Star。作为 Redis 官方维护的项目，它的稳定性和功能完整性在 Go 生态中处于领先位置。

go-redis 提供与 Redis 服务器交互的接口。它的目标是覆盖 Redis 的常用命令，并在连接管理、集群支持和可观测性方面提供完整能力。无论是本地开发还是生产环境部署，这个库都能满足大部分场景的需求。

版本支持

go-redis 支持最近三个 Redis 主版本，目前包括 Redis 8.0、8.2、8.4 和 8.8。从 Redis 8.8 开始，客户端新增数组数据类型支持，通过 AR 系列命令操作数组。该 API 仍处于实验阶段，后续版本可能调整。

go.mod 要求最低 Go 1.24，CI 会针对多个 Go 版本和 Redis 版本运行测试。这意味着开发者可以在较新的 Go 版本上获得稳定体验，同时也能跟踪 Redis 的新特性。

核心功能

go-redis 的功能覆盖比较全面：

• 支持除 QUIT 和 SYNC 外的大部分 Redis 命令
• 自动连接池管理
• 发布订阅
• 管道和事务
• Lua 脚本执行
• Redis Sentinel 和 Redis Cluster 支持
• 性能监控
• 可自定义读写缓冲区大小
• 概率数据结构

连接池机制可以减少重复创建连接的开销。管道和事务支持则让批量操作更高效。对于需要高可用的场景，Sentinel 和 Cluster 模式也提供了内置支持。

安装与快速开始

使用 Go modules 初始化项目后，通过 go get 安装 v9 版本。在 go.mod 中引入后，即可在代码中使用。

初始化客户端只需要指定地址和密码：

rdb := redis.NewClient(&redis.Options{
    Addr:     "localhost:6379",
    Password: "",
    DB:       0,
})

基本的 Set 和 Get 操作如下：

err := rdb.Set(ctx, "key", "value", 0).Err()
val, err := rdb.Get(ctx, "key").Result()

对于不存在的键，go-redis 会返回 redis.Nil 错误，方便业务层判断。这个设计让键缺失和真正的网络错误可以区分开来，减少误判。

认证方式

go-redis 提供四种认证方式，按优先级从高到低排列：

1. Streaming Credentials Provider：支持连接生命周期内动态更新凭证，适用于托管身份和令牌认证。
2. Context-based Credentials Provider：每次操作时通过 context 获取凭证。
3. Regular Credentials Provider：通过函数返回静态凭证。
4. Username/Password：在 Options 中直接配置用户名和密码。

这种分层设计让企业场景更灵活。例如在云环境中，可以通过令牌服务动态刷新凭证，而本地开发可以直接使用用户名和密码。

协议与可观测性

客户端支持 RESP2 和 RESP3 两种协议，可通过 Protocol 选项指定。同时支持通过 Redis URL 解析连接配置，便于从环境变量或配置中心读取地址。

OpenTelemetry 支持通过 extra/redisotel 包引入：

redisotel.InstrumentTracing(rdb)
redisotel.InstrumentMetrics(rdb)

接入后，可以收集调用延迟、错误率等指标，方便接入现有的监控体系。

缓冲区与错误处理

从 v9.12 起，go-redis 默认使用 32KiB 的读写缓冲区。对于高吞吐场景，可以通过 ReadBufferSize 和 WriteBufferSize 调整到更大值。如果默认缓冲区导致异常，也可以回退到 4096 字节。

go-redis 还内置了多种类型化错误判断函数，例如 IsLoadingError、IsAuthError、IsOOMError、IsMovedError 等，便于程序根据错误类型采取不同处理逻辑。在 Hook 中包装错误时，只要保留原始错误类型，这些判断依然可以生效。

总结

go-redis 是 Go 生态中使用广泛的 Redis 客户端之一。它覆盖单节点、哨兵、集群等多种部署形态，并提供连接池、认证、可观测性和类型化错误等能力。对于需要在 Go 项目中使用 Redis 的开发者，这是一个可靠的选择。其持续的官方维护和活跃的社区反馈，也保证了项目会跟随 Redis 和 Go 的发展不断更新。

错误等能力。对于需要在 Go 项目中使用 Redis 的开发者，这是一个可靠的选择。其持续的官方维护和活跃的社区反馈，也保证了项目会跟随 Redis 和 Go 的发展不断更新。