后端 HTTP 接口参考

HTTP 接口处理函数是后端插件的 HTTP 接口：调用方通过统一端点 POST /plugin/invoke 传入参数，脚本执行后返回一个 JSON 对象。你写 TypeScript 源文件，构建后由运行时装载执行。

登记方式（按文件自动发现，无需在清单声明）

文件路径 + 命名导出 = 接口名：

规则	例子
`handlers/*/.ts` 一个文件一个 HTTP 接口处理函数，导出名用文件末段的动作名	`handlers/example/create.ts` + `export function create` → 接口名 `example.create`

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

清单 scripts[] / events[] 认领过的入口不会再登记成 HTTP 接口处理函数（防止内部脚本被当 HTTP 接口调用）。

路径段不能含点、不能以 _ 开头。

改文件路径等于改接口名——调用方会跟着 404，把它当作 API 契约的一部分来管理。

语义详解见 HTTP 接口指南。

函数签名

fh2-plugin-sdk/backend 表示插件 SDK 的后端类型入口；实际导入路径保留生成工程的配置，不按示意名安装依赖。

// handlers/example/create.ts
import { createRecord } from '../../shared/records'
import type { RecordInput, RecordResult } from '../../shared/records'
import type { HandlerCtx } from 'fh2-plugin-sdk/backend'

export function create (input: RecordInput, ctx: HandlerCtx): RecordResult {
  return createRecord(input, 'handler')
}

签名是 <动作名>(input, ctx)；ctx 见脚本上下文——只装请求事实，能力不在上下文上（是 allowlist 注入的全局对象）。

input 整块透传，平台不校验不裁剪；必填与类型检查由脚本自己做。

返回值必须是对象，原样放进响应 data；返回标量、数组或 undefined 会失败。

调用

请求体只允许 pluginId、handler、input 三个顶层字段，多一个返回 40001。

Idempotency-Key：平台不代生成；脚本要用 ctx.stableId() 就必须带上。写操作传业务稳定键，读操作不传。

前端插件调用后端的写法：ctx.apiCall('/plugin/invoke', {method: 'POST', body: {pluginId, handler, input}})——pluginId 写后端插件的 ID。

执行环境

项	值
超时	5 秒，不可配置；做不完的事交给流程编排
模块策略（源码）	允许相对导入插件内模块（`shared/`）；禁止 Node.js 内置模块、裸包、动态导入（构建期校验）
并发限制	无计时器、无 `async/await`（同步沙箱）；要延迟/重试交给流程
能力注入	按包级 `allowlist` 注入全局对象，见能力目录；同一插件所有 HTTP 接口处理函数共用一份权限

错误

throw { code: 'NOT_FOUND', message: '记录不存在' }

分类	典型错误码	HTTP / 业务码	调用方
契约错	`INVALID_ARGUMENT`、`UNKNOWN_FIELD`、`TYPE_MISMATCH`、`PERMISSION_DENIED` 等	400 / `40006`	改参数，不要重试
业务结果	`NOT_FOUND`、`DUPLICATE`、`CONFLICT`	200 / `20001`	按业务处理，不是成功也不是故障
可重试	`TIMEOUT`、`STORAGE_ERROR`，以及认不出的错误码、普通 `Error`	503 / `50301`	可退避重试（建议带幂等键）

成功判据：HTTP 2xx 且 code === 0。完整业务码表见错误码。

常见问题

现象	原因与处理
返回 40006「找不到 HTTP 接口处理函数」	名字拼错、文件没放 `handlers/` 目录、路径和导出名对不上（如 `create.ts` 里导出了 `handle`），或入口被 `scripts[]`/`events[]` 认领了
返回 50301	抛了认不出的错误码（如拼写错误）、脚本超时或内部错误；核对三分类表
脚本里 `store is not defined`	包级 `allowlist` 没申报 `data:read`/`data:write`；缺申报的对象根本不会注入
`ctx.stableId()` 抛 INVALID_ARGUMENT	调用方没带 `Idempotency-Key` 头

登记方式（按文件自动发现，无需在清单声明）#

函数签名#

调用#

执行环境#

错误#

常见问题#

登记方式（按文件自动发现，无需在清单声明）

函数签名

调用

执行环境

错误

常见问题