后端插件的结构

一个后端插件 = 一个含 fh2-plugin.json（源清单）的目录。你写 TypeScript；构建时工具链把它编译打包成运行时可装载的普通 JS 和 dist/plugin.json（运行时清单）。这一页讲清：目录里放什么、三种入口怎么登记、构建前后是什么关系。

目录里放什么

backend/my_backend/
├── fh2-plugin.json      # 源清单：身份、权限、声明有哪些脚本和流程
├── handlers/            # HTTP 接口脚本（放进去自动登记，一个文件一个接口）
│   └── example/create.ts    # → 接口名 example.create
├── events/              # 消息回调脚本（由清单 events[] 引用）
├── adapters/            # 流程用脚本（由清单 scripts[] 引用）
├── workflows/           # 流程编排 JSON（由清单 flows[] 列出，列了才装载）
├── shared/              # 多入口共用的业务逻辑（普通 TS 模块，相对 import）
├── types/               # fh2-plugin types 生成的类型声明，不要手改
├── schema.sql           # 建表 SQL：存储契约的唯一事实源
└── tsconfig.json

四种入口，登记方式不同

入口	放哪	怎么登记	名字怎么来
HTTP 接口处理函数	`handlers/*/.ts`	自动发现，清单里不用写	文件路径 + 命名导出：`handlers/example/create.ts` + `export function create` → `example.create`
事件处理函数	`events/*.ts`	清单 `events[]` 引用	`consumer.entry` 指定导出名
流程脚本	`adapters/*.ts`	清单 `scripts[]` 引用	`name` 字段，缺省取文件名
只读判定	`evaluators/*.ts`	清单 `evaluators[]` 引用	`name` 字段；由受审步 `evaluate` 调用

构建后 HTTP 接口处理函数会得到稳定入口名（h_example_create），调用方用 example.create / example_create / h_example_create 三种写法都能寻址。

evaluators 是纯判定入口：注入面恒空，只能使用 log；需要读写数据或调用其他能力时，应使用流程脚本或事件回调。

源码与构建产物

	你写的（源码）	构建后的（产物）
清单	`fh2-plugin.json`	`dist/plugin.json`（运行时清单，宿主装载它）
代码	`handlers/ events/ adapters/ shared/` 下的 `.ts`	`dist/scripts/` 下的 JavaScript 打包文件
谁维护	你	工具链（`fh2-plugin build`），不要手改

后端插件必须先构建再部署：宿主装载的是 dist/ 产物，不是源码。build 只生成构建产物，pack 构建并组装交付包，两者都不启动服务。工程包含后端且未使用 --frontend-only 时，本地 dev 会构建后端并启动 HTTP 模拟器；它不是真实网关，也不执行流程或消息队列。详见后端调试。

运行环境的限制

写脚本前先记住这几条，都是硬性的：

同步沙箱：没有 async/await、计时器、动态 import()、require、eval。要延迟/重试的事交给流程编排。

模块策略：允许从 ./ 相对路径导入本插件内的其他模块（比如 shared/）；禁止 Node 内置模块、裸包导入。三种入口共用的逻辑放 shared/，一份事实，多处复用。

能力按 allowlist 注入：清单申报了 data:read/data:write，脚本里才有 store 这个全局对象；没申报的对象根本不存在（不是 null）。log 恒可用。

输入自己校验：input 原样透传，平台不校验。返回值必须是对象，原样放进响应的 data。

存储：schema.sql 是唯一事实源

数据表由 schema.sql 单点定义；工具链从它派生存储实体投影进构建产物，作者不在清单里写 entities[]。生产环境由部署方在发布流程中执行 schema.sql（平台不会自动建表），本地 HTTP 模拟器按派生声明在内存建表。详见数据存储与缓存。

上下文与能力注入

脚本签名是 <入口函数>(input, ctx)。前端插件的 ctx 上挂能力；后端正相反——能力是按 allowlist 注入的全局对象（store、cache、media……），ctx 只带请求信息。详见 ctx 与能力注入。

下一步

清单字段逐个说明、写第一个接口：从第一个后端插件继续，然后看 HTTP 接口。

数据怎么存：数据存储与缓存。

目录里放什么#

四种入口，登记方式不同#

源码与构建产物#

运行环境的限制#

存储：schema.sql 是唯一事实源#

上下文与能力注入#