脚本开发 / 简易存储 DFF.STORE

DFF.STORE 用于持久化小规模 KV 数据，结构为 scope + key -> value。写入时会自动进行 JSON 序列化，读取时自动反序列化并保留 JSON 类型。

需要将数据保存到文件系统时，可使用 脚本开发 / 文件系统存储 DFF.STORE_FS。两种存储的数据彼此独立。

复杂查询或大量数据应使用数据库连接器。短生命周期、高频访问且可接受字符串化的数据应使用 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(...) 只包含匹配且仍有效的记录。

自 8.1.18 起，使用 not_exists=True 时，不存在或已过期的 Key 均允许写入，即使过期记录尚未物理清理；仍有效的已有记录保持不变。set(...) 和 mset(...) 都返回 None，必须确认创建结果时应在写入后读取。批量写入会逐项执行，不是全有或全无的事务。

缺失或假值 expires 表示不过期；后续不带过期时间的写入会清除原有过期时间。旧代码可能使用 expire 参数，新代码应统一使用 expires。

自 8.1.18 起，keys(...)、get_pattern(...) 和 delete_pattern(...) 的模式匹配完整键名：abc 只匹配 abc，*abc* 匹配包含 abc 的键，abc? 匹配 abc 后恰好一个字符。除 * 和 ? 外，其他字符均按字面匹配。依赖旧版本包含匹配的调用，应显式补上 *；删除前先使用 keys(...) 核对结果。

动态引用

DFF.STORE.ref(...) 返回动态引用，可用于 DFF.API 的 delayed_cron_job、timeout、expires 和 queue 参数。省略 scope 时，引用使用专用的 REF Scope，而不是当前 Script Scope；通常应显式传入与写入方一致的 Scope。

记录缺失、已过期或值为 JSON null 时，引用使用 default；0、False 和空字符串会保留并交由目标参数校验，不会替换为默认值。

模式删除默认会匹配整个 Scope

delete_pattern() 的默认模式是 "*"。除非明确需要删除整个 Scope，否则必须显式传入 pattern，并先通过 keys(...) 查看匹配到的 Key。

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