【HarmonyOS Next之旅】DevEco Studio使用指南(二十六) -＞创建端云一体化开发工程

[1 -> 创建HarmonyOS应用工程](#1 -> 创建HarmonyOS应用工程)

[1.1 -> 新建工程](#1.1 -> 新建工程)

[1.1.1 -> 前提条件](#1.1.1 -> 前提条件)

[1.1.2 -> 选择模板](#1.1.2 -> 选择模板)

[1.1.3 -> 配置工程信息](#1.1.3 -> 配置工程信息)

[1.1.4 -> 关联云开发资源](#1.1.4 -> 关联云开发资源)

[1.2 -> 工程初始化配置](#1.2 -> 工程初始化配置)

[1.2.1 -> 自动开通云开发服务](#1.2.1 -> 自动开通云开发服务)

[1.3 -> 端云一体化开发工程目录结构](#1.3 -> 端云一体化开发工程目录结构)

[1.3.1 -> 端开发工程(Application)](#1.3.1 -> 端开发工程(Application))

[1.3.2 -> 云开发工程(CloudProgram)](#1.3.2 -> 云开发工程(CloudProgram))

[2 -> 创建元服务工程](#2 -> 创建元服务工程)

[2.1 -> 新建工程](#2.1 -> 新建工程)

[2.1.1 -> 前提条件](#2.1.1 -> 前提条件)

[2.1.2 -> 选择模板](#2.1.2 -> 选择模板)

[2.1.3 -> 关联云开发资源](#2.1.3 -> 关联云开发资源)

[2.1.4 -> 配置工程信息](#2.1.4 -> 配置工程信息)

[2.2 -> 工程初始化配置](#2.2 -> 工程初始化配置)

[2.2.1 -> 自动开通云开发服务](#2.2.1 -> 自动开通云开发服务)

[2.3 -> 端云一体化开发工程目录结构](#2.3 -> 端云一体化开发工程目录结构)

[2.3.1 -> 端开发工程(Application)](#2.3.1 -> 端开发工程(Application))

[2.3.2 -> 云开发工程(CloudProgram)](#2.3.2 -> 云开发工程(CloudProgram))

[3 -> 历史工程转换为端云一体化开发工程](#3 -> 历史工程转换为端云一体化开发工程)

1 -> 创建HarmonyOS应用工程

1.1 -> 新建工程

1.1.1 -> 前提条件

已实名认证、且注册地为中国境内(不包含中国香港、中国澳门、中国台湾)的华为开发者账号登录DevEco Studio。
请确保华为开发者账号无欠款，账户欠费将导致云存储服务开通失败。

1.1.2 -> 选择模板

1. 选择以下任一种方式，打开工程创建向导界面。

如果当前未打开任何工程，可以在DevEco Studio的欢迎页点击"Create Project"开始创建一个新工程。
如果已经打开了工程，可以在菜单栏选择"File > New > Create Project"来创建一个新工程。

2. 在"Application"页签，选择合适的云开发模板，然后点击"Next"。

说明

当前仅支持通用云开发模板([CloudDev]Empty Ability)。

1.1.3 -> 配置工程信息

1. 在工程配置界面，配置工程的基本信息。

|---------------------|----------------------------------------------------------------------------------------|
| 参数 | 说明 |
| Project name | 工程的名称，由大小写字母、数字和下划线组成。 |
| Bundle name | 软件包名称，需保证唯一，且需与您在AGC创建的HarmonyOS应用的"应用包名"一致。 |
| Save location | 工程文件本地存储路径，由大小写字母、数字和下划线等组成，不能包含中文字符。 |
| Compatible SDK | 兼容的最低API Version。 使用基于Cloud Foundation Kit(云开发服务)的端云一体化开发功能，请选择5.0.0(12)或以上版本。 |
| Module name | 模块名称。 |
| Device type | 该工程模板支持的设备类型，目前仅支持手机设备。 |
| Enable CloudDev | 是否启用云开发。云开发模板默认启用且无法更改。 |

2. 点击"Next"，开始关联云开发资源。

1.1.4 -> 关联云开发资源

为工程关联云开发所需的资源，即将您账号团队在AGC创建的同包名应用关联到当前工程。具体操作如下：

1. (可选)如您尚未登录DevEco Studio，点击"Sign In"，在弹出的账号登录页面，使用已实名认证的华为开发者账号完成登录。

登录成功后，界面将展示账号昵称。

2. 点击"Team"下拉框，选择开发团队。

3. 关联应用

选中团队后，系统根据工程Bundle name在该团队中自动查询AGC上的同包名应用。

如查询到应用，选中该应用，点击"Finish"即可。

如查询到的应用尚未关联任何项目(即为游离应用)，则无法选中。

如果查询到的应用所属项目尚未启用数据处理位置，请点击界面提示内的"AppGallery Connect"设置数据处理位置。

注意

由于云开发目前仅支持中国站点，请确保项目启用的数据处理位置包含中国站点。
无论项目启用的默认数据处理位置为哪个站点，后续开发的云服务资源都将部署在中国站点。

如查询到应用但出现如下提示，表明查询到的应用类型为元服务，与当前工程类型不一致。请修改以确保当前工程与AGC上同包名应用均为HarmonyOS应用类型。

如在当前团队中未查询到同包名应用，请先确认填写的包名是否有误。

如包名有误，点击界面提示中的"go back"返回工程信息配置界面进行修改。
如包名无误，则表明当前团队尚未在AGC控制台创建与当前工程包名相同的应用。您可点击界面提示中的"AppGallery Connect"，前往AGC控制台进行补充创建。

完成以上操作后，DevEco Studio即可获取到同包名应用信息。选中应用后，点击"Finish"。

4. 如所属的团队尚未签署云开发相关协议，点击协议链接仔细阅读协议内容后，勾选同意协议，点击"Finish"。

说明

只有账号持有者和法务角色才有权限签署协议。

5. 进入主开发界面，DevEco Studio执行工程同步操作，端侧工程会自动执行"ohpm install"，云侧工程会自动执行"npm install"，以分别下载端侧和云侧依赖。

说明

若云侧执行"npm install"失败，请排查是否尚未配置npm运行环境。

6. 在主开发界面，可查看刚刚新建的工程。

1.2 -> 工程初始化配置

当您成功创建工程并关联云开发资源后，DevEco Studio会为您的工程自动执行一些初始化配置。

1.2.1 -> 自动开通云开发服务

DevEco Studio为工程关联的项目自动开通云函数、云数据库、云存储等云开发服务，您可在"Notifications"窗口查看服务开通状态。

说明

如服务开通失败，可通过CloudDev云开发管理面板快捷进入AGC控制台进行手动开通。
如云存储服务自动开通与手动开通均失败，可能是账户欠费导致。请您检查账户是否余额不足，补齐全款后再前往AGC控制台进行手动开通。

1.3 -> 端云一体化开发工程目录结构

端云一体化开发工程主要包含端开发工程(Application)与云开发工程(CloudProgram)。

1.3.1 -> 端开发工程(Application)

端开发工程主要用于开发应用端侧的业务代码，通用云开发模板的端开发工程目录结构如下图所示。"Application/cloud_objects"模块用于存放云对象的端侧调用接口类，"src/main/ets/pages"目录下包含了云存储、云数据库和云函数页面。

1.3.2 -> 云开发工程(CloudProgram)

在云开发工程中，您可为您的应用开发云端代码，包括云函数和云数据库服务代码。通用云开发模板的云开发工程目录结构如下图所示。

clouddb：云数据库目录，包含数据条目目录(dataentry)和对象类型目录(objecttype)。

dataentry：用于存放数据条目文件。

该目录下一般会根据您选择的云开发模板预置数据条目示例文件。在通用云开发模板工程中，该目录下会预置名为"d_Post.json"的数据条目示例文件，内含两条示例数据。您可按需使用、修改或删除。

objecttype：用于存放对象类型文件。

该目录下一般会根据您选择的云开发模板预置对象类型示例文件。在通用云开发模板工程中，该目录下会预置名为"Post.json"的对象类型示例文件，内含对象类型"Post"的权限、索引、字段名称和字段值等。您可按需使用、修改或删除。

db-config.json：模块配置文件，主要包含云数据库工程的配置信息，如默认存储区名称、默认数据处理位置。
cloudfunctions：云函数目录，包含各个云函数/云对象子目录。每个子目录下包含了云函数/云对象的配置文件、入口文件、依赖文件等。

该目录下一般会根据您选择的云开发模板预置示例函数。通用云开发模板工程下预置了一个用于生成UUID的示例云对象"id-generator"，您可按需使用、修改或删除。

node_modules：工程同步时执行"npm install"生成，包含"typescript"和"@types/node"公共依赖。
cloud-config.json：云开发工程配置文件，包含应用名称与ID、项目名称与ID、启用的数据处理位置、支持的设备类型等。
package.json：定义了"typescript"和"@types/node"公共依赖。
package-lock.json：工程同步时执行"npm install"生成，记录当前状态下实际安装的各个npm package的具体来源和版本号。

2 -> 创建元服务工程

2.1 -> 新建工程

2.1.1 -> 前提条件

您已使用已实名认证、且注册地为中国境内(不包含中国香港、中国澳门、中国台湾)的华为开发者账号登录DevEco Studio。
请确保您的华为开发者账号无欠款，账户欠费将导致云存储服务开通失败。

2.1.2 -> 选择模板

1. 选择以下任一种方式，打开工程创建向导界面。

如果当前未打开任何工程，可以在DevEco Studio的欢迎页点击"Create Project"开始创建一个新工程。
如果已经打开了工程，可以在菜单栏选择"File > New > Create Project"来创建一个新工程。

2. 点击"Atomic Service"页签，选择合适的云开发模板，然后点击"Next"。

说明

当前仅支持通用云开发模板([CloudDev]Empty Ability)。

2.1.3 -> 关联云开发资源

为工程关联云开发所需的资源，即将您账号团队在AGC创建的元服务关联到待创建工程。具体操作如下：

1. (可选)如您尚未登录DevEco Studio，点击"Sign In"，在弹出的账号登录页面，使用已实名认证的华为开发者账号完成登录。

登录成功后，界面将展示账号昵称。

2. 选择已登录账号下的APP ID，以关联AGC上的元服务。

从APP ID下拉列表中选中所需的APP ID后，界面会展示该元服务在AGC控制台的名称、所属项目、包名与数据处理位置。确认无误后，点击"Next"。

说明

元服务包名为自动生成，格式为固定前缀与appid的组合(com.atomicservice.[appid])。不符合命名规范的包名无法在APP ID下拉列表中展示。

如APP ID为空，表明当前账号下尚未在AGC控制台创建元服务。您可点击"Register App ID"，前往AGC控制台进行补充创建。

创建成功后返回DevEco Studio界面，点击"Refresh"刷新当前APP ID列表，选择新生成的APP ID，点击"Next"即可。

如查询到的元服务尚未关联任何项目，则无法选中。请先将游离元服务添加到AGC项目下。

如果查询到的元服务所属项目尚未启用数据处理位置，请点击界面提示内的"AppGallery Connect"设置数据处理位置。

注意

由于云开发目前仅支持中国站点，请确保项目启用的数据处理位置包含中国站点。
无论项目启用的默认数据处理位置为哪个站点，后续开发的云服务资源都将部署在中国站点。

2.1.4 -> 配置工程信息

1. 进入工程配置界面，配置工程的基本信息。

|---------------------|-------------------------------------------------------------------------------------------|
| 参数 | 说明 |
| Project name | 工程的名称，由大小写字母、数字和下划线组成。 |
| Bundle name | 创建元服务时自动生成，不支持手动修改。 |
| Save location | 工程文件本地存储路径，由大小写字母、数字和下划线等组成，不能包含中文字符。 |
| Compatible SDK | 兼容的最低API Version。 元服务使用基于Cloud Foundation Kit(云开发服务)的端云一体化开发功能，请选择5.0.0(12)或以上版本。 |
| Module name | 模块名称。 |
| Device type | 该工程模板支持的设备类型，目前仅支持手机设备。 |
| Enable CloudDev | 是否启用云开发。云开发模板默认启用且无法更改。 |

2. 点击"Finish"，进入主开发界面，DevEco Studio执行工程同步操作，端侧工程会自动执行"ohpm install"，云侧工程会自动执行"npm install"，以分别下载端侧和云侧依赖。

说明

若云侧执行"npm install"失败，请排查是否尚未配置npm运行环境。

3. 在主开发界面，可查看刚刚新建的工程。

2.2 -> 工程初始化配置