腳本開發 / 簡易存儲 DFF.STORE

DFF.STORE 用於持久化小規模 KV 數據，結構為 scope + key -> value。寫入時會自動進行 JSON 序列化，讀取時自動反序列化並保留 JSON 類型。

複雜查詢或大量數據應使用數據庫連接器。短生命週期、高頻訪問且可接受字符串化的數據應使用 DFF.CACHE。

通用參數

參數	必須 / 默認值	説明
key	必須	鍵名，最長 256 個字符
value	必須	JSON 可序列化對象
expires	None	過期秒數；None 表示永不過期
scope	當前 Script ID	命名空間，最長 256 個字符
pattern	"*"	鍵名匹配；* 匹配任意長度，? 匹配單個字符

API

方法	返回值 / 説明
set(key, value, expires=None, not_exists=False, scope=None)	寫入單個值，返回 None
mset(key_values, expires=None, not_exists=False, scope=None)	批量寫入，返回 None
get(key, scope=None) / DFF.STORE(key, scope=None)	返回值；不存在或已過期時返回 None
mget(keys, scope=None)	返回 {key: value}
getall(scope=None)	返回 Scope 下的全部數據
keys(pattern='*', scope=None)	返回匹配的 Key 列表
get_pattern(pattern='*', scope=None)	返回匹配的數據 {key: value}
delete(key, scope=None)	刪除指定 Key
delete_pattern(pattern='*', scope=None)	刪除匹配的 Key
ref(key, scope=None, default=None)	為支持動態取值的 DFF.API 參數創建延遲引用

DFF.STORE.set('user:user-001', {'name': 'User A'}, scope='users')
user = DFF.STORE.get('user:user-001', scope='users')

DFF.STORE.mset({
    'user:user-002': {'name': 'User B'},
    'user:user-003': {'name': 'User C'},
}, scope='users')

users = DFF.STORE.get_pattern('user:*', scope='users')

mget(...) 會包含每個請求的 Key，缺失或已過期的值為 None；get_pattern(...) 只包含匹配且仍有效的記錄。

使用 not_exists=True 時，剛過期的 Key 仍可能阻止創建。set(...) 和 mset(...) 都返回 None，必須確認創建結果時應在寫入後讀取。批量寫入會逐項執行，不是全有或全無的事務。

缺失或假值 expires 表示不過期；後續不帶過期時間的寫入會清除原有過期時間。舊代碼可能使用 expire 參數，新代碼應統一使用 expires。

動態引用

DFF.STORE.ref(...) 返回動態引用，可用於 DFF.API 的 delayed_cron_job、timeout、expires 和 queue 參數。省略 scope 時，引用使用專用的 REF Scope，而不是當前 Script Scope；通常應顯式傳入與寫入方一致的 Scope。

模式刪除默認會匹配整個 Scope

delete_pattern() 的默認模式是 '*'。除非明確需要刪除整個 Scope，否則必須顯式傳入 pattern，並先通過 keys(...) 查看匹配到的 Key。

不要使用 DFF.STORE 長期保存大文件或大型列表。