redisKit

package
v2.8.112 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 19, 2023 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	NotSetupError = errorKit.New("haven’t been set up correctly")
)

Functions

func IsConsumerGroupNameAlreadyExistError added in v2.2.64 

func IsConsumerGroupNameAlreadyExistError(err error) bool

IsConsumerGroupNameAlreadyExistError

TODO: 涉及 github.com/redis/go-redis/v9 源码， 后续看有没有好的解决方法.

PS: 与 XGroupCreateMkStream 搭配使用.

func MustSetUp 

func MustSetUp(config *Config)

func SetUp 

func SetUp(config *Config) (err error)

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func GetClient 

func GetClient() (*Client, error)

GetClient

前提: 成功调用 SetUp() || MustSetUp().

func MustGetClient added in v2.2.58 

func MustGetClient() *Client

func NewClient 

func NewClient(config Config) (client *Client, err error)

NewClient 新建一个go-redis客户端（内置连接池，调用方无需额外考虑并发问题）

!!!: 每一个命令都会重新取得一个连接，执行后立即回收，而且回收到资源池的顺序类似于堆. https://www.cnblogs.com/yangqi7/p/13289232.html

连接哨兵集群的demo: https://blog.csdn.net/supery071/article/details/109491404

@return (1) 两个返回值，必定有一个为nil，另一个非nil； 

(2) Cluster模式下，第1个返回值的类型: *redis.ClusterClient.

func (*Client) Append 

func (client *Client) Append(ctx context.Context, key, value string) (int64, error)

Append

命令说明: Redis Append 命令用于为指定的 key 追加值。 (1) 如果 key 已经存在并且是一个字符串， APPEND 命令将 value 追加到 key 原来的值的末尾。 (2) 如果 key 不存在， APPEND 就简单地将给定 key 设为 value ，就像执行 SET key value 一样。

@return 追加后值的长度

func (*Client) Close 

func (client *Client) Close() error

func (*Client) DBSize 

func (client *Client) DBSize(ctx context.Context) (int64, error)

DBSize

命令说明: 返回当前数据库的 key 的数量. 命令语法: DBSIZE 命令返回值: 当前数据库的 key 的数量.

func (*Client) Decr 

func (client *Client) Decr(ctx context.Context, key string) (int64, error)

Decr

命令说明: Redis Decr 命令将 key 中储存的数字值减一。 (1) 如果 key 不存在，那么 key 的值会先被初始化为 0 ，然后再执行 DECR 操作。 (2) 如果值包含错误的类型，或字符串类型的值不能表示为数字，那么返回一个错误。 (3) 本操作的值限制在 64 位(bit)有符号数字表示之内（范围: [math.MinInt64, math.MaxInt64]，即[-9223372036854775808, 9223372036854775807]）。

func (*Client) DecrBy 

func (client *Client) DecrBy(ctx context.Context, key string, decrement int64) (int64, error)

DecrBy

命令说明: Redis Decrby 命令将 key 所储存的值减去指定的减量值。 (1) 如果 key 不存在，那么 key 的值会先被初始化为 0 ，然后再执行 DECRBY 操作。 (2) 如果值包含错误的类型，或字符串类型的值不能表示为数字，那么返回一个错误。 (3) 本操作的值限制在 64 位(bit)有符号数字表示之内（范围: [math.MinInt64, math.MaxInt64]，即[-9223372036854775808, 9223372036854775807]）。

e.g. key存在&&value为"-9223372036854775808"（将返回error） 

(context.Background(), "a") => 0 ERR increment or decrement would overflow

func (*Client) Del 

func (client *Client) Del(ctx context.Context, keys ...string) (int64, error)

Del

命令说明: 删除已存在的键。不存在的 key 会被忽略。 命令语法: DEL KEY_NAME 命令返回值: 被删除 key 的数量。

func (*Client) Eval 

func (client *Client) Eval(ctx context.Context, script string, keys []string, args ...interface{}) (interface{}, error)

Eval

!!!: cluster集群模式下，使用lua脚本要注意（特别是涉及多个Redis key的情况），更多详见".info".

命令说明: 使用 Lua 解释器执行脚本 命令语法: EVAL script numkeys key [key ...] arg [arg ...]

func (*Client) EvalSha 

func (client *Client) EvalSha(ctx context.Context, sha1 string, keys []string, args ...interface{}) (interface{}, error)

EvalSha

!!!: cluster集群模式下，使用lua脚本要注意（特别是涉及多个Redis key的情况），更多详见".info". PS: 一般与 ScriptLoad 搭配使用.

命令说明: 根据给定的 sha1 校验码，执行缓存在服务器中的脚本 命令语法: EVALSHA sha1 numkeys key [key ...] arg [arg ...]

func (*Client) Exists 

func (client *Client) Exists(ctx context.Context, keys ...string) (bool, error)

Exists

命令说明: 检查给定 key 是否存在. 命令语法: EXISTS KEY_NAME 命令返回值: 若 key 存在返回 1 ，否则返回 0.

func (*Client) Expire 

func (client *Client) Expire(ctx context.Context, key string, expiration time.Duration) (bool, error)

Expire

命令说明: 设置 key 的过期时间，key 过期后将不再可用。单位以秒计。 命令语法: Expire KEY_NAME TIME_IN_SECONDS 命令返回值: 设置成功返回 1 。 当 key 不存在或者不能为 key 设置过期时间时(比如在低于 2.1.3 版本的 Redis 中你尝试更新 key 的过期时间)返回 0 。

e.g. key不存在 => (false, nil) key存在 => (true, nil)

func (*Client) ExpireAt 

func (client *Client) ExpireAt(ctx context.Context, key string, tm time.Time) (bool, error)

ExpireAt

命令说明: 以 UNIX 时间戳(unix timestamp)格式设置 key 的过期时间。key 过期后将不再可用。 命令语法: Expireat KEY_NAME TIME_IN_UNIX_TIMESTAMP 命令返回值: 设置成功返回 1 。 当 key 不存在或者不能为 key 设置过期时间时(比如在低于 2.1.3 版本的 Redis 中你尝试更新 key 的过期时间)返回 0 。

func (*Client) FlushAll 

func (client *Client) FlushAll(ctx context.Context) (string, error)

FlushAll

命令说明: 清空整个 Redis 服务器的数据(删除所有数据库的所有 key ). 命令语法: FLUSHALL 命令返回值: 总是返回 OK .

func (*Client) FlushAllAsync 

func (client *Client) FlushAllAsync(ctx context.Context) (string, error)

FlushAllAsync 异步地.

func (*Client) FlushDB 

func (client *Client) FlushDB(ctx context.Context) (string, error)

FlushDB

命令说明: 清空当前数据库中的所有 key. 命令语法: FLUSHDB 命令返回值: 总是返回 OK .

func (*Client) FlushDBAsync 

func (client *Client) FlushDBAsync(ctx context.Context) (string, error)

FlushDBAsync 异步地.

func (*Client) GeoAdd 

func (client *Client) GeoAdd(ctx context.Context, key string, geoLocation ...*redis.GeoLocation) (int64, error)

GeoAdd

命令说明: 存储指定的地理空间位置，可以将一个或多个经度(longitude)、纬度(latitude)、位置名称(member)添加到指定的 key 中. 命令语法: GEOADD key longitude latitude member [longitude latitude member ...]

func (*Client) GeoDist 

func (client *Client) GeoDist(ctx context.Context, key string, member1, member2, unit string) (float64, error)

GeoDist

命令说明: 用于返回两个给定位置之间的距离. 命令语法: GEODIST key member1 member2 [m|km|ft|mi]

func (*Client) GeoPos 

func (client *Client) GeoPos(ctx context.Context, key string, members ...string) ([]*redis.GeoPos, error)

GeoPos

命令说明: 从给定的 key 里返回所有指定名称(member)的位置（经度和纬度），不存在的返回 nil。 命令语法: GEOPOS key member [member ...]

func (*Client) Get 

func (client *Client) Get(ctx context.Context, key string) (string, error)

Get

命令说明: 获取指定 key 的值。（如果 key 不存在，返回 nil；如果key 储存的值不是字符串类型，返回一个错误） 命令语法: GET KEY_NAME 命令返回值: 返回 key 的值，如果 key 不存在时，返回 nil。 如果 key 不是字符串类型，那么返回一个错误。

e.g. 当前db中不存在 传参key => ("", redis.Nil)

func (*Client) GetKeyWithPrefix added in v2.8.106 

func (client *Client) GetKeyWithPrefix(key string) string

func (*Client) GetMode 

func (client *Client) GetMode() Mode

func (*Client) GetPrefix added in v2.8.110 

func (client *Client) GetPrefix() string

func (*Client) GetUniversalClient 

func (client *Client) GetUniversalClient() redis.UniversalClient

GetUniversalClient 返回go-redis客户端

func (*Client) GetWithoutRedisNil 

func (client *Client) GetWithoutRedisNil(ctx context.Context, key string) (string, error)

GetWithoutRedisNil 对 Get 进行封装（特殊处理）: 当前db中不存在传参key时，返回 ("", nil).

PS： (1) 如果当前db中不存在传参key，将返回 ("", nil) (2) 如果不关心key是否存在，只关心值，可以调用此方法 (3) 如果对应value的类型不为string，会返回error: WRONGTYPE Operation against a key holding the wrong kind of value

func (*Client) HDel 

func (client *Client) HDel(ctx context.Context, key string, fields ...string) (int64, error)

HDel

命令说明: 删除哈希表 key 中的一个或多个指定字段，不存在的字段将被忽略。 命令语法: HDEL KEY_NAME FIELD1.. FIELDN 命令返回值: 被成功删除字段的数量，不包括被忽略的字段。

func (*Client) HExists 

func (client *Client) HExists(ctx context.Context, key, field string) (bool, error)

HExists

命令说明: 用于查看哈希表的指定字段是否存在 命令语法: HEXISTS KEY_NAME FIELD_NAME 命令返回值: 如果哈希表含有给定字段（field），返回 1 。 如果哈希表不含有给定字段，或 key 不存在，返回 0 。

PS: key和field，只要有一个不存在，返回值必定为(false, nil).

@param key 可以为"" @param field 可以为""

func (*Client) HGet 

func (client *Client) HGet(ctx context.Context, key, field string) (string, error)

HGet

命令说明: 返回哈希表中指定字段的值。 命令语法: HGET KEY_NAME FIELD_NAME 命令返回值: 返回给定字段的值。如果给定的字段或 key 不存在时，返回 nil 。

func (*Client) HGetAll 

func (client *Client) HGetAll(ctx context.Context, key string) (map[string]string, error)

HGetAll

命令说明: 

返回哈希表中，所有的字段和值。
在返回值里，紧跟每个字段名(field name)之后是字段的值(value)，所以返回值的长度是哈希表大小的两倍。

命令语法: HGETALL KEY_NAME 命令返回值: 以列表形式返回哈希表的字段及字段值。 若 key 不存在，返回空列表。

func (*Client) HKeys 

func (client *Client) HKeys(ctx context.Context, key string) ([]string, error)

func (*Client) HScan 

func (client *Client) HScan(ctx context.Context, key string, cursor uint64, match string, count int64) ([]string, uint64, error)

func (*Client) HSet 

func (client *Client) HSet(ctx context.Context, key string, values ...interface{}) (int64, error)

HSet 将哈希表 key 中的字段 field 的值设为 value

命令说明: 

为哈希表中的字段赋值 。
PS:
(1) 如果哈希表不存在，一个新的哈希表被创建并进行 HSET 操作。
(2) 如果字段已经存在于哈希表中，旧值将被覆盖。

命令语法: HSET KEY_NAME FIELD VALUE 命令返回值: 如果字段是哈希表中的一个新建字段，并且值设置成功，返回 1 。 如果哈希表中域字段已经存在且旧值已被新值覆盖，返回 0 。

PS: (1) 3个传参都可以为""（3个全是""也可以）； (2) 可以一次性设置多对 field 和 value.

@param key 如果db中不存在，会自动创建 @param values accepts values in following formats: 

("myhash", "key1", "value1", "key2", "value2")
("myhash", []string{"key1", "value1", "key2", "value2"})
("myhash", map[string]interface{}{"key1": "value1", "key2": "value2"})

func (*Client) HSetNX 

func (client *Client) HSetNX(ctx context.Context, key, field string, value interface{}) (bool, error)

HSetNX 只有在 字段field 不存在时，设置哈希表字段的值

命令说明: 

为哈希表中不存在的的字段赋值。
PS:
(1) 如果哈希表不存在，一个新的哈希表被创建并进行 HSET 操作。
(2) 如果字段已经存在于哈希表中，操作无效。
(3) 如果 key 不存在，一个新哈希表被创建并执行 HSETNX 命令。

命令语法: HSETNX KEY_NAME FIELD VALUE 命令返回值: 设置成功，返回 1 。 如果给定字段已经存在且没有操作被执行，返回 0 。

PS: (1) 如果field未存在，将返回: (true, nil). (2) 如果field已存在，将返回: (false, nil)，且 此次设置哈希表字段的值 将无效.

@param key 如果db中不存在，会自动创建

func (*Client) Incr 

func (client *Client) Incr(ctx context.Context, key string) (int64, error)

Incr

命令说明: Redis Incr 命令将 key 中储存的数字值增一。 (1) 如果 key 不存在，那么 key 的值会先被初始化为 0 ，然后再执行 INCR 操作。 (2) 如果值包含错误的类型，或字符串类型的值不能表示为数字，那么返回一个错误。 (3) 本操作的值限制在 64 位(bit)有符号数字表示之内（范围: [math.MinInt64, math.MaxInt64]，即[-9223372036854775808, 9223372036854775807]）。

@param key (1) 可以不存在 

(2) 可以为""

e.g. key不存在 

(context.Background(), "a") => 1 <nil>

e.g.1 key存在&&value为"1" 

(context.Background(), "a") => 2 <nil>

e.g.2 key存在&&value为"-1000" 

(context.Background(), "a") => -999 <nil>

e.g.3 key存在&&value为"9223372036854775807"（将返回error） 

(context.Background(), "a") => 0 ERR increment or decrement would overflow

e.g.4 key存在&&value为"3.1415926"（将返回error） 

(context.Background(), "a") => 0 ERR value is not an integer or out of range

e.g.5 key存在但类型为list（将返回error） 

(context.Background(), "a") => 0 WRONGTYPE Operation against a key holding the wrong kind of value

func (*Client) IncrBy 

func (client *Client) IncrBy(ctx context.Context, key string, value int64) (int64, error)

IncrBy

命令说明: Redis Incrby 命令将 key 中储存的数字加上指定的增量值。 (1) 如果 key 不存在，那么 key 的值会先被初始化为 0 ，然后再执行 INCRBY 命令。 (2) 如果值包含错误的类型，或字符串类型的值不能表示为数字，那么返回一个错误。 (3) 本操作的值限制在 64 位(bit)有符号数字表示之内（范围: [math.MinInt64, math.MaxInt64]，即[-9223372036854775808, 9223372036854775807]）。

func (*Client) IncrByFloat 

func (client *Client) IncrByFloat(ctx context.Context, key string, value float64) (float64, error)

IncrByFloat

命令说明: Redis Incrbyfloat 命令为 key 中所储存的值加上指定的浮点数增量值。 (1) 如果 key 不存在，那么 INCRBYFLOAT 会先将 key 的值设为 0 ，再执行加法操作。

func (*Client) Keys deprecated 

func (client *Client) Keys(ctx context.Context, pattern string) ([]string, error)

Keys

Deprecated: 当 KEYS命令 被用于处理一个大的数据库时，它可能会阻塞服务器达数秒之久。

e.g. db为空（或者不存在与 传参match 响应的key） => ([]string{}, nil)（第一个返回值不为nil）

func (*Client) LPop 

func (client *Client) LPop(ctx context.Context, key string) (string, error)

LPop 移除并返回列表的第一个元素

PS: 如果移除后列表为空。将删除该key.

@return key不存在的情况，将返回 ("", redis.Nil)

func (*Client) LPush 

func (client *Client) LPush(ctx context.Context, key string, values ...interface{}) (int64, error)

LPush 将一个或多个值插入到列表头部

语法: LPUSH key value1 [value2]

@param key 不存在的话，会自动创建此key

func (*Client) LPushX 

func (client *Client) LPushX(ctx context.Context, key string, values ...interface{}) (int64, error)

LPushX 将一个或多个值插入到列表头部

PS: (1) 如果 key 不存在，一个空列表会被创建并执行 LPUSH 操作； (2) 当 key 存在但不是列表类型时，返回一个错误。

@return key不存在的话，将返回 (0, nil)

func (*Client) MGet 

func (client *Client) MGet(ctx context.Context, keys ...string) ([]interface{}, error)

MGet

命令说明: 返回所有(一个或多个)给定 key 的值。 如果给定的 key 里面，有某个 key 不存在，那么这个 key 返回特殊值 nil 。 命令语法: MGET KEY1 KEY2 .. KEYN 命令返回值: 一个包含所有给定 key 的值的列表。

func (*Client) MSet 

func (client *Client) MSet(ctx context.Context, values ...interface{}) (bool, error)

MSet

命令说明: 同时设置一个或多个 key-value 对。 命令语法: MSET key1 value1 key2 value2 .. keyN valueN 命令返回值: 总是返回 OK 。

func (*Client) MSetNX 

func (client *Client) MSetNX(ctx context.Context, values ...interface{}) (bool, error)

MSetNX

命令说明: 所有给定 key 都不存在时，同时设置一个或多个 key-value 对。 命令语法: MSETNX key1 value1 key2 value2 .. keyN valueN 命令返回值: 当所有 key 都成功设置，返回 1 。 如果所有给定 key 都设置失败(至少有一个 key 已经存在)，那么返回 0 。

func (*Client) NewDistributedMutex 

func (client *Client) NewDistributedMutex(name string, options ...redsync.Option) *redsync.Mutex

NewDistributedMutex 生成Redis分布式互斥锁.

Go 每日一库之 redis官网推荐的go版本的分布式锁：redsync 

https://mp.weixin.qq.com/s/yXbEMTsZEgLWZuZgrFPXSg

图解redsync开源包，告诉你分布式锁为什么不仅仅是setnx 

https://mp.weixin.qq.com/s/hI4bKjNB_20dGC4kZZxKsQ

PS: (1) 不可重入锁; (2) 更多详见"Redis分布式锁（多语言）.docx"; (3) 写入Redis中键的默认TTL为: 8s. (4) Unlock: 

如果持有锁的时间 > Redis键的TTL，此时 "解锁" 将返回 false, error(类型: *redsync.ErrTaken; 错误内容: lock already taken, locked nodes: [0]);

(5) Lock: 

retry（获取锁失败后等一会，再尝试获取锁），相关配置: redsync.WithTries()、redsync.WithRetryDelay()、redsync.WithRetryDelayFunc()
retry整体周期内，如果获取锁失败，将返回error:
	(a) 类型: *redsync.ErrTaken; 错误内容: lock already taken, locked nodes: [0]
	(b) redsync.ErrFailed
e.g.
	PS: 尝试获取锁其实也要花一点时间.
	默认配置下，总计重试 32 次，第0次不等待，第1~31次在开始时等待随机时间（[50, 250)ms）.
	retry整体周期为 约4.8s（因为随机），还是获取不到则返回error.
e.g.1
	如果配置后，整体retry周期 > Redis中key的TTL，当上一个锁的key超时后，你就能获取到锁了（假如没有其他人也在抢锁）.

@param name 建议以 "mutex:" 为前缀

e.g. 将TTL修改为30s（原8s） NewDistributedMutex("name", redsync.WithExpiry(time.Second * 30))

func (*Client) NewUniqueId 

func (client *Client) NewUniqueId(ctx context.Context, key string) (string, error)

NewUniqueId 通过Redis生成唯一id.

PS: 返回值可以用作"分布式唯一id".

@param key (1) 可以不存在 

(2) 可以为""

func (*Client) PSubscribe 

func (client *Client) PSubscribe(ctx context.Context, patterns ...string) *redis.PubSub

PSubscribe 模式的订阅（对频道的模糊匹配，通过*）.

PS: 每个模式以 * 作为匹配符，e.g. 

it* 匹配所有以 it 开头的频道( it.news 、 it.blog 、 it.tweets 等等)；
news.* 匹配所有以 news. 开头的频道( news.it 、 news.global.today 等等)，诸如此类.

命令说明: 命令订阅一个或多个符合给定模式的频道. 命令语法: PSUBSCRIBE pattern [pattern ...] 命令返回值: 接收到的信息.

e.g. 监听 所有db 中key的超时 

!!!: 需要先配置好Redis并重启，详见"Redis.wps".
传参channels: "__keyevent@*__:expired"

func (*Client) Persist 

func (client *Client) Persist(ctx context.Context, key string) (bool, error)

Persist

命令说明: 移除给定 key 的过期时间，使得 key 永不过期。 命令语法: PERSIST KEY_NAME 命令返回值: 当过期时间移除成功时，返回 1 。 如果 key 不存在或 key 没有设置过期时间，返回 0 。

func (*Client) Ping 

func (client *Client) Ping(ctx context.Context) (string, error)

func (*Client) Pipeline 

func (client *Client) Pipeline() redis.Pipeliner

Pipeline 管道

TODO: cluster集群模式下，使用pipeline有问题.

redis.Pipeliner实例调用Exec函数执行时，第二个返回值为error类型： (1) 假如管道中每条命令都正常执行，将返回nil； (2) 假如管道中某些命令报错了，将返回第一个报错命令的error实例.

func (*Client) Publish 

func (client *Client) Publish(ctx context.Context, channel string, message interface{}) (int64, error)

Publish 发布.

参考: https://www.runoob.com/redis/pub-sub-publish.html

命令说明: 命令用于将信息发送到指定的频道. 命令语法: PUBLISH channel message 命令返回值: 接收到信息的订阅者数量.

func (*Client) RandomKey 

func (client *Client) RandomKey(ctx context.Context) (string, error)

RandomKey

命令说明: 从当前数据库中随机返回一个 key. 命令语法: RANDOMKEY 命令返回值: 当数据库不为空时，返回一个 key；当数据库为空时，返回 nil（windows 系统返回 null）.

func (*Client) Rename 

func (client *Client) Rename(ctx context.Context, key, newKey string) (string, error)

Rename

命令说明: 修改 key 的名称 。 命令语法: RENAME OLD_KEY_NAME NEW_KEY_NAME 命令返回值: 

改名成功时提示 OK ，失败时候返回一个错误。
当 OLD_KEY_NAME 和 NEW_KEY_NAME 相同，或者 OLD_KEY_NAME 不存在时，返回一个错误。 当 NEW_KEY_NAME 已经存在时， RENAME 命令将覆盖旧值。

func (*Client) RenameNX 

func (client *Client) RenameNX(ctx context.Context, key, newKey string) (bool, error)

RenameNX

命令说明: 在新的 key 不存在时修改 key 的名称 。 命令语法: RENAMENX OLD_KEY_NAME NEW_KEY_NAME 命令返回值: 修改成功时，返回 1 。 如果 NEW_KEY_NAME 已经存在，返回 0 。

func (*Client) SAdd 

func (client *Client) SAdd(ctx context.Context, key string, members ...interface{}) (int64, error)

SAdd 将一个或多个成员元素加入到集合中，已经存在于集合的成员元素将被忽略.

PS: (1) 假如集合 key 不存在，则创建一个只包含添加的元素作成员的集合； (2) 当集合 key 不是集合类型时，返回一个错误.

@return 第1个返回值: 成功添加的成员的数量（已经在集合中的不算）

func (*Client) SIsMember 

func (client *Client) SIsMember(ctx context.Context, key string, member interface{}) (bool, error)

SIsMember 判断 member元素 是否是 key对应集合 的成员？

func (*Client) SMembers deprecated 

func (client *Client) SMembers(ctx context.Context, key string) ([]string, error)

SMembers 返回集合中的所有的成员（不存在的集合 key 被视为空集合）.

Deprecated: 当 SMEMBERS命令 被用于处理一个大的数据库时，它可能会阻塞服务器达数秒之久。

e.g. key不存在的情况 => ([]string{}, nil)

func (*Client) SMembersMap deprecated 

func (client *Client) SMembersMap(ctx context.Context, key string) (map[string]struct{}, error)

SMembersMap

Deprecated: 当 SMEMBERS命令 被用于处理一个大的数据库时，它可能会阻塞服务器达数秒之久。

@return 第1个返回值: key为成员的值，value为空结构体（无意义）

e.g. key不存在的情况 => (map[string]struct{}{}, nil)

func (*Client) SPop 

func (client *Client) SPop(ctx context.Context, key string) (string, error)

SPop 用于移除并返回集合(set)中的一个随机元素.

func (*Client) SPopN 

func (client *Client) SPopN(ctx context.Context, key string, count int64) ([]string, error)

func (*Client) SRandMember 

func (client *Client) SRandMember(ctx context.Context, key string) (string, error)

SRandMember 返回集合中 1个 随机数.

func (*Client) SRandMemberN 

func (client *Client) SRandMemberN(ctx context.Context, key string, count int64) ([]string, error)

SRandMemberN 返回集合中 多个 随机数.

func (*Client) SRem 

func (client *Client) SRem(ctx context.Context, key string, members ...interface{}) (int64, error)

SRem 移除集合中的一个或多个成员元素，不存在的成员元素会被忽略.

PS: (1) 移除后，如果集合为空，将自动删除 传参key. (2) 当 key 不是集合类型，返回一个错误.

@return 第1个返回值: 被成功移除的元素的数量，不包括被忽略的元素（集合中本来就不存在该元素）

func (*Client) SSubscribe 

func (client *Client) SSubscribe(ctx context.Context, channels ...string) *redis.PubSub

SSubscribe

TODO: 目前还未在网上找到"SSUBSCRIBE"命令的相关说明,

func (*Client) Scan deprecated 

func (client *Client) Scan(ctx context.Context, cursor uint64, match string, count int64) ([]string, uint64, error)

Scan 迭代当前数据库中的数据库键.

Deprecated: 建议直接使用 ScanFully.

PS: (1) scan命令也并不是完美的，它"返回的结果有可能重复"，因此需要客户端"去重"； (2) 用于替代keys，因为keys在大数据量有性能问题； (3) 返回的[]string实例的长度可能会大于传参count，比如瞎传cursor的情况，编码时得注意.

@return 返回的error == nil的情况下，第1个返回值([]string)必定不为nil

e.g. db为空（|| db中不存在符合条件的key） (context.TODO(), 0, "*", 10) => ([]string{}, 0, nil)

func (*Client) ScanFully 

func (client *Client) ScanFully(ctx context.Context, match string, count int64) ([]string, error)

ScanFully 对 Scan 进行了封装，用于替代 Keys 命令.

增量迭代命令的缺点: 

因为在对键进行增量式迭代的过程中， 键可能会被修改， 所以增量式迭代命令只能对被返回的元素"提供有限的保证" （offer limited guarantees about the returned elements）。

PS: (1) 如果db为空，将返回: [] <nil> (2) redis cluster模式下，需要特殊处理（详见代码），否则：明明有数据的情况下，可能取不到数据，或者取到的数据不全（因为只找1个节点要）.

@return 返回的error == nil的情况下，第1个返回值([]string)必定不为nil

e.g. db为空（|| db中不存在符合条件的key） (context.TODO(), "*", 10) => ([]string{}, nil)

func (*Client) ScriptLoad 

func (client *Client) ScriptLoad(ctx context.Context, script string) (string, error)

ScriptLoad

命令说明: 将脚本 script 添加到脚本缓存中，但并不立即执行这个脚本 命令语法: SCRIPT LOAD script 命令返回值: 给定脚本的 SHA1 校验码

func (*Client) Set 

func (client *Client) Set(ctx context.Context, key string, value interface{}, expiration time.Duration) (bool, error)

Set 设置指定key的值（string类型）.

命令说明: 设置给定 key 的值。如果 key 已经存储其他值， SET 就覆写旧值，且无视类型。 命令语法: SET KEY_NAME VALUE 命令返回值: 

在 Redis 2.6.12 以前版本， SET 命令总是返回 OK 。
从 Redis 2.6.12 版本开始， SET 在设置操作成功完成时，才返回 OK 。

@param key 可以为"" @param value 支持的类型: string、[]byte、int、float64、bool(true: "1"; false: "0")... 

不支持的类型（会返回error）: map、自定义结构体...

@param expiration e.g. 120*time.Second 120s后过期 

 	 0 						持久化的键（即TTL为-1），无论：键是否存在、存在的键是否有超时时间
 	 -1(即redis.KeepTTL)	（需要确保Redis版本 >= 6.0，否则会返回error: ERR syntax error）
							(a) 键存在:		保持已经存在的TTL
							(b) 键不存在:	持久化的键

func (*Client) SetEx deprecated 

func (client *Client) SetEx(ctx context.Context, key string, value interface{}, expiration time.Duration) (bool, error)

SetEx

Deprecated: 个人感觉在 go-redis 中，使用 Set 就够了.

命令说明: 为指定的 key 设置值及其过期时间。。(如果 key 已经存在，SETEX 命令将会 替换旧的值 并 更新TTL) 命令语法: SETEX KEY_NAME TIMEOUT VALUE 命令返回值: 设置成功时返回 OK 。

func (*Client) SetNX 

func (client *Client) SetNX(ctx context.Context, key string, value interface{}, expiration time.Duration) (bool, error)

SetNX key不存在才会: 设置值 && 更新TTL

PS: 如果传参key已经存在，不会修改该key的TTL.

命令说明: 在指定的 key 不存在时，为 key 设置指定的值. 命令语法: SETNX KEY_NAME VALUE 命令返回值: 设置成功，返回 1 ；设置失败，返回 0 .

@return 第一个返回值代表: 是否设置成功

func (*Client) SetXX 

func (client *Client) SetXX(ctx context.Context, key string, value interface{}, expiration time.Duration) (bool, error)

SetXX （与 SetNX 相反）key存在才会: 设置值 && 更新TTL

Redis的数据类型详解 https://blog.csdn.net/m0_53474063/article/details/112647028

func (*Client) Subscribe 

func (client *Client) Subscribe(ctx context.Context, channels ...string) *redis.PubSub

Subscribe 频道的订阅（对频道的完全匹配）.

PS: (1) 建议 起一个goroutine 来进行订阅操作. (2) *redis.PubSub实例的2种使用方法: (a) PubSub.Channel()（推荐） 

(b) PubSub.ReceiveMessage()

(3) 取消订阅详见"_info.md".

命令说明: 订阅给定的一个或多个频道的信息. 命令语法: SUBSCRIBE channel [channel ...] 命令返回值: 接收到的信息.

e.g. 监听 db0 中key的超时 

!!!: 需要先配置好Redis并重启，详见"Redis.wps".
传参channels: "__keyevent@0__:expired"

func (*Client) TTL 

func (client *Client) TTL(ctx context.Context, key string) (time.Duration, error)

TTL

命令说明: 返回 key 的剩余过期时间. 命令语法： TTL KEY_NAME 命令返回值： (1) 当 key 不存在时，返回 -2 

(2) 当 key 存在但没有设置剩余生存时间时（持久化键），返回 -1
(3) 否则，以毫秒为单位，返回 key 的剩余生存时间

func (*Client) TxPipeline 

func (client *Client) TxPipeline() redis.Pipeliner

TxPipeline 事务管道

TODO: cluster集群模式下，使用pipeline有问题.

详见"Redis.docx".

func (*Client) Type 

func (client *Client) Type(ctx context.Context, key string) (string, error)

Type

命令说明: 返回 key 所储存的值的类型. 命令语法: TYPE KEY_NAME 命令返回值: 

none (key不存在)
string (字符串)
list (列表)
set (集合)
zset (有序集)
hash (哈希表)

e.g. 传参key不存在的情况 => ("none", nil)

func (*Client) XAck added in v2.2.61 

func (client *Client) XAck(ctx context.Context, stream, group string, ids ...string) (int64, error)

XAck [消费者] 将消息标记为"已处理".

PS: 并不会删除对应消息.

func (*Client) XAdd added in v2.2.58 

func (client *Client) XAdd(ctx context.Context, a *redis.XAddArgs) (id string, err error)

XAdd [生产者] 添加消息到末尾（如果指定的队列不存在，则创建一个队列）.

语法: XADD key ID field value [field value ...] key: 队列名称，如果不存在就创建 ID: 消息 id，我们使用 * 表示由 redis 生成，可以自定义，但是要自己保证递增性。 field value: 记录

@param a (1) 必需字段: Stream、Values 

(2) Stream字段对应: Redis中的key（stream类型）
(3) 可选的ID字段，为 ""（默认） 则由Redis生成

@return id: 消息的id

func (*Client) XDel added in v2.2.58 

func (client *Client) XDel(ctx context.Context, stream string, ids ...string) (int64, error)

XDel 删除Stream中的特定消息.

@return (1) 删除成功: 返回(1, nil) 

(2) 删除失败: 返回(0, nil)（e.g. stream 和 id 对应的消息不存在）

func (*Client) XGroupCreate added in v2.2.58 

func (client *Client) XGroupCreate(ctx context.Context, stream, consumerGroup, start string) error

XGroupCreate [消费者] 创建消费者组.

@Deprecated: Use XGroupCreateMkStream instead.

PS: (1) 如果 stream 对应的key: (a) 存在，do nothing; 

(b) 不存在，将返回error（ERR The XGROUP subcommand requires the key to exist. Note that for CREATE you may want to use the MKSTREAM option to create an empty stream automatically.）.

(2) 如果 group 已经存在，将返回error(BUSYGROUP Consumer Group name already exists).

func (*Client) XGroupCreateMkStream added in v2.2.62 

func (client *Client) XGroupCreateMkStream(ctx context.Context, stream, consumerGroup, start string) error

XGroupCreateMkStream [消费者] 创建消费者组.

PS: (1) 如果 stream 对应的key: (a) 存在，do nothing; 

(b) 不存在，将自动创建一个空的stream.

(2) 如果 group 已经存在，将返回error(BUSYGROUP Consumer Group name already exists).

func (*Client) XRead added in v2.2.58 

func (client *Client) XRead(ctx context.Context, a *redis.XReadArgs) ([]redis.XStream, error)

func (*Client) XReadGroup added in v2.2.58 

func (client *Client) XReadGroup(ctx context.Context, a *redis.XReadGroupArgs) ([]redis.XStream, error)

XReadGroup [消费者] 读取消费组中的消息.

XReadGroupArgs结构体: 

Group 		消费组名
Consumer	消费者名
Count		读取数量
Block		阻塞时间
Streams		要读取的所有Stream（!!!: (1) 数量应当>=2; (2) 最后一个元素应该是 ">"）

func (*Client) XReadStreams added in v2.2.58 

func (client *Client) XReadStreams(ctx context.Context, streams ...string) ([]redis.XStream, error)

func (*Client) ZAdd 

func (client *Client) ZAdd(ctx context.Context, key string, members ...redis.Z) (int64, error)

ZAdd

命令说明: 将一个或多个成员元素及其分数值加入到有序集当中。 

(1) 如果某个成员已经是有序集的成员，那么更新这个成员的分数值，并通过重新插入这个成员元素，来保证该成员在正确的位置上。
(2) 分数值可以是 整数值 或 双精度浮点数。
(3) 如果有序集合 key 不存在，则创建一个空的有序集并执行 ZADD 操作。
(4) 当 key 存在但不是有序集类型时，返回一个错误。

命令语法: ZADD KEY_NAME SCORE1 VALUE1.. SCOREN VALUEN 命令返回值: 被成功添加的新成员的数量，不包括那些被更新的、已经存在的成员。

func (*Client) ZCard 

func (client *Client) ZCard(ctx context.Context, key string) (int64, error)

ZCard

命令说明: 计算集合中元素的数量。 命令语法: ZCARD KEY_NAME 命令返回值: 当 key 存在且是有序集类型时，返回有序集的基数。 当 key 不存在时，返回 0。

func (*Client) ZCount 

func (client *Client) ZCount(ctx context.Context, key, min, max string) (int64, error)

ZCount

命令说明: 计算有序集合中指定分数区间的成员数量。 命令语法: ZCOUNT key min max 命令返回值: 分数值在 min 和 max 之间的成员的数量。

func (*Client) ZRangeByScore 

func (client *Client) ZRangeByScore(ctx context.Context, key string, opt *redis.ZRangeBy) ([]string, error)

ZRangeByScore

命令说明: 

返回有序集合中指定分数区间的成员列表。有序集成员按分数值递增(从小到大)次序排列。
具有相同分数值的成员按字典序来排列(该属性是有序集提供的，不需要额外的计算)。
默认情况下，区间的取值使用闭区间 (小于等于或大于等于)，你也可以通过给参数前增加 ( 符号来使用可选的开区间 (小于或大于)。

命令语法: ZRANGEBYSCORE key min max [WITHSCORES] [LIMIT offset count] 命令返回值: 指定区间内，带有分数值(可选)的有序集成员的列表。

func (*Client) ZRangeByScoreWithScores 

func (client *Client) ZRangeByScoreWithScores(ctx context.Context, key string, opt *redis.ZRangeBy) ([]redis.Z, error)

ZRangeByScoreWithScores

详见: ZRangeByScore，命令中有 WITHSCORES.

func (*Client) ZRem 

func (client *Client) ZRem(ctx context.Context, key string, members ...interface{}) (int64, error)

ZRem

命令说明: 移除有序集中的一个或多个成员，不存在的成员将被忽略。(当 key 存在但不是有序集类型时，返回一个错误。) 命令语法: ZREM key member [member ...] 命令返回值: 被成功移除的成员的数量，不包括被忽略的成员。

func (*Client) ZRevRangeByScore 

func (client *Client) ZRevRangeByScore(ctx context.Context, key string, opt *redis.ZRangeBy) ([]string, error)

ZRevRangeByScore

命令说明: 

返回有序集中指定分数区间内的所有的成员。有序集成员按分数值递减(从大到小)的次序排列。
具有相同分数值的成员按字典序的逆序(reverse lexicographical order )排列。
除了成员按分数值递减的次序排列这一点外， ZREVRANGEBYSCORE 命令的其他方面和 ZRANGEBYSCORE 命令一样。

命令语法: ZREVRANGEBYSCORE key max min [WITHSCORES] [LIMIT offset count] 命令返回值: 指定区间内，带有分数值(可选)的有序集成员的列表。

func (*Client) ZRevRangeByScoreWithScores 

func (client *Client) ZRevRangeByScoreWithScores(ctx context.Context, key string, opt *redis.ZRangeBy) ([]redis.Z, error)

ZRevRangeByScoreWithScores

详见: ZRevRangeByScore，命令中有 WITHSCORES.

type ClusterConfig 

type ClusterConfig struct {
	// Addrs
	/*
		A seed list of host:port addresses of cluster nodes.
		可以是: 所有的 master 的地址，
		也可以是: 所有的 master + slave 的地址（推荐）.
	*/
	Addrs []string `json:"addrs" yaml:"addrs" validate:"required,gte=2,dive,hostname_port"`
}

type Config 

type Config struct {
	UserName  string `json:"userName" yaml:"userName"`
	Password  string `json:"password" yaml:"password"`
	KeyPrefix string `json:"keyPrefix" yaml:"keyPrefix"`

	Mode        Mode               `json:"mode" yaml:"mode" validate:"oneof=single sentinel cluster"`
	Single      *SingleConfig      `json:"single" yaml:"singleNode"`
	MasterSlave *MasterSlaveConfig `json:"masterSlave" yaml:"masterSlaver"`
	Sentinel    *SentinelConfig    `json:"sentinel" yaml:"sentinel"`
	Cluster     *ClusterConfig     `json:"cluster" yaml:"cluster"`
}

func (Config) Equal 

func (config Config) Equal(config1 Config) bool

func (*Config) Validate added in v2.8.107 

func (config *Config) Validate() error

Validate

PS: (1) config可能为nil，此时将返回error; (2) 此方法体内不能调用 validateKit.Struct，以免发生递归死循环（但可以调用 validateKit.New）.

type MasterSlaveConfig added in v2.8.108 

type MasterSlaveConfig struct {
}

type Mode 

type Mode string

Mode Redis的集群模式 

const (
	// ModeSingle 单点
	ModeSingle Mode = "single"
	// ModeMasterSlave 主从集群
	ModeMasterSlave Mode = "masterSlave"
	// ModeSentinel 哨兵集群
	ModeSentinel Mode = "sentinel"
	// ModeCluster cluster集群
	ModeCluster Mode = "cluster"

	// DefaultMasterName 哨兵模式下，默认的MasterName
	DefaultMasterName = "mymaster"
)

type SentinelConfig 

type SentinelConfig struct {
	// MasterName The master name.
	MasterName string `json:"masterName" yaml:"masterName"`

	// Addrs A seed list of host:port addresses of sentinel nodes.
	Addrs []string `json:"addrs" yaml:"addrs" validate:"required,gte=2,dive,hostname_port"`

	DB int `json:"db" yaml:"db" validate:"gte=0"`
}

type SingleConfig added in v2.8.108 

type SingleConfig struct {
	// Addr address(host:port)
	Addr string `json:"addr" yaml:"addr" validate:"hostname_port"`

	// DB Database to be selected after connecting to the server.
	DB int `json:"db" yaml:"db" validate:"gte=0"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.