# README
go-redis:Redis 客户端
go-redis
封装了 Redis 客户端,并且提供了各种 Redis 命令的 Go 接口。
使用方法
配置 Redis
如果使用 go-runner
启动服务,go-redis
会被自动创建,无需操心。所有配置放在配置文件的相关条目下。
注意,Redis 有多种启动模式,我们应该选用其中一种来填写配置:
[redis.client]
:代表普通直连模式,只在自测阶段应该设置,用于直连一台独立的 Redis 服务。[redis.cluster]
:使用 Redis cluster,线上会使用 cluster 模式管理 Redis 集群。
以 [redis.client]
为例,配置内容如下:
[redis.client]
addr = "127.0.0.1:6379"
业务代码需要使用 Redis 时,直接使用 New
方法即可。
import "github.com/altstory/go-redis"
func Foo(ctx context.Context, req *FooRequest) (res *FooResponse, err error) {
// 这里省略各种参数检查……
r := redis.New(ctx)
v, err := r.Get("foo")
if err != nil {
// Redis 出错啦,记得写日志并报错。
return
}
// 没取到 foo 的值,进行处理
if v.IsNull() {
// 处理……
} else {
// 拿到了 v 的值,通过 v.String() 得到里面的字符串内容。
}
// 其他代码省略……
}
在服务中使用多个 MySQL 连接
在某些场景下,仅使用一个 Redis 并不足够,那么我们可以自行构建 Factory
来连接更多的 Redis 服务。
首先在配置文件中写一个新的 Redis 连接配置。
[redis_another.client]
addr = "127.0.0.1:6380"
然后实例化一个新的工厂。
// anotherRedisFactory 的类型是 **Factory,是一个指针的指针。
var anotherRedisFactory = redis.Register("redis_another")
接着,使用这个全局变量 anotherRedisFactory
来创建新的 Redis client,在业务中使用。
factory := *anotherRedisFactory
r := factory.New(ctx)
// 使用 redis client 进行各种操作……
# Functions
AggregateMax 返回一个用于 sorted set 计算结果存储的选项 AGGREGATE MAX。 详见 https://redis.io/commands/zunionstore。.
AggregateMin 返回一个用于 sorted set 计算结果存储的选项 AGGREGATE MIN。 详见 https://redis.io/commands/zunionstore。.
AggregateSum 返回一个用于 sorted set 计算结果存储的选项 AGGREGATE SUM。 详见 https://redis.io/commands/zunionstore。.
Async 代表用异步模式进行 flush。.
Count 返回一个扫描选项,用于在各种 Scan 中实现 COUNT count。.
Expire 返回一个用于设置 key 超时的选项。 详见 https://redis.io/commands/set。.
Limit 返回一个用于 sorted set 范围查询的 limit。.
MakeBulkString 将 str 包装成 BulkString。.
MakeChanAndSub 可以方便的创建一个 ChanAndSub 实例。.
MakeKeyAndValue 可以方便的创建一个 KeyAndValue 实例。.
MakeMemberAndScore 可以方便的创建一个 MemberAndScore 实例。.
MakeMemberRange 将一个 member 变成 MemberRange。
默认返回的范围是包含 member 这个值的,如果希望生成一个不包含 member 的 MemberRange,应该调用 min := MakeScoreRange(1.234).Exclusive() // min == "(1.234".
MakeMultiValue 将 v 包装成一个 MultiValue。 如果 v 已经是一个 MultiValue 了,会返回 v 本身。.
MakeScoreRange 将一个 score 变成 ScoreRange。
默认返回的范围是包含 score 这个值的,如果希望生成一个不包含 value 的 ScoreRange,应该调用 min := MakeScoreRange(1.234).Exclusive() // min == "(1.234".
Match 返回一个扫描选项,用于在各种 Scan 中实现 MATCH pattern。.
New 通过默认的连接池创建一个 Redis 连接。.
NewFactory 创建一个新的 Redis 连接池。.
Null 返回一个 Null 值的 BulkString。.
NX 返回一个用于设置仅当 key 不存在才改变其值的选项。 详见 https://redis.io/commands/set。.
Register 将配置文件里 [section] 部分的配置用于初始化 Redis。 需要注意,Register 函数依赖于 runner 的启动流程, 在 AddClient 周期结束前,返回的 Factory 并不可用。.
Weights 返回一个用于 sorted set 计算结果存储的选项 WEIGHTS。 详见 https://redis.io/commands/zunionstore。.
XX 返回一个用于设置仅当 key 存在才改变其值的选项。 详见 https://redis.io/commands/set。.
# Constants
DefaultDialTimeout 代表默认的连接超时。.
DefaultReadTimeout 代表默认的读超时。.
DefaultWriteTimeout 代表默认的写超时。.
MemberRange 的边界值。.
MemberRange 的边界值。.
所有 Redis key 类型。.
所有 Redis key 类型。.
所有 Redis key 类型。.
所有 Redis key 类型。.
所有 Redis key 类型。.
所有 Redis key 类型。.
# Variables
ErrKeyHasNoExpiration 是当 key 没有设置超时时间、使用 TTL/PTTL 时返回的错误。.
ErrKeyNotExist 是当 key 找不到时返回的错误。.
ErrNotImplemented 表示这个功能还未实现。.
ErrUnexpectedResponseType 表示一个不支持的 redis 应答格式,一般都是这个库的 bug。.
ErrUnsupportedValueType 表示 redis 返回值的类型不支持,一般都是使用了还没实现的功能导致的。.
# Structs
BulkString 代表 Redis 协议中的 Bulk String 类型, 详见 https://redis.io/topics/protocol#bulk-string-reply。.
ChanAndSub 代表一对 channel 和 subscriber。.
ClientConfig 代表 Redis 直连模式的配置。 TODO: 补充更多配置项。.
ClusterConfig 代表 Redis cluster 配置。 TODO: 补充更多配置项。.
Config 代表一个 Redis 连接池工厂配置。
由于 Redis 有多种不兼容的连接池,这个类型由一系列子配置组成,如果同时设置了多个配置,生效的优先顺序如下: - ClientConfig - ClusterConfig - FailoverConfig - RingConfig TODO: - SentinelConfig TODO: - UniversalConfig TODO:.
Factory 管理 Redis 连接池,并提供接口从连接池中取出可用的 Redis 连接。.
FailoverConfig 代表 Redis failover client 配置。 TODO: 补充更多配置项。.
FutureMultiValue 表示一个还未获得结果的 MultiValue, 一般来说使用者不需要直接用这个结构,而是把它当做 error 来用, 使用 MakeMultiValue 来还原里面的值。
FutureMultiValue 实现了 error 接口, transaction 或 pipeline 中的所有 redis 接口调用都会返回一个 FutureMultiValue error, 使用者可以将这个 error 存起来,等 transaction 或 pipeline 提交之后 再用 MakeMultiValue 转化成真正的 MultiValue。
例如: var futureValue error _, err := client.Multi(r redis.Redis) error { r.Set("foo", "2") r.Incr("foo") _, futureValue = r.Get("foo") }) /* 检查 err,这里略过 */
// 使用 MakeMultiValue 获得真正的 MultiValue。 val := redis.MakeMultiValue(futureValue) v, ok := val.Value() fmt.Println(v, ok) // Output: 3 true.
KeyAndValue 代表一对 K/V 组合。.
MemberAndScore 代表 sorted set 的 member 和 score。.
MultiValue 存储所有合法的 Redis 值类型,包括 nil 和 error。 MULTI 和 EVAL 用它来存储返回值,调用者一般需要根据上下文来判断其中实际存储的类型是什么.
RangeOption 代表 sorted set 对计算结果进行范围查询时的选项。.
ScanOption 代表一个扫描选项。.
SetOption 代表设置一个 key 时候用到的各种选项。.
StoreOption 代表 sorted set 对计算结果进行存储时的选项。.
# Interfaces
Cluster 代表 Redis 跟集群相关的接口,详见 https://redis.io/commands#cluster。.
Connection 代表 Redis 跟连接相关的接口,详见 https://redis.io/commands#connection。
注意:由于 `SELECT` 和 `SWAPDB` 在 Redis Cluster 模式下已经没有用, 我们应该始终会使用 Redis Cluster 或者其他 Redis proxy 来实现高可用, 可以预计这两个接口应该永远不会用到,因此无需定义。
另外,`AUTH` 接口不做封装,密码验证的工作已经在框架层完成。.
Generic 代表 Redis 各种经典 K/V 接口,详见 https://redis.io/commands#generic。
注意,WAIT 不是用户使用的命令,这里不支持。.
GEO 代表 Redis 跟 GEO 相关的接口,详见 https://redis.io/commands#geo。.
Hashes 代表 Redis 跟 hash 相关的接口,详见 https://redis.io/commands#hash。.
HyperLogLog 代表 Redis 跟 HyperLogLog 相关的接口,详见 https://redis.io/commands#hyperloglog。.
Lists 代表 Redis 跟 list 相关的接口,详见 https://redis.io/commands#list。.
PubSub 代表 Redis 跟 pub/sub 相关的接口,详见 https://redis.io/commands#pubsub。.
Redis 代表一个 Redis 连接。.
Scan 代表所有跟扫描键值相关的接口,详见 https://redis.io/commands/scan。.
Scripting 代表 Redis 跟 scripting 相关的接口,详见 https://redis.io/commands#scripting。.
Server 代表 Redis 跟 server 相关的接口,详见 https://redis.io/commands#server。.
Sets 代表 Redis 跟 set 相关的接口,详见 https://redis.io/commands#set。.
SortedSets 代表 Redis 跟 zset 相关的接口,详见 https://redis.io/commands#sorted_set。.
Streams 代表 Redis 跟 stream 相关的接口,详见 https://redis.io/commands#stream。.
Strings 代表 Redis 跟字符串相关的接口,详见 https://redis.io/commands#string。.
Transactions 代表 Redis 跟事务相关的接口,详见 https://redis.io/commands#transactions。.
# Type aliases
ChanAndSubs 代表一系列 channel 和 subscriber 组合。.
FlushOption 代表 FLUSHDB 和 FLUSHALL 的选项。.
KeyAndValues 代表一系列 K/V 组合。.
KeyType 代表 Redis key 所对应的类型。.
MemberAndScores 代表一系列 sorted set 的 member 和 score 组合。.
MemberRange 表示一个 sorted set 里面 member 的范围。
允许的取值为: - 包含字符串:[member1 - 不包含字符串:(member2 - 边界:-、+.
ScoreRange 代表 sorted set 里面 score 的范围。
允许的取值为: - 数字:-1、2.3 - 范围:(1 - 无穷:-inf、+inf.