SDK 初始化

概述

SDK 初始化（init）是 GM Web SDK 中用于建立前后端通信的重要功能。该方法主要用于有后端服务的应用，通过调用 GA 服务的 check_status 接口来检查并启动应用的后端服务。

适用范围

init 方法仅适用于有后端服务的应用。如果您开发的是纯前端应用，可以跳过此步骤，直接使用 SDK 的其他功能。

应用类型说明

有后端服务的应用

对于包含后端服务的应用：

• 必须调用 init 方法
• 每次应用打开时都需要执行初始化
• init 方法会自动检查并启动后端服务
• 确保前后端通信的正常建立

纯前端应用

对于仅包含前端代码的应用：

• 无需调用 init 方法
• 可以直接使用 SDK 提供的其他功能
• 不会影响 SDK 的正常使用
• 适用于静态网页、纯客户端应用等场景

工作原理

当调用 init 方法时，SDK 会执行以下流程：

1. 服务检查：调用 GA 服务的 check_status 接口
2. 状态验证：检查应用后端服务的运行状态
3. 服务启动：如果服务未运行，自动启动后端服务
4. 连接建立：建立前后端通信连接

基本用法

简单初始化

// 适用于有后端服务的应用
window.$gm.init()
  .then(() => {
    console.log('SDK 初始化成功，后端服务已启动');
    // 可以安全地调用需要后端支持的 SDK 方法
  })
  .catch((error) => {
    console.error('SDK 初始化失败:', error);
  });

带配置的初始化

// 带配置参数的初始化
window.$gm.init({
  timeout: 5000,        // 超时时间（毫秒）
  retryCount: 3,        // 重试次数
  autoStart: true       // 自动启动后端服务
})
  .then((result) => {
    console.log('初始化成功:', result);
  })
  .catch((error) => {
    console.error('初始化失败:', error);
  });

使用场景

有后端服务的应用示例

// 在应用入口文件中进行初始化
document.addEventListener('DOMContentLoaded', async () => {
  try {
    // 检查应用是否需要后端服务
    if (hasBackendService()) {
      await window.$gm.init();
      console.log('后端服务初始化完成');
    }
    
    // 继续应用的其他初始化逻辑
    initializeApp();
  } catch (error) {
    console.error('应用初始化失败:', error);
    showErrorMessage('应用启动失败，请重试');
  }
});

function hasBackendService() {
  // 根据应用配置判断是否有后端服务
  return window.APP_CONFIG && window.APP_CONFIG.hasBackend;
}

纯前端应用示例

// 纯前端应用无需调用 init
document.addEventListener('DOMContentLoaded', () => {
  console.log('纯前端应用启动');
  
  // 直接使用 SDK 的其他功能
  window.$gm.openFile({
    path: '/path/to/file'
  });
  
  // 初始化应用
  initializeApp();
});

最佳实践

应用类型检测

// 自动检测应用类型并决定是否需要初始化
async function initializeSDK() {
  // 检查应用配置
  const appConfig = await getAppConfig();
  
  if (appConfig.type === 'fullstack') {
    // 全栈应用，需要初始化后端服务
    await window.$gm.init();
    console.log('全栈应用初始化完成');
  } else if (appConfig.type === 'frontend-only') {
    // 纯前端应用，跳过初始化
    console.log('纯前端应用，跳过后端服务初始化');
  }
}

错误处理

// 完善的错误处理机制
async function safeInitialize() {
  try {
    await window.$gm.init();
    return { success: true, message: '初始化成功' };
  } catch (error) {
    console.error('初始化失败:', error);
    
    // 根据错误类型提供不同的处理方案
    if (error.code === 'SERVICE_NOT_FOUND') {
      return { success: false, message: '后端服务未找到，请检查应用配置' };
    } else if (error.code === 'TIMEOUT') {
      return { success: false, message: '服务启动超时，请重试' };
    } else {
      return { success: false, message: '未知错误，请联系技术支持' };
    }
  }
}

开发建议

1. 明确应用类型：在开发初期就确定应用是否需要后端服务
2. 配置化管理：通过配置文件管理应用类型，便于后续维护
3. 错误处理：为初始化过程添加完善的错误处理机制
4. 用户体验：为用户提供清晰的加载状态和错误提示