【HarmonyOS Next之旅】DevEco Studio使用指南(二十八) -＞開發云對象

1 -> 開發流程

2 -> 創建云對象

3 -> 開發云對象

4 -> 調試云對象

4.1 -> 前提條件

4.2 -> 通過本地調用方式調試云對象

4.3 -> 通過遠程調用方式調試云對象

5 -> 部署云對象

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]'，外層的方括號表示參數列表。