跳轉至

腳本開發 / 簡易緩存 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')