接口引擎

接口引擎用后端脚本沉淀可复用 HTTP / MCP 接口，供列表、表单、页面按钮与第三方调用。脚本宿主与数据集相同：后端 Jint，结果写到 App.Response.Body。

新增接口

1. 进入 系统引擎 → 接口引擎（路由 /system-engine/interface-engine）。

   

2. 新增分组，若已有分组或不分组跳过；点击【新增】->【分组】，打开分组表单填写分组名称后点击【确定】保存即可。

   

3. 点击【新增】->【接口】打开接口表单；填写完成表单后点击【确定】保存。

   

   表单字段说明：

   属性	说明
   分组	归属接口分组，便于列表归类
   名称	必填。列表展示名称
   描述	用途说明
   路由	必填。HTTP 路径，如 /api/crm/v1/orders/search
   请求方法	必填。见下表；须大写
   启用日志	开：日志写入 t_interface_log表
   异常日志	开：仅记录异常；关：成功也记（需同时启用日志）
   MCP 支持	开：作为动态 MCP 工具暴露，开启后需要在MCP Schema 中配置入参。
   MCP 工具名	MCP name；站点内唯一，建议字母数字下划线
   允许匿名	开：未登录可调；关：须登录且角色有接口权限
   是否启用	关：路由不生效
   脚本	后端 JS 正文；须设置 App.Response.Body
   MCP Schema	JSON 文本；OpenAPI 风格参数数组或 object schema

   请求方法（下拉）

   选项	效果
   GET	无 Body；参数多在 Query / 路由；适合查询
   POST	Body 进入 App.Request.Body；适合检索、创建、复杂入参
   PUT	Body 进入 App.Request.Body；适合全量或按约定更新
   DELETE	常配合路由参数删除；Body 视调用方而定

编辑接口

1. 在接口引擎列表中选中一行，点击操作列【编辑】打开表单。
2. 修改表单中的信息，点击【确认】。

提示： 若改了路由或方法，前端调用方与第三方文档须同步更新；开启 MCP 时改工具名后，客户端也要改调用名（动态工具缓存约 1 分钟）。

删除接口

选中要删除的接口，点击操作列【删除】，按提示点击【确认】。

提示：

1.删除的是引擎库中的接口登记与脚本，不会删除业务表数据。

2.删除前确认没有列表 / 树、按钮、权限或第三方仍指向该接口；否则运行态会 404 或无权限。

接口调试

点击工具栏【测试】按钮，打开接口调试器。

默认库查询示例

不传数据源名时，使用站点默认关系库；结果写到 App.Response.Body：

try {
  var body = App.Request.Body || {};//body为传入参数
  var phone = body.phone;
  if (!phone) {
    App.Response.StatusCode = 400;
    App.Response.Body = { ok: false, message: 'phone required' };
    return;
  }

  var rows = App.Services.DatabaseService.Query({
    table: 'contact',
    type: 1,
    wheres: [{
      type: 1,
      values: [{
        column: 'phone',
        type: 0,
        value: String(phone),
        value_source_type: 1,
        value_type: 0
      }]
    }],
    columns: ['id', 'name', 'phone'],
    page: { page_size: 1, page_number: 1 }
  });

  var row = rows.length > 0 ? rows[0] : null;
  App.Response.Body = {
    ok: true,
    data: row ? { id: row.id, name: row.name, phone: row.phone } : null
  };
} catch (e) {
  App.IsException = true;
  App.Helpers.Logger.Error(String(e));
  App.Response.StatusCode = 500;
  App.Response.Body = { ok: false, message: String(e) };
}

多库、写入约定见 关系数据库；完整语法见 后端脚本。

创建或改完接口后，需要打开调试器检测。

示例入参：

{
  "id": "1234567890123456789",
  "body": {
    "headers": {},
    "querys": {},
    "routes": {},
    "body": { "phone": "13800138000" }
  }
}

失败则改脚本或配置后重跑，通过后再开放给业务引用。

前端与第三方调用

• 前端：App.Services.InterfaceService.Execute({ ... })（或按站点约定封装）。
• 非匿名接口必须携带token

常见问题

保存成功但调用 404 / 无响应

检查 是否启用、路由是否与调用路径一致、请求方法是否大写且匹配；动态路由改完后可能有短时缓存。

脚本执行了但返回空

须给 App.Response.Body 赋值；不要用已废弃的 App.Result。

查询不到表或列

DatabaseService.Query 的 table / column 用 map_name；表须先在数据仓库同步。见 关系数据库。

列表下拉没数据，却配了数据集

列表 / 树的 source_id 只能填 接口 id。数据集应挂在表单控件的 source_value（source_type=2），不要把数据集 id 当 source_id。

MCP 工具调不到

确认已开 MCP 支持、context 已保存；改配置后等待缓存约 1 分钟。非匿名时同样校验接口权限。

如何确认接口可用

用调试器按正常、非法参数、无权限、异常分支各跑一遍，再给业务引用。