跳轉至

簡易緩存 DFF.CACHE

腳本開發 / 簡易緩存 `DFF.CACHE`

DFF.CACHE 是基於 Redis 的臨時緩存，結構為 scope + key -> value，適合計數器、隊列、集合和輕量消息發佈。

需要保留 JSON 類型或持久保存小規模應用狀態時，應使用 DFF.STORE。

關鍵差異

讀出的標量值通常是字符串，需要按業務類型調用 int(...)、float(...) 或 json.loads(...)。
默認 scope 是當前 Script ID；跨 Script 共享數據時必須顯式傳入相同的 scope。
每個 Key 和發佈 Topic 都按 Scope 隔離，返回的 Key 名不包含內部 Scope 前綴。
hstrlenall(...) 返回 {field: value字節長度}，長度單位是字節，不是 Unicode 字符數。

API 速查

Key

方法	説明
`type(key, scope=None)`	返回 Key 的數據類型
`keys(pattern='*', scope=None)`	返回匹配的 Key
`exists(key, scope=None)`	判斷 Key 是否存在
`expire(key, expires, scope=None)`	設置剩餘過期秒數
`expireat(key, timestamp, scope=None)`	設置 UNIX 秒時間戳形式的過期時間
`ttl(key, scope=None)` / `pttl(key, scope=None)`	返回剩餘過期時間，單位分別為秒和毫秒
`rename(key, new_key, scope=None)`	重命名 Key
`renamenx(key, new_key, scope=None)`	僅當目標不存在時重命名 Key
`delete(key, scope=None)`	刪除單個 Key，或傳入列表 / 元組批量刪除
`delete_pattern(pattern, scope=None)`	刪除匹配的 Key；`pattern` 必填

String

方法	説明
`set(key, value, expires=None, not_exists=False, exists=False, scope=None)`	寫入值，可限制 Key 存在狀態和過期秒數
`mset(key_values, scope=None)`	批量寫入；不支持同時設置過期時間
`get(key, scope=None)` / `DFF.CACHE(key, scope=None)`	讀取單個值
`mget(keys, scope=None)`	批量讀取
`get_pattern(pattern, scope=None)`	返回匹配的 `{key: value}`
`getset(key, value, scope=None)`	寫入新值並返回舊值
`incr(key, step=1, scope=None)` / `incrby(key, step, scope=None)`	增加整數值

Hash

方法	説明
`hkeys(key, pattern='*', with_values=False, scope=None)`	返回匹配字段；`with_values=True` 時同時返回值
`hset(key, field, value, not_exists=False, scope=None)`	寫入字段
`hsetnx(key, field, value, scope=None)`	僅在字段不存在時寫入
`hmset(key, field_values, scope=None)`	批量寫入字段
`hget(key, field, scope=None)`	讀取字段
`hstrlen(key, field, scope=None)` / `hstrlenall(key, scope=None)`	返回一個或全部字段值的字節長度
`hmget(key, fields, scope=None)`	批量讀取字段
`hgetall(key, scope=None)`	讀取全部字段和值
`hincr(key, field, step=1, scope=None)` / `hincrby(key, field, step, scope=None)`	增加整數字段值
`hdel(key, field, scope=None)`	刪除單個字段，或傳入列表 / 元組批量刪除

List

方法	説明
`lpush(key, value, scope=None)` / `rpush(key, value, scope=None)`	從左側 / 右側壓入一個值或值列表
`lpop(key, count=None, scope=None)` / `rpop(key, count=None, scope=None)`	從左側 / 右側彈出一個或多個值
`blpop(key, timeout=0, scope=None)` / `brpop(key, timeout=0, scope=None)`	阻塞彈出
`rpoplpush(key, dest_key=None, scope=None, dest_scope=None)`	從源列表右側彈出並壓入目標列表左側
`brpoplpush(key, dest_key=None, timeout=0, scope=None, dest_scope=None)`	阻塞執行彈出並壓入
`llen(key, scope=None)`	返回列表長度
`lrange(key, start=0, stop=-1, scope=None)`	返回指定範圍
`ltrim(key, start, stop, scope=None)`	只保留指定範圍

blpop(...) 和 brpop(...) 返回 [原始鍵名, value]，超時返回 [None, None]。rpoplpush(...) 和 brpoplpush(...) 省略目標 Key 時會使用源 Key，dest_scope 可用於明確的跨 Scope 移動。

Set

方法	説明
`sadd(key, member, scope=None)` / `srem(key, member, scope=None)`	添加 / 刪除一個成員或成員列表
`scard(key, scope=None)`	返回成員數
`smembers(key, scope=None)`	返回全部成員
`sismember(key, member, scope=None)`	判斷成員是否存在

ZSet

方法	説明
`zadd(key, member_scores, scope=None)` / `zrem(key, member, scope=None)`	添加 / 刪除成員
`zcard(key, scope=None)`	返回成員數
`zrange(key, start=0, stop=-1, with_scores=False, scope=None)`	按位置返回成員
`zrangebyscore(key, min_score='-inf', max_score='+inf', with_scores=False, scope=None)`	按分數返回成員
`zpop_below_all(key, score, scope=None)` / `zpop_above_all(key, score, scope=None)`	彈出不高於 / 不低於指定分數的全部成員
`zpop_below_lpush_all(key, dest_key, score, scope=None)` / `zpop_above_lpush_all(key, dest_key, score, scope=None)`	彈出符合分數條件的成員，並將其壓入目標列表

執行 ZSet 彈出或移動擴展前，應確認源 Key、目標 Key 和分數邊界。

發佈與動態引用

方法	説明
`publish(topic, message, scope=None)`	向帶 Scope 前綴的 Topic 發佈消息
`ref(key, scope=None, default=None)`	為支持動態取值的 `DFF.API` 參數創建延遲引用

ref(...) 省略 scope 時使用專用的 REF Scope。String、List、Hash、Set 和 ZSet 會分別使用對應的讀取操作解析引用。引用只用於 DFF.API 的 delayed_cron_job、timeout、expires 和 queue 參數。

示例

常用數據結構
import json

DFF.CACHE.set('count', 1, expires=60, scope='job')
count = int(DFF.CACHE.get('count', scope='job') or 0)

DFF.CACHE.hmset('user:001', {'name': 'Tom', 'age': 20}, scope='users')
age = int(DFF.CACHE.hget('user:001', 'age', scope='users') or 0)

DFF.CACHE.rpush('queue', json.dumps({'id': 1}), scope='jobs')
item = json.loads(DFF.CACHE.lpop('queue', scope='jobs'))

使用注意事項

阻塞操作應設置合理的 timeout，避免 Func 超時。
執行 delete_pattern(...) 前，應先使用 keys(...) 檢查匹配項。
避免對超大 Hash 調用 hstrlenall(...)，以免阻塞共享緩存服務。
publish(...) 的 Topic 帶有 Scope 前綴，訂閲方必須使用一致的 Scope 約定。
多個 Script 共享數據時，應顯式傳入 scope。