SDK 初始化

概述

$gm.init() 用于请求 GMSSH 检查当前微应用的后端服务状态。SDK 会调用 /api/center/check_status，并传入当前应用的名称、版本和通信类型。

适用范围

包含后端服务的微应用，必须在首次业务请求前等待 $gm.init() 成功。纯前端应用使用 message、dialog 等主应用注入能力时，不需要调用该方法。

方法签名

interface GMWebSdk {
  init(): Promise<unknown>;
}

init() 不接收配置参数。Promise 的解析值为 check_status 请求的返回结果；请求失败时，Promise 会被拒绝。

请求内容

SDK 向 /api/center/check_status 发起 POST 请求，数据来源如下：

请求字段	SDK 属性	说明
app_name	$gm.name	当前应用唯一标识
version	$gm.version	当前应用版本
communication_type	$gm.communicationType	当前应用的通信类型

init() 不会在前端创建新的 IPC 连接，也不会注册额外的窗口消息监听器。SDK 在加载时已将主应用注入的能力合并到 window.$gm。

基本用法

async function initializeApp() {
  try {
    await window.$gm.init();
    // 初始化成功后再发起应用服务请求
    startApplication();
  } catch (error) {
    console.error("应用服务初始化失败", error);
    showInitializationError(error);
  }
}

initializeApp();

应用类型

包含后端服务的应用

应用启动时调用一次 init()，并在调用成功后再发起 /api/call/{developer-name}/{app-name}/{method} 请求。

async function startApplication(name) {
  await window.$gm.init();

  return window.$gm.request("/api/call/official/example/hello", {
    method: "post",
    data: {
      version: window.$gm.version,
      transport: window.$gm.communicationType,
      params: {
        lang: window.$gm.lang,
        name,
      },
    },
  });
}

纯前端应用

如果应用不包含后端服务，也不调用应用服务路由，可以不调用 init()。主应用注入的界面能力可直接使用：

window.$gm.message.success("应用已就绪");

window.$gm.chooseFile((path) => {
  console.log("已选择服务器文件", path);
}, "/");

重复调用与重试

SDK 没有缓存初始化 Promise，也没有对重复调用进行去重。每次调用 init() 都会重新请求 /api/center/check_status。

建议在应用入口统一管理初始化状态：

• 首次启动时调用一次。
• 初始化期间禁止重复发起业务请求。
• 失败时显示明确的错误状态和重试入口。
• 用户触发重试时再次调用 init()。

错误处理

init() 会透传 $gm.request 的失败结果。应用不应依赖未公开的固定错误码，而应显示可重试的错误状态，并记录实际返回的错误信息。

async function initializeWithRetry() {
  try {
    await window.$gm.init();
    return true;
  } catch (error) {
    const message = error instanceof Error ? error.message : "初始化失败";
    window.$gm.message.error(message);
    return false;
  }
}