HarmonyOS鸿蒙Next新手也能搞定的端云一体化指南——端侧业务实现

端侧调用云函数

前置条件

已经通过DevEco Studio一站式集成开发环境云侧工程完成云函数开发，同时通过内置的调试工具完成业务逻辑代码验证，并通过一键部署能力将云侧云函数部署到AGC云端（部署到AGC云端的代码可以通过与本地使用调试工具验证代码逻辑方法相同的操作进行验证）。

调用云函数指南

从API 12版本开始，DevEco Studio已经将AGC SDK内置到HarmonyOS SDK中，无需开发者管理依赖关系，可直接在代码文件中引用云开发服务（Cloud Foundation Kit）。

• 调用云函数需要网络权限，在“entry/src/main/module.json5”配置文件中添加网络权限，添加完成后需要点击编辑区右上角“Sync now”同步配置。
• 在代码文件中引入云函数模块及其相关模块。
• （可选）获取函数名称和版本信息。若开发者忘记自定定义的函数名称，可以通过云侧工程“cloudfunctions”目录查看，该方式只能查看云函数名称。若需要云函数版本号，则需要通过DevEco Studio提供的云开发管理面板，点击“Serverless > Cloud Functions > Go to console”进入AGC控制台云函数子控制台。点击目标函数名称（如query-welcome-func）进入到云函数详情页面，然后切换页签为“触发器”，查看“触发URL”的后缀，获取触发器标识，格式为“函数名-版本号”。如下图所示，“query-welcome-func-$latest”，其中“query-welcome-func”为函数名，“$latest”为版本号。
• 通过call()方法调用云函数，需要传递包含必须参数云函数名称，可选参数函数请求体、云函数版本、函数请求超时时间、函数请求加载模式（默认为正常模式NORMAL）构建的云函数调用参数。

cloudFunction.call({
  name: "query-welcome-func"
}).then((data: cloudFunction.FunctionResult) => {
  const result = data.result;
  // 处理调用返回结果
}).catch((error: BusinessError) => {
  // 处理云函数异常时的处理逻辑
})

使用预加载提升欢迎页显示速度

一些理论知识要点

预加载是AGC云开发（AGC Serverless）提供的一项服务，主要用于让开发者的应用在安装状态下提前加载应用首页数据到本地缓存，有效提升应用页面首开速度。预加载服务仅以原始二进制数据进行缓存，应用使用预加载服务时不需要修改原有数据格式，获取缓存后可直接进行解析，并且可以对隐私、敏感数据进行加密。

使用预加载绑定获取「欢迎页信息」云函数

开通预加载服务

使用DevEco Studio一站式集成开发环境通过通用云开发模板创建端云一体化工程后，当前不会自动开通预加载服务，需要开发者手动在 AGC控制台自行开启。登录AGC控制台，点击“我的项目”，在项目列表中点击需要开通预加载服务的目标项目。在项目界面点击左侧菜单栏选择“云开发（Severless） > 预加载”，进入预加载页面，点击“立即开通”。

配置预加载

在目标项目中开通了预加载服务后，并且已经开发并部署云函数，在预加载页面，点击“修改”，在下拉框选择实现预加载的云函数名称，点击“保存”完成云函数配置。

一键生成Client Model

• 展开云侧工程，在云数据库clouddb目录，右击需要调用的对象类型文件（以“Welcome.json”为例），选择“Generate Client Model”打开选择Client Model文件存放目录窗口。
• 在窗口中选择生成Client Model文件存放在端侧的目录，点击OK。
• 开发工具会自动在指定目录下生成对应对象类型的Client Model文件。

调用实现预加载的云函数

调用方法与端侧调用云函数方法一致，都使用 call()方法调用云函数，返回执行业务逻辑代码结果。唯一区别在于预加载需要设置加载模式为预加载模式加载PRELOAD。

export async function PreloadCloudFunction<T>() {
  try {
    const data = await cloudFunction.call({
      name: "query-welcome-func",
      timeout: 3 * 1000,
      loadMode: cloudFunction.LoadMode.PRELOAD
    });
    const result = data.result as ApiResult<T>;
    if (result.code === 0) {
      AppStorage.setOrCreate<T>(CustomConstants.PRELOAD_DATA_KEY, result.data);
    } else {
      AppStorage.setOrCreate<T>(CustomConstants.PRELOAD_DATA_KEY, null);
    }
  } catch (error) {
    const err = error as BusinessError;
    console.error(`cloud function preload cause: ${JSON.stringify(err)}`);
    await NormalCloudFunction();
  }
}

在主模块EntryAbility文件的onWindowStageCreate()方法中调用封装的预加载方法。

onWindowStageCreate(windowStage: window.WindowStage): void {
  // Main window is created, set main page for this ability
  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
  
  windowStage.loadContent('pages/Index', async (err) => {
    if (err.code) {
      hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.');
    await PreloadCloudFunction<Welcome>();
  });
}

在首页使用PersistentStorage对数据进行持久化，使用@StorageProp装饰器定义变量获取预加载缓存数据进行展示，已达到启动应用欢迎页效果。