指令碼開發 / 簡易儲存 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 長期儲存大檔案或大型列表。