【HarmonyOS Next之旅】DevEco Studio使用指南(二十八) -＞开发云对象

枫叶丹

发布于 2025-05-30 08:49:43

2040

文章被收录于专栏：C++C++

1 -> 开发流程

除去传统的云函数，您还可在端云一体化云侧工程下开发云对象。云对象是一种特殊的云函数，本质是对云函数的一种封装，客户端可通过导入一个云对象来直接使用这个对象的方法，提供在端侧直接调用云侧代码的开发体验。相对普通云函数方式，云对象代码更精简、逻辑更清晰，大多数场景下推荐使用云对象代替传统云函数。开发流程大致如下：

创建云对象：您可直接在DevEco Studio创建云对象。
开发云对象：云对象创建完成后，您便可以开始编写云对象业务代码了。
调试云对象：您可以对云对象进行调试，以测试云对象代码运行是否正确。
部署云对象：完成云对象代码开发与调试后，您可将云对象部署到AGC云端，支持单个部署和批量部署。

说明

一般建议先将云对象调试无误后再部署至云端，但某些业务场景下需要先部署云对象才能进行调试。请根据实际业务需要操作。

2 -> 创建云对象

首先您需要在云侧工程下创建云对象。

1. 右击“cloudfunctions”目录，选择“New > Cloud Function”。

2. 在“Select the Cloud Function Type”栏选择“Cloud Object”，输入云对象名称(如“my-cloud-object”)，点击“OK”。

与云函数名一样，云对象名称长度2-63个字符，仅支持小写英文字母、数字、中划线（-），首字符必须为小写字母，结尾不能为中划线（-）。

“cloudfunctions”目录下生成新建的云对象目录，目录下主要包含如下文件：

云对象配置文件“function-config.json”：包含handler、触发器等信息。
- handler: 云对象的入口模块及云对象导出的类，通过“.”连接。
- functionType：表示函数类型，“0”表示云函数，“1”表示云对象。
- triggers：定义了云对象使用的触发器类型，当前云对象仅支持HTTP触发器。
说明 云对象的配置文件“function-config.json”不建议手动修改，否则将导致云对象部署失败或其它错误。

云对象入口文件“xxx.ts”(如“myCloudObject.ts”)：在此文件中编写云对象代码。

云对象依赖配置文件“package.json”：在此文件中添加依赖。

3 -> 开发云对象

云对象创建完成后，您便可以直接在云对象中编写需要实现的方法。例如，通过云对象实现add与subtract两个方法。

1. 打开云对象入口文件(此处以“myCloudObject.ts”为例)，添加add与subtract方法。

export class MyCloudObject {
    add(num1: number, num2: number) {
        return { result: num1 + num2 };
    }
    subtract(num1: number, num2: number) {
        return { result: num1 - num2 };
    }
}

注意

云对象是无状态性。云对象部署至云侧后，每一次调用都可能是不同的后台节点，因此在云对象上定义类成员变量是无意义的。从一个Method中对一个类成员属性赋值，然后期望从另一个Method去获取类成员属性，这样的做法是错误的。
云对象无需编写构造函数。云侧在收到对云对象的某一个函数的请求时，会调用云对象的默认的无参构造函数。
云对象方法的输入是从JSON反序列化而来，只能是string、number或者Object，不支持Date、Uint8Array等类型。如果在编写云对象代码的过程中需要传递Date或Uint8Array，建议通过定义成number或者数组，在Method内通过显式地调用Date或Uint8Array的构造函数来达到目的。
云对象的方法的输出当前不支持单个number返回。
云对象的方法的输入、输出可以使用自定义对象，不能使用第三方依赖定义的对象或类型。注意，并不是云对象不能有第三方依赖，而是云对象的输入和输出不能有第三方依赖，否则在"Generator Invoke Interface"阶段，将会因为找不到依赖而失败，根本原因是，端侧代码运行在HarmonyOS支持方舟运行时，而云侧运行在Node.js中，二者的依赖管理不同。

2. (可选)如云对象存在依赖关系，可在“package.json”文件的“dependencies”下添加需要的依赖，然后点击右上角“Sync Now”。

说明

右击“package.json”文件，选择“Run 'npm install'”菜单，也可以实现依赖包安装。

所有安装的依赖包都会存储在当前云对象的“node_modules”目录下。

4 -> 调试云对象

云对象开发完成后，您可以对其进行调试，以验证云对象代码运行是否正常。

目前DevEco Studio云对象调试支持本地调用和远程调用，请根据实际场景选择使用：

通过本地调用方式调试云对象：在DevEco Studio调试本地开发好的云对象。支持单个调试和批量调试，并支持Run和Debug两种模式，调试功能丰富，常在云对象开发过程或问题定位过程中使用。
通过远程调用方式调试云对象：先将云对象部署至AGC云端，然后直接在DevEco Studio调用云端云对象。此方式主要用于测试云对象在云端的运行情况、或补充测试因各种因素限制未能在本地调用方式中发现的问题。

4.1 -> 前提条件

请确保已登录。
如果工程有代码逻辑涉及云对象调用云数据库，需在调试前先将整个云工程部署到AGC云端，否则云端将没有相关数据及环境变量。

4.2 -> 通过本地调用方式调试云对象

可在DevEco Studio调试本地开发好的云对象，支持单个调试和批量调试，并支持Run和Debug两种模式。

单个调试和批量调试流程相同，区别仅在于：单个调试是一次只为一个云对象启动本地调试，之后只能调用该云对象；批量调试是一次为“cloudfunctions”目录下所有云对象启动本地调试、然后逐个调用各个云对象。
Run模式和Debug模式的区别在于：Debug模式支持使用断点来追踪云对象的运行情况，Run模式则不支持。

下文以Debug模式下调试单个云对象“my-cloud-object”为例，介绍如何在DevEco Studio调试本地云对象。

1. 右击“my-cloud-object”云对象目录，选择“Debug 'my-cloud-object'”。

说明

如需批量调试多个云对象，右击“cloudfunctions”目录，选择“Debug Cloud Functions”，即可启动该目录下所有云对象。如“cloudfunctions”目录下同时存在云函数和云对象，将会启动所有的云函数和云对象。

2. 在下方通知栏“cloudfunctions”窗口，查看调试日志。如果出现“Cloud Functions loaded successfully”，表示云对象已成功加载到本地运行的HTTP Server中，并生成对应的Function URI。

3. 如需设置断点调试，在函数代码中选定要设置断点的有效代码行，在行号(如下图行3)后单击鼠标左键设置断点(如下图的红点)。

设置断点后，调试能够在断点处中断，并高亮显示该行。

4. 在菜单栏选择“View > Tool Windows > Cloud Functions Requestor”，使用事件模拟器(Cloud Functions Requestor)触发云对象调用。

5. 在弹出的“Cloud Functions Requestor”面板，配置触发事件参数。

Cloud Function：选择需要触发的云对象，此处以云对象“my-cloud-object”为例。
Environment：选择云对象调用环境。此处选择“Local”，表示本地调用。
Method：必填项，输入云对象的方法名称，如“add”。
Event：方法参数列表，JSON array格式，依次代表Method的入参。如add方法接收两个number类型的形参，num1与num2，那么填入“[1, 2]”表示构造num1=1，num2=2的请求。

注意

如果Method的入参中的某一个是数组[]类型，那么Event中将至少包含两层方括号'['，外层的方括号表示参数列表。

6. (可选)点击“Save”，可保存当前触发事件。

点击右上角

可展开保存的触发事件，后续可直接点击“Load”加载事件。对于不需要保存的触发事件，也可以点击“Delete”删除。

7. 点击“Trigger”，将会触发执行云对象的方法，执行结果将展示在“Result”框内。

说明

“Result”框右侧的“Logs”面板仅供通过远程调用方式调试云对象时使用。

8. 点击菜单栏

，可停止调试。

9. 根据调试结果修改云对象代码后，点击

重新以Debug模式启动调试，直至没有问题。

10. 参考步骤5~9，完成云对象其他方法或其他云对象的调试。

4.3 -> 通过远程调用方式调试云对象

可以将云对象部署至AGC云端，然后在DevEco Studio调用云端云对象，以测试云对象在云端的运行情况、或补充测试因各种因素限制未能在本地调试中发现的问题。

1. 参考部署云对象将需要调试的云对象部署至AGC云端。

2. 在菜单栏选择“View > Tool Windows > Cloud Functions Requestor”，使用事件模拟器(Cloud Functions Requestor)触发云对象调用。

3. 在弹出的“Cloud Functions Requestor”面板，配置触发事件参数。

Cloud Function：选择需要触发的云对象，此处依然以“my-cloud-object”为例。
Environment：选择云对象调用环境。此处选择“Remote”，表示远程调用。
Method：输入云对象的方法名称，如“add”。
Event：方法参数列表，JSON array格式，按顺序代表Method的入参，如add方法接收两个number类型的形参，num1与num2，那么填入“[1, 2]”表示构造num1=1，num2=2的请求，如“[1, 2]”。

注意

如果Method的入参中的某一个是数组[]类型，那么Event中将至少包含两层方括号，如'[[1, 2], 3]'，外层的方括号表示参数列表。