跳轉到

指令碼開發 / 簡易快取 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')