数据存储与缓存

插件需要持久化业务数据（航线、会话、事件记录……）时，用平台提供的两个存储：

	`store`（数据存储）	`cache`（缓存）
存什么	权威业务数据	临时状态、热点数据
会丢吗	不会（平台数据库）	会（有 TTL，过期即删）
怎么查	按条件查、排序、分页	只能按键精确取
隔离	物理表名全局统一：`plugin_db_<entity>`；装载期拒绝跨插件同名实体	所有插件共享一个键空间
权限	`data:read` / `data:write`	`cache:read` / `cache:write`

一句话选型：这数据丢了要不要紧、要不要长期精确查？要 → store；丢了无所谓、就是为了快 → cache。 特别注意"去重"：窗口期内去重（如 1 小时内别重复处理）用 cache 的 setnx；永久去重必须用 store 的唯一索引（createIfAbsent）——缓存会过期，过期后就会重复处理。

数据存储（store）

建表：schema.sql 是唯一事实源

数据表由 schema.sql 单点定义。你只写这一份：

本地 dev：工具链从 schema.sql 派生存储声明，本地模拟器在内存建表。

构建：派生的实体投影进运行时清单（dist/plugin.json），宿主装载时按它校验 store 调用——不要在源清单里手写 entities[]。

生产：部署方在发布流程中执行 schema.sql 建真实表（平台不会自动建表）。

规则：

物理表名 = plugin_db_<实体名>，前缀平台拼。

SQL 平台列为 id / created_at / updated_at，另保留 tenant_id（当前不自动写）。JS store 返回及筛选/排序使用 id / createdAt / updatedAt；tenant_id 不是脚本可直接读写的平台字段。

insert 可指定 id，不指定则由平台生成；创建/更新时间由平台维护，不能写入业务记录，平台字段也不能用于更新内容。业务响应数据结构可以保留自己的 created_at，从 record.createdAt 映射，见共享契约。

业务字段从 JS 写入时一律传字符串（布尔用 '1'/'0'）。毫秒时间戳建议用 TEXT 存定宽 13 位字符串（如 "1788861600000"）；TEXT 上的范围筛选和排序按字典序，不补零会出错。

业务字段名统一用下划线命名（和物理业务列名一致）；平台时间字段使用上述公开名，不要将物理列名当作脚本字段。

漏跑 DDL 的表现：包能装载，首次访问数据报 STORAGE_ERROR。

六个方法

注意：没有 get 和 put。按主键查一条用 query + limit: 1，空列表自己翻成 NOT_FOUND；删除按条件删，不是按 id 删。

查询写法

算子全集：eq neq gt gte lt lte in nin contains startsWith endsWith isNull isNotNull。顶层字段之间是 AND（不支持 OR，需要 OR 就拆多次查询在脚本里合并）。

分页与排序：limit 缺省 100、最大 1000；offset 最大 100000；排序字段最多 3 个，末尾自动补 id ASC 保证分页稳定。

这些是后端运行时的查询约束；本地模拟器对对象形式 orderBy 和分页的支持不等价，不能据此确认"最新一条"或任意历史列表。保持正式查询形状，在已部署测试环境验证排序与分页，见已知限制。

幂等与并发：两条铁律

"有则取、无则建"用 createIfAbsent，不要"先查再写"。 并发下"先查再插"会插重：

"抢占状态"用带条件的 update，看 affected 行数。 不要 update 后再查一次判断自己抢到没有：

前提：uniqueBy 的字段在数据库里有对应 UNIQUE 索引（schema.sql 里建），否则 createIfAbsent 报 STORAGE_ERROR，不会退化成普通插入。

错误码

UNKNOWN_ENTITY（实体没声明/表没建）、UNKNOWN_FIELD（列名错）、INVALID_FILTER（筛选写错）、EMPTY_FILTER（update/delete 用了空筛选，被拒绝）、TYPE_MISMATCH、DUPLICATE、LIMIT_EXCEEDED、PERMISSION_DENIED、STORAGE_ERROR（库异常，可重试）。

当前不支持的

事务（多表原子性）、关联查询、OR、聚合（计数/求和/分组）、批量写、裸 SQL、跨插件访问。需要跨表原子性的业务，要么设计成"一张表一个唯一键 + 状态机"，要么等平台事务能力，不要用补偿代码假装原子。

缓存（cache）

cache 是平台提供的缓存能力，底层服务由部署方配置。适合：事件去重（窗口期）、外部配置缓存几分钟、限流计数、粗粒度锁。cache.get/set/setnx 返回 {ok,data} 或 {ok:false,error}；connector.fetch 不返回这个信封，而是返回 {status,headers,body}，网络或出网限制错误以异常抛出。不能因为 store 使用信封就假设所有能力都同形。

下面是一个流程脚本里的热点配置片段。前提是：清单连接声明了 traffic.connector.cascade，部署方已配置 baseUrl，流程步骤用 inputs.connectorId 指向它；脚本有效 allowlist 包含 cache:read、cache:write、config:get、egress:fetch，且目标主机已获出网白名单放行。只缓存业务展示值，不缓存连接凭据或上游返回的敏感字段。

关键事实：

平台不为缓存键加前缀，所有插件共享一个缓存键空间。要私有的键自己带插件名前缀（myplugin:dedup:...）；两个插件要协作共享数据，约定一个公共前缀即可——这是受支持的用法。

set 的 ttl 必填，范围 1 秒 ~ 24 小时，超限报 TTL_INVALID。要存超过 24 小时的状态，说明它该进 store。

值自动 JSON 序列化/反序列化：存什么类型取回什么类型。

限额：键 ≤ 256 字节、值 ≤ 1 MB、单次脚本最多 256 次缓存调用。

常见坑

现象	原因
首次访问数据报 `STORAGE_ERROR`	schema.sql 没执行，表不存在
时间范围筛选查不到数据	时间戳没存定宽字符串，字符串比较乱了
`createIfAbsent` 报 `STORAGE_ERROR`	`uniqueBy` 字段没有 UNIQUE 索引
并发下出现重复数据	用了"先查再插"；改用 `createIfAbsent`
缓存过期后重复处理	把永久去重放在了 cache 里；挪到 store 唯一索引
两个插件互相读不到对方的缓存	一方自带了前缀另一方没有；约定统一前缀

数据存储（store）#

建表：schema.sql 是唯一事实源#

六个方法#

查询写法#

幂等与并发：两条铁律#

错误码#

当前不支持的#

缓存（cache）#

常见坑#