调用模块方法

平台应用前端调用模块能力时，统一通过 app-gateway。页面不能直接请求 backend-instance、gateway2、模块服务地址或平台内部接口。

对外公开且稳定的浏览器前缀是 https://api.baijimu.com/app-gateway/api；gateway2 和其他内部服务地址不属于应用 协议。完整的网关选择、授权链和配置方法见 App Gateway 接入与配置。

调用协议

POST /app-gateway/api/workspace-runtime/apps/{installId}/services/{service}/methods/{method}
Authorization: Bearer {appClientToken}
Content-Type: application/json

service 和 method 作为单个 URL 路径段传递。前端拼接 URL 时必须分别使用 encodeURIComponent，不能把未经编码的用户输入直接写入路径。service 不是具体 Runtime businessId。

请求参数

POST 请求体直接是模块方法参数对象：

POST /app-gateway/api/workspace-runtime/apps/pia_xxx/services/course-management/methods/createCourse
Authorization: Bearer ag1_xxx
Content-Type: application/json

{
  "code": "COURSE-001",
  "name": "高等数学",
  "teacherId": 123,
  "tags": ["必修", "一年级"]
}

请求体顶层字段与模块方法 paramDefinitions 中的参数名称一一对应：

• 必填、类型、对象结构和数组元素服从模块方法定义。
• 无参数方法也必须发送 JSON 空对象 {}。
• 不要再包装 service、method 或 params。
• 不要传递 interface、methodBody、userId 或平台身份请求头。
• methodBody 只描述特定模块实现如何访问后端 HTTP 服务，不属于前端调用协议。

例如 createCourse 定义了 code、name、teacherId 和 tags，页面就发送同名 JSON 字段。模块内部是否把 teacherId 转换为 teacher_id，属于模块实现，不影响 页面协议。

interface 绑定

平台应用版本使用 interface 声明逻辑依赖，安装时由平台通过 interfaceBindings 绑定到具体 Runtime businessId。前端把同一个逻辑接口名放进 services/{service} 路径段；App Gateway 先校验当前版本是否声明该接口和方法，再按当前安装解析具体实现。

例如版本声明：

{
  "interface": "wechat-official-account",
  "methods": ["listAuthorizedAccounts"]
}

安装绑定为：

{
  "interfaceBindings": {
    "wechat-official-account": "m-baijimu-2157"
  }
}

前端请求中的 {service} 始终是 wechat-official-account，不能改成 m-baijimu-2157。具体 businessId 只在 App Gateway 与运行态内部流转。

响应

调用成功时，app-gateway 返回统一 CModel 响应，模块方法返回值位于 data：

{
  "errorCode": "0",
  "value": "success",
  "data": {
    "id": 1001,
    "code": "COURSE-001",
    "name": "高等数学"
  },
  "systemCurrentTime": 1785067200000
}

调用方应先判断 HTTP 状态和 errorCode，再读取 data。常见失败边界：

业务组件不要把所有错误都当成登录失效。只有明确的 401 或 token 失效结果才重新进入 授权流程。

前端封装

业务组件应复用统一客户端，不要分别拼接授权头和平台地址：

export async function callModule({
  platformApiBase,
  installId,
  appClientToken,
  logicalService,
  method,
  params = {},
}) {
  const path =
    `${platformApiBase}/workspace-runtime/apps/${encodeURIComponent(installId)}` +
    `/services/${encodeURIComponent(logicalService)}` +
    `/methods/${encodeURIComponent(method)}`;

  const response = await fetch(path, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${appClientToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(params),
  });
  const payload = await response.json();

  if (!response.ok || payload.errorCode !== "0") {
    throw new Error(payload.value || `模块调用失败：HTTP ${response.status}`);
  }
  return payload.data;
}

当 platformApiBase 使用官方公网前缀时，其值为 https://api.baijimu.com/app-gateway/api。不同部署环境应从应用环境配置读取该值， 不能在业务组件中散落生产域名。

调用前提

一次调用只有同时满足以下条件才会执行：

1. appClientToken 有效且属于 URL 中的 installId。
2. 安装记录处于启用状态，并具有对应运行态应用。
3. 当前平台应用版本声明了 URL 中的逻辑接口及对应方法。
4. 该逻辑接口已经在安装态绑定到具体 Runtime businessId。
5. 当前工作区用户拥有调用该模块方法的权限。
6. 目标模块已安装且方法可用。

App Gateway 通过这些检查并完成逻辑接口解析后，才把具体 businessId、method 和 请求参数转换为内部运行时调用。前端不需要了解内部调用信封或模块的后端 HTTP 实现。

旧的 POST /workspace-runtime/apps/{installId}/call 只作为存量迁移入口保留，新应用 不得使用；新应用统一使用本页的逻辑接口路径。