跳转至

脚本开发 / 简易缓存 DFF.CACHE

DataFlux Func 内置了基于 Redis 的简易缓存功能 DFF.CACHE。 对于一些有数据缓存需求,同时需求并不复杂的场景,可以直接使用本内置缓存功能。

存储功能为 Scope-Key-Value 结构,不同命名空间下,允许存在相同的 Key。

简易缓存不会保持原始数据类型

在操作简易缓存时,无论在代码中写入的是字符串还是数字,重新读取后都是字符串。

用户需要自行处理读取到的内容,并进行合适的类型类型转换或反序列化处理。

通用类

一些和缓存数据库本身相关,以及与具体 Key 类型无关的方法

DFF.CACHE.ping()

于 6.0.6 版本新增

Ping 检测缓存数据库响应

示例
1
2
DFF.CACHE.ping()
# True

DFF.CACHE.info()

于 6.0.6 版本新增

获取缓存数据库信息

示例
1
DFF.CACHE.info()

DFF.CACHE.dbsize()

于 6.0.6 版本新增

获取缓存数据库 Key 数量

示例
1
2
DFF.CACHE.dbsize()
# 10

DFF.CACHE.type(...)

于 6.0.6 版本新增

获取 Key 类型,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
3
DFF.CACHE.set('my_key', 100, scope='my_scope')
DFF.CACHE.type('my_key', scope='my_scope')
# 'string'

DFF.CACHE.keys(...)

于 6.0.6 版本新增

获取 Key 列表,参数如下:

参数 类型 必须 / 默认值 说明
pattern str "*" 键名匹配模式
支持 * 通配符
scope str 当前脚本名 命名空间
示例
1
2
DFF.CACHE.keys('*', scope='my_scope')
# ['my_key']

DFF.CACHE.exists(...)

于 6.0.6 版本新增

检查 Key 是否存在,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
DFF.CACHE.exists('my_key', scope='my_scope')
# True

DFF.CACHE.expire(...)

设置缓存的过期时长,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
expire int None 过期时长。
单位:秒
None 表示永不过期
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.expire('my_key', 3600, scope='my_scope')

DFF.CACHE.expireat(...)

于 6.0.6 版本新增

设置缓存的过期时间点,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
timestamp int 必须 UNIX 时间戳(单位:秒)
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.expireat('my_key', int(time.time() + 3600), scope='my_scope')

DFF.CACHE.ttl(...)

于 6.0.6 版本新增

获取键剩余过期时间(秒),参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
DFF.CACHE.ttl('my_key', scope='my_scope')
# 3599

DFF.CACHE.delete(...)

删除存储的数据,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.delete('my_key', scope='my_scope')

DFF.CACHE.delete_pattern(...)

根据键名匹配模式删除存储的数据,参数如下:

参数 类型 必须 / 默认值 说明
pattern str "*" 键名匹配模式
支持 * 通配符
scope str 当前脚本名 命名空间
示例
1
2
3
4
DFF.CACHE.set('my_key', 100, scope='my_scope')
DFF.CACHE.set('my_key2', 200, scope='my_scope')

DFF.CACHE.delete_pattern('my*', scope='my_scope')

字符串类(String)

有关通过 DFF.CACHE.set(...) 方法写入的值的操作方法

DFF.CACHE.set(...)

建立缓存,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
value str / int / float 必须 数据
expires / expire int None 过期时间。
单位:秒
None 表示永不过期
not_exists bool False 是否仅在键不存在时写入
exists bool False 是否仅在键存在时写入
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.set('my_key', 100, scope='my_scope')

DFF.CACHE.mset(...)

于 6.0.6 版本新增

批量建立缓存,参数如下:

参数 类型 必须 / 默认值 说明
key_values dict 必须 键名-数据字典
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
data = {
  'my_key' : 100,
  'my_key2': 200,
}
DFF.CACHE.mset(data, scope='my_scope')

DFF.CACHE.get(...)

获取缓存,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
3
4
DFF.CACHE.set('my_key', 100, scope='my_scope')

DFF.CACHE.get('my_key', scope='my_scope')
# '100'

DFF.CACHE.mget(...)

于 6.0.6 版本新增

批量获取缓存,参数如下:

参数 类型 必须 / 默认值 说明
keys str 必须 键名列表
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
DFF.CACHE.set('my_key', 100, scope='my_scope')
DFF.CACHE.set('my_key2', 200, scope='my_scope')

DFF.CACHE.mget([ 'my_key', 'my_key2' ], scope='my_scope')
# {'my_key': '100', 'my_key2': '200'}

DFF.CACHE.get_pattern(...)

于 6.0.6 版本新增

根据键名匹配模式获取缓存,参数如下:

参数 类型 必须 / 默认值 说明
pattern str "*" 键名匹配模式
支持 * 通配符
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
DFF.CACHE.set('my_key', 100, scope='my_scope')
DFF.CACHE.set('my_key2', 200, scope='my_scope')

DFF.CACHE.get_pattern('my_*', scope='my_scope')
# {'my_key2': '200', 'my_key': '100'}

DFF.CACHE.getset(...)

获取缓存,同时设置新的缓存值,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
value str / int / float 必须 数据
scope str 当前脚本名 命名空间
示例
1
2
3
4
DFF.CACHE.set('my_key', 100, scope='my_scope')

DFF.CACHE.getset('my_key', 200, scope='my_scope')
# '100'

DFF.CACHE.incr(...)

对缓存值增加步进,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
step int 1 步进值
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.incr('my_key', scope='my_scope')

DFF.CACHE.incrby(...)

对缓存值增加指定步进,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
step int 必须 步进值
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.incrby('my_key', step=2, scope='my_scope')

哈希类(Hash)

使用哈希结构可以将同类型的缓存存入相同的 Key 下,减少缓存主空间的 Key 数量

DFF.CACHE.hkeys(...)

获取哈希结构字段列表,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
pattern str "*" 字段名匹配模式
支持 * 通配符
scope str 当前脚本名 命名空间
示例
1
2
3
4
DFF.CACHE.hmset('user:001', { 'name': 'Tom', 'city': 'Beijing' }, scope='my_scope')

DFF.CACHE.hkeys('user:001', scope='userCache')
# ['name', 'city']

DFF.CACHE.hset(...)

设置哈希结构中的某个字段值,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
field str 必须 字段名
value str / int / float 必须 数据
not_exists bool False 是否仅在字段不存在时写入
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.hset('user:001', 'name', 'Tom', scope='my_scope')

DFF.CACHE.hmset(...)

设置哈希结构中的多个字段值,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
obj dict 必须 数据
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.hmset('user:001', { 'name': 'Tom', 'city': 'Beijing' }, scope='my_scope')

DFF.CACHE.hget(...)

获取哈希结构中的字段值,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
field str 必须 字段名
scope str 当前脚本名 命名空间
示例
1
2
3
4
DFF.CACHE.hmset('user:001', { 'name': 'Tom', 'city': 'Beijing', 'age': 20 }, scope='my_scope')

DFF.CACHE.hget('user:001', 'name', scope='my_scope')
# 'Tom'

DFF.CACHE.hmget(...)

于 6.0.6 版本新增

获取哈希结构中的多个字段值,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
fields list 必须 字段名列表
scope str 当前脚本名 命名空间
示例
1
2
3
4
DFF.CACHE.hmset('user:001', { 'name': 'Tom', 'city': 'Beijing', 'age': 20 }, scope='my_scope')

DFF.CACHE.hmget('user:001', ['name', 'city'], scope='my_scope')
# {'name': 'Tom', 'city': 'Beijing'}

DFF.CACHE.hgetall(...)

于 6.0.6 版本新增

获取哈希结构中的全部字段值,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
3
4
DFF.CACHE.hmset('user:001', { 'name': 'Tom', 'city': 'Beijing', 'age': 20 }, scope='my_scope')

DFF.CACHE.hgetall('user:001', scope='my_scope')
# {'age': '20', 'city': 'Beijing', 'name': 'Tom'}

DFF.CACHE.hincr(...)

于 6.0.6 版本新增

对哈希结构中的字段增加步进,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
field str 必须 字段名
step int 1 步进值
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.hincr('user:001', 'signCount', scope='my_scope')

DFF.CACHE.hincrby(...)

于 6.0.6 版本新增

对哈希结构中的字段增加步进,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
field str 必须 字段名
step int 必须 步进值
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.hincrby('user:001', 'signCount', step=2, scope='my_scope')

DFF.CACHE.hdel(...)

删除哈希结构中的某个字段,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
field str 必须 字段名
scope str 当前脚本名 命名空间
示例
1
2
3
DFF.CACHE.hmset('user:001', { 'name': 'Tom', 'city': 'Beijing' }, scope='my_scope')

DFF.CACHE.hdel('user:001', 'city', scope='my_scope')

列表类(List)

使用列表结构可以将多个缓存按顺序存入相同的 Key 下,常用于实现队列、栈等处理

DFF.CACHE.lpush(...)

左侧向列表结构添加元素,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
value str / int / float 必须 数据
scope str 当前脚本名 命名空间
示例
1
2
DFF.CACHE.lpush('userQueue', '001', scope='queue')
DFF.CACHE.lpush('userQueue', '002', scope='queue')

DFF.CACHE.rpush(...)

右侧向列表结构添加元素,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
value str / int / float 必须 数据
scope str 当前脚本名 命名空间
示例
1
2
DFF.CACHE.rpush('userQueue', '001', scope='queue')
DFF.CACHE.rpush('userQueue', '002', scope='queue')

DFF.CACHE.lpop(...)

左侧从列表结构中弹出元素,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
DFF.CACHE.lpush('userQueue', '001', scope='queue')
DFF.CACHE.lpush('userQueue', '002', scope='queue')

DFF.CACHE.lpop('userQueue', scope='queue')
# '002'

DFF.CACHE.rpop(...)

右侧从列表结构中弹出元素,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
DFF.CACHE.lpush('userQueue', '001', scope='queue')
DFF.CACHE.lpush('userQueue', '002', scope='queue')

DFF.CACHE.rpop('userQueue', scope='queue')
# '001'

DFF.CACHE.blpop(...)

于 6.0.6 版本新增

以阻塞方式,从左侧从列表结构中弹出元素,参数如下:

参数 类型 必须 / 默认值 说明
key str / list 必须 键名 / 键名列表
timeout int 0 阻塞超时时长(秒)
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
DFF.CACHE.lpush('userQueue', '001', scope='queue')
DFF.CACHE.lpush('userQueue', '002', scope='queue')

DFF.CACHE.blpop('userQueue', timeout=3, scope='queue')
# ['userQueue', '002']

DFF.CACHE.brpop(...)

于 6.0.6 版本新增

以阻塞方式,从右侧从列表结构中弹出元素,参数如下:

参数 类型 必须 / 默认值 说明
key str / list 必须 键名 / 键名列表
timeout int 0 阻塞超时时长(秒)
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
DFF.CACHE.lpush('userQueue', '001', scope='queue')
DFF.CACHE.lpush('userQueue', '002', scope='queue')

DFF.CACHE.brpop('userQueue', timeout=3, scope='queue')
# ['userQueue', '001']

DFF.CACHE.rpoplpush(...)

从一个列表结构右侧弹出元素,同时向另一个列表结构左侧推入元素,并返回此元素,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名(来源)
dest_key str key 相同 键名(目标)
scope str 当前脚本名 命名空间(来源)
dest_scope str scope 相同 命名空间(目标)
示例
1
2
3
4
5
6
DFF.CACHE.lpush('userQueue', '001', scope='queue')
DFF.CACHE.lpush('userQueue', '002', scope='queue')
DFF.CACHE.lpush('userQueue', '003', scope='queue')

DFF.CACHE.rpoplpush('userQueue', 'userQueue2', scope='queue')
# '001'
小技巧:队列滚动
1
2
3
4
5
6
7
8
9
DFF.CACHE.lpush('userQueue', '001', scope='queue')
DFF.CACHE.lpush('userQueue', '002', scope='queue')
DFF.CACHE.lpush('userQueue', '003', scope='queue')

DFF.CACHE.rpoplpush('userQueue', scope='queue')
# '001'

DFF.CACHE.rpoplpush('userQueue', scope='queue')
# '002'

DFF.CACHE.brpoplpush(...)

于 6.0.6 版本新增

以阻塞方式,从一个列表结构右侧弹出元素,同时向另一个列表结构左侧推入元素,并返回此元素,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名(来源)
dest_key str key 相同 键名(目标)
scope str 当前脚本名 命名空间(来源)
dest_scope str scope 相同 命名空间(目标)
示例
1
2
3
4
5
6
DFF.CACHE.lpush('userQueue', '001', scope='queue')
DFF.CACHE.lpush('userQueue', '002', scope='queue')
DFF.CACHE.lpush('userQueue', '003', scope='queue')

DFF.CACHE.brpoplpush('userQueue', 'userQueue2', timeout=3, scope='queue')
# '001'

DFF.CACHE.llen(...)

获取列表结构元素数量,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
DFF.CACHE.lpush('userQueue', '001', scope='queue')
DFF.CACHE.lpush('userQueue', '002', scope='queue')

DFF.CACHE.llen('userQueue', scope='queue')
# 2

DFF.CACHE.lrange(...)

获取列表结构内元素列表(不弹出),参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
start int 0 起始索引(包含)
stop int -1 结束索引(包含,-1 表示最后一个)
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
6
7
8
9
DFF.CACHE.rpush('userQueue', '001', scope='queue')
DFF.CACHE.rpush('userQueue', '002', scope='queue')
DFF.CACHE.rpush('userQueue', '003', scope='queue')
DFF.CACHE.rpush('userQueue', '004', scope='queue')

DFF.CACHE.lrange('userQueue', 0, 1, scope='queue')
# [ '001', '002' ]
DFF.CACHE.lrange('userQueue', 0, -1, scope='queue')
# [ '001', '002', '003', '004' ]

DFF.CACHE.ltrim(...)

左侧开始,保留列表结构内元素,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
start int 必须 起始索引(包含)
stop int 必须 结束索引(包含,-1 表示最后一个)
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
6
DFF.CACHE.rpush('userQueue', '001', scope='queue')
DFF.CACHE.rpush('userQueue', '002', scope='queue')
DFF.CACHE.rpush('userQueue', '003', scope='queue')
DFF.CACHE.rpush('userQueue', '004', scope='queue')

DFF.CACHE.ltrim('userQueue', 0, 1, scope='queue')
小技巧:限制队列长度(回卷)
1
2
3
4
limit = 3
for i in range(100):
    DFF.CACHE.lpush('userQueue', i, scope='queue')
    DFF.CACHE.ltrim('userQueue', 0, limit, scope='queue')

别名方法

于 6.0.6 版本新增

由于对列表结构的 PUSH / POP 操作同时支持从左到右和从右到左。

为了避免混乱,保证始终操作方向统一,可以使用以下别名方法。

别名方法 对应实际方法
push lpush
pop rpop
bpop brpop

集合类(Set)

使用集合结构可以保存不重复的成员

DFF.CACHE.sadd(...)

于 6.0.6 版本新增

添加成员,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
member str 必须 成员
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.sadd('staredUsers', 'user-001', scope='set')

DFF.CACHE.srem(...)

于 6.0.6 版本新增

删除成员,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
member str 必须 成员
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.srem('staredUsers', 'user-001', scope='set')

DFF.CACHE.scard(...)

于 6.0.6 版本新增

获取成员数量,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
DFF.CACHE.scard('staredUsers', scope='set')
# 1

DFF.CACHE.smembers(...)

于 6.0.6 版本新增

获取成员列表,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
DFF.CACHE.sadd('staredUsers', 'user-001', scope='set')
DFF.CACHE.sadd('staredUsers', 'user-002', scope='set')

DFF.CACHE.smembers('staredUsers', scope='set')
# ['user-002', 'user-001']

DFF.CACHE.sismember(...)

于 6.0.6 版本新增

检查成员是否在集合内,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
DFF.CACHE.sadd('staredUsers', 'user-001', scope='set')
DFF.CACHE.sadd('staredUsers', 'user-002', scope='set')

DFF.CACHE.sismember('staredUsers', 'user-002', scope='set')
# True

有序集合类(ZSet)

使用集合结构可以保存不重复的成员,并按照指定的分数(score,int / float 类型)保证有序

DFF.CACHE.zadd(...)

于 6.0.6 版本新增

添加成员,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
member_scores dict 必须 成员-分数字典
scope str 当前脚本名 命名空间
示例
1
2
3
4
5
data = {
  'user-001': 100,
  'user-002': 200,
}
DFF.CACHE.zadd('staredUsers', data, scope='zset')

DFF.CACHE.zrem(...)

于 6.0.6 版本新增

删除成员,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
member str 必须 成员
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.zrem('staredUsers', 'user-001', scope='zset')

DFF.CACHE.zcard(...)

于 6.0.6 版本新增

获取成员数量,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
scope str 当前脚本名 命名空间
示例
1
2
DFF.CACHE.zcard('staredUsers', scope='zset')
# 1

DFF.CACHE.zrange(...)

于 6.0.6 版本新增

根据得分 Score 顺序索引获取成员,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
start int 0 起始索引(包含)
stop int -1 结束索引(包含,-1 表示最后一个)
reverse boolean False 是否反向输出
with_scores boolean False 是否同时返回分数
scope str 当前脚本名 命名空间
示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
data = {
  'user-001': 100,
  'user-002': 200,
  'user-003': 300,
}
DFF.CACHE.zadd('staredUsers', data, scope='zset')

DFF.CACHE.zrange('staredUsers', scope='zset')
# ['user-001', 'user-002', 'user-003']
DFF.CACHE.zrange('staredUsers', start=1, stop=-1, scope='zset')
# ['user-002', 'user-003']
DFF.CACHE.zrange('staredUsers', with_scores=True, scope='zset')
# [['user-001', 100.0], ['user-002', 200.0], ['user-003', 300.0]]

DFF.CACHE.zrangebyscore(...)

于 6.0.6 版本新增

根据得分 Score 获取成员,参数如下:

参数 类型 必须 / 默认值 说明
key str 必须 键名
min_score int "-inf" 起始得分 Score(包含, "-inf" 表示最小值)
max_score int "+inf" 结束得分 Score(包含, "+inf" 表示最大值)
with_scores boolean False 是否同时返回分数
scope str 当前脚本名 命名空间
示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
data = {
  'user-001': 100,
  'user-002': 200,
  'user-003': 300,
}
DFF.CACHE.zadd('staredUsers', data, scope='zset')

DFF.CACHE.zrangebyscore('staredUsers', scope='zset')
# ['user-001', 'user-002', 'user-003']
DFF.CACHE.zrangebyscore('staredUsers', min_score=200, max_score=200, scope='zset')
# ['user-002']
DFF.CACHE.zrangebyscore('staredUsers', with_scores=True, scope='zset')
# [['user-001', 100.0], ['user-002', 200.0], ['user-003', 300.0]]

消息类

使用消息类方法可以向订阅特定主题的客户端发送消息

DFF.CACHE.publish(...)

向主题发布消息,参数如下:

参数 类型 必须 / 默认值 说明
topic str 必须 主题
message str 必须 消息内容
scope str 当前脚本名 命名空间
示例
1
DFF.CACHE.publish('some_topic', 'hello', scope='app')