脚本开发 / 文件系统存储 DFF.STORE_FS

于 8.1.18 版本新增

DFF.STORE_FS 用于在文件系统中持久化小规模 JSON 数据，按 scope + key 读写。它与 DFF.STORE 的调用方式一致，但数据彼此独立；相同 Scope 和 Key 不会共享值。

1. 读写数据

Key 和 Scope 均为最长 256 个字符的字符串。省略 scope 时使用当前 Script ID；跨脚本访问时应显式指定相同的 Scope。

DFF.STORE_FS.set('settings', {'enabled': True}, scope='app')
settings = DFF.STORE_FS.get('settings', scope='app')

DFF.STORE_FS.mset({
    'job:1': {'status': 'ready'},
    'job:2': {'status': 'ready'},
}, expires=60, scope='app')
jobs = DFF.STORE_FS.get_pattern('job:*', scope='app')

方法	返回值 / 说明
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_FS(key, scope=None)	返回值；不存在或已过期时返回 None
mget(keys, scope=None)	返回 {key: value}，缺失或过期的值为 None
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 动态引用

expires 为过期秒数；省略或传入假值表示不过期，后续不带过期时间的写入会清除原有过期时间。not_exists=True 允许写入缺失或已过期的记录，保留仍有效的已有记录。写入方法返回 None，需要确认结果时应回读；批量写入逐项执行，不是全有或全无的事务。

模式匹配完整键名，* 匹配任意长度，? 匹配单个字符，其他字符按字面匹配。模式操作会扫描所选 Scope，适用于小规模数据。

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

delete_pattern() 默认使用 '*'。删除部分数据时应显式传入模式，并先使用 keys(...) 核对匹配结果。

2. 动态引用

DFF.STORE_FS.ref(...) 可用于 DFF.API 的 delayed_cron_job、timeout、expires 和 queue 参数。省略 scope 时使用 REF，与普通读写的默认 Scope 不同，应显式传入与写入方一致的 Scope。

记录缺失、已过期或值为 JSON null 时使用 default；0、False 和空字符串会保留并交由目标参数校验。具体用法见 脚本开发 / 导出函数 DFF.API / 动态引用。

3. 存储与部署

数据保存在资源目录的 store-fs 子目录中。在配置文件 config.yaml 中配置了 RESOURCE_ROOT_PATH 时，使用该资源目录。所有使用这些值的 Server 和 Worker 实例都必须访问同一个资源目录，包括解析动态引用的 Server。

底层文件系统需要支持文件锁和原子替换；备份应覆盖资源目录。资源目录权限决定数据访问权限，不要将存储目录包含在公开文件服务根目录中，也不要直接编辑托管文件。

读取会过滤过期记录，后台清理负责物理回收。大文件、大型列表和复杂查询应使用其他存储或数据库连接器；临时缓存可使用 脚本开发 / 简易缓存 DFF.CACHE。