「九」HarmonyOS 5 端云一体化实战项目——「M.U.」应用云侧开发云数据库

1 立意背景

M. 代表 “我”，U. 代表 “你”，这是一款用于记录情侣从相识、相知、相恋、见家长、订婚直至结婚等各个阶段美好记忆留存的应用程序。它旨在为情侣们提供一个专属的空间，让他们能够将一路走来的点点滴滴，如初次相遇时的心动瞬间、逐渐了解彼此过程中的深入交流、甜蜜恋爱时期的浪漫时刻、面对家长时的紧张与期待、订婚时的喜悦以及结婚时的神圣幸福等，都以一种独特而有意义的方式记录下来。这款应用程序就像是一个装满珍贵回忆的宝库，随着时间的推移，见证着情侣们爱情旅程的每一个重要阶段，成为他们美好爱情的永恒见证者和守护者。

2 HarmonyOS特性能力接入场景

• 华为账号服务
• 云开发服务
• 预加载

我们团队开发的MU作品是一款用于记录，情侣之间相处时各个阶段照片的归集。提供欢迎页、用户无感知匿名登录，相册管理，用户信息查看等功能。

• 欢迎页快速响应：通过预加载服务，实现可更换欢迎页快速响应功能。

• 用户无感知匿名登录：我们使用首次启动应用程序生成的UUID作为主键，关联用户的unionId和openId，达到用户无论是卸载重装还是冷启动，都能够快速响应用户数据信息。用户基本信息通过云数据库接口存储云端，用户头像通过云存储接口存入云端并更新对应的云数据库数据条目。

• 相册管理：使用云数据库和云存储服务实现相册的封面、标题、描述、内容信息的留存。

3 作品资源

3.1 欢迎页

3.2 时光轴

1）创建相册

2）上传照片

3.3 我的

4 一些理论性的知识要点

4.1 云数据库概述

云数据库是一款端云协同的数据库产品，是AGC云开发（AGC Serverless）关键服务之一，为AGC构建了MBaas（Mobile Backend as a Service，移动后端即服务）能力。云数据库提供了端云数据的协同管理、统一的数据模型和丰富的数据管理API接口等能力，端侧可以编写少量的代码实现AGC云端云数据库的交互。

云数据库采用基于对象模型的数据存储结构，与常见的关系数据库（MySQL，Oracle等）类似，包含数据表、表字段、表字段值、主键，以及表操作权限。唯一不同在于存储区，数据以对象的形式存储在不同的存储区中，每一个对象，都是一条完整的数据记录。存储区是一个独立的数据存储区域，每个存储区拥有完全相同的对象类型定义（也就是数据表），可以根据业务能力为不同用户划分不同的存储区。

云数据库对象类型、存储区以及数据，可以通过AGC控制台定义、创建和管理，也可以通过一站式集成开发工具DevEco Studio定义、创建和管理。云数据库支持多种数据类型，包括字符串、数值、文本、日期等。

云数据库还提供了多重数据安全策略，基于隐私或者敏感数据的全程加密管理能力，加密字段的数据在端侧会被加密，然后再以密文形式发送并存储到云数据库中。同时，提供基于角色的权限管理模型，预置4种角色和3种权限，来保证数据的安全，同时简化了权限管理操作。

4.2 数据库模型概述

云数据库是一款基于对象模型的数据库，采用存储区、对象类型和对象三级结构。每个应用在开通云数据库服务后，都会实例化一个云数据库实例，该实例中可以创建多个对象类型（数据表）、多个存储区。一个对象类型的数据可以对应一个存储区，也可以对应多个存储区。

• 对象类型（ObjectType）：用于定义存储对象的集合，不同的对象类型对应的不同数据结构。每创建一个对象类型，云数据库会在每个存储区实例化一个与之结构相应的对象类型，用于存储对应的数据。
• 存储区（CloudDBZone）：是一个独立的数据存储区域，多个数据存储区相互独立。每个存储区拥有完全相同的对象类型定义，开发者可以根据业务需要自定义存储区中存储的对象。
• 对象（CloudDBZoneObject）：是云数据库基本操作单元，每个对象，都是一条完整的数据记录。

4.2.1 数据类型

云数据库支持多种数据类型，如下表所示：

4.2.2 权限管理

云数据库支持对所有用户的访问进行鉴权，保障应用数据的安全。云侧访问云数据库的用户角色默认位管理员角色，即从AGC控制台、云函数和Server端访问云数据库角色，该角色默认拥有所有权限。端侧为应用程序运行端，端侧的数据操作有严格的安全规则限制，其数据的读写权限根据云侧权限配置表进行控制。

云数据库预置4种角色和3种权限，如下表所示：

5 创建一个存储「欢迎页信息」的对象类型

5.1 开发流程

使用端云一体化云侧工程开发云数据库流程为以下四步：

• 确保云数据库服务开通。
• 通过DevEco Studio工具在云侧工程创建一个用于存储数据条目的对象类型。
• 通过DevEco Studio工具在云侧工程为创建的对象类型添加数据，并配置数据所在存储区。
• 数据成功添加后，通过DevEco Studio工具提供的一键部署能力，将对象类型和数据条目部署到AGC云端。

5.2 确保云数据库服务开通

使用DevEco Studio预置的通用云开发模板创建的端云一体化工程，在工程初始化时，会自动开通云开发（Serverless）服务，若在开发工具主界面通知栏（Notifications）中显示服务开通失败，需按照以下步骤进行开通个。

• 登录AGC控制台，点击“我的项目”。

• 在项目列表中点击需要开通云数据库的项目。

• 在打开的目标项目左侧导航栏选择“云开发（Serverless） > 云数据库”，进入云数据库页面，点击“立即开通”。

• 在开通云数据库时，若尚未设置默认数据处理位置，在弹出的”数据处理位置“窗口进行设置，仔细阅读弹出提示框的文字说明后，在“启用”栏为您的项目勾选一个或多个数据处理位置，并在“设为默认”栏将其中一个设置为默认数据处理位置。

5.3 云侧创建对象类型

• 展开云侧工程目录，右击“clouddb/objecttype”目录，选择“New > Cloud DB Object Type”。

• 在弹出的新建对象类型窗口中输入对象类型名称（下文以“Welcome”为例）后，点击OK按钮完成创建。对象类型命名必须符合以下规范：
  • 只能包含大小写字母，数字，下划线，并且至少包含字母类型。
  • 必须以字母开头，以字母或者数字结尾，不允许以“sqlite_”开头，不允许以下划线结尾。
  • 不允许使用如下系统保留名称：naturalbase_metadata、objecttypeinfohelper、t_data_upgrade_info、t_index_schema、t_nstore_config、t_schema_negotiate_info、t_metadata_schema、t_nstore_permission、t_system_config。

• DevEco Studio工具会根据通用云开发模板内置的对象类型模板新建对象类型JSON文件”Welcome.json“，并会在编码区自动打开该文件。文件结构属性包括对象类型名称（objectTypeName）、对象类型配置字段信息（fields）、对象类型索引信息（indexes）、对象类型角色权限（permissions）。

• 根据业务需要在“fields”中配置对象类型字段信息，字段属性（需要满足的规范参见在“fileds”中为该对象类型配置字段信息）如下表所示。

例如：为“Welcom”对象类型配置如下字段：

"fields": [
    {"fieldName": "id", "fieldType": "Integer", "notNull": true, "belongPrimaryKey": true},
    {"fieldName": "img", "fieldType": "String"},
    {"fieldName": "status", "fieldType": "Short", "defaultValue": 0},
    {"fieldName": "createTime", "fieldType": "Date"}
]

• 根据业务需要在“indexes”中为该对象类型配置索引、索引包含的字段、以及索引包含的字段的排序方式。索引属性（需要满足的规范参见在“indexes”中为该对象类型配置索引）如下表所示。

例如：为“Welcom”对象类型配置如下索引：

"indexes": [
    {
      "indexName": "IND_202412101709",
      "indexList": [
        {
          "fieldName": "id",
          "sortType": "ASC"
        },
        {
          "fieldName": "createTime",
          "sortType": "DESC"
        }
      ]
    }
  ]

• 根据实际业务在“permissions”中设置各角色是否具有该对象类型的Read、Upsert（包含新增和修改）和Delete权限。角色权限属性（需要满足的规范参见在“permissions”中设置各角色对象类型权限）如下表所示。

例如：为“Welcom”对象类型各角色配置权限：

"permissions": [
    {
      "role": "World",
      "rights": [
        "Read"
      ]
    },
    {
      "role": "Authenticated",
      "rights": [
        "Read",
        "Upsert"
      ]
    },
    {
      "role": "Creator",
      "rights": [
        "Read",
        "Upsert",
        "Delete"
      ]
    },
    {
      "role": "Administrator",
      "rights": [
        "Read",
        "Upsert",
        "Delete"
      ]
    }
  ]

5.4 添加数据条目

如果在创建对象类型后，直接一键部署对象类型，会出现以下异常信息。发生这种异常信息是因为未在对象类型内添加数据条目。

• 为对象类型添加数据条目，并配置数据所在的存储区，当前支持手动创建和自动生成数据条目文件，建议使用DevEco Studio工具提供的自动生成数据条目文件。右击对象类型JSON文件，选择“Generate Data Entry”，依旧以对象类型“Welcome”为例，包含“id”、“img”、“status”、“createTime”六个字段。

• 在弹出的“New Cloud DB Data Entry”窗口内，为即将生成的数据条目文件定义名称。此处取默认值“d_Welcome”为例。

• 会根据DevEco Studio工具预置通用云开发模板提供的数据条目模板自动在“clouddb/dataentry”目录下为对象类型“Welcome”生成数据条目文件“d_Welcome”，该文件中已为开发者预置了默认的存储区，所属对象类型名称（“Welcome”），以及对象类型的字段名（“id”、“img”、“status”、“createTime”）。
  • cloudDBZoneName：配置存储区名称，支持自定义，需要开发者记住存储区名称，在使用API访问云数据库时需要使用该值获取对象类型数据。
  • objectTypeName：对象类型名称。
  • objects：配置当前对象类型中所有字段的值，即写入数据。一个对象即为一条数据，可以通过新建一个对象来为字段赋新值，也可以修改某个对象下字段的值。需要注意的是，主键或加密字段的值不支持修改。

{
  "cloudDBZoneName": "default",
  "objectTypeName": "Welcome",
  "objects": [
    {
      "id": 1,
      "img": "string1",
      "status": 0,
      "createTime": 1733835123302
    }
  ]
}

5.5 部署云数据库

完成对象类型创建以及对象类型数据条目创建后，开发者可以通过右击对象类型或者数据条目直接将对象类型和数据条目部署到AGC云端。DevEco Studio工具支持单个对象类型和数据条目部署，也支持批量部署。

• 单个对象类型部署，右击对象类型名称。若批量部署，需要右击“clouddb”目录，选择“Deploy Cloud DB”。

• 可以在开发工具主界面底部状态栏右侧查看云数据库打包与部署进度。

• 等待部署云数据库，直至出现“Deploy successfully”消息，表示云数据库已成功部署。

• 云数据库部署成功后，DevEco Studio工具会自动从AGC云端下载云数据库的schema文件，并将该文件存储在端侧工程“AppScope/resources/rawfile“目录，文件名称为”schema.json“，该文件是端侧API访问云数据库必须引入的配置文件。

5.6 查看云数据库部署情况

• 在DevEco Studio工具主界面顶部菜单栏选择“Tools > Cloud Dev”打开云开发管理面板。

• 如果开发工具尚未登录华为开发者账号，需要先登录授权才可以使用云开发管理面板能力。点击面板中的“CloudDev > Go to console”或者“Serverless > Cloud DB > Go to console”打开AGC控制台。两者区别在于第一种方式需要在AGC控制台页面点击左侧“云数据库”菜单，而第二种方式可以直接定位到AGC控制台云数据库子控制台。

• 分别点击“对象类型”、“存储区”与“数据”页签，查看通过DevEco Studio工具开发并部署的云数据库资源是否已经成功部署到AGC云端。

6 总结

本小节主要对云数据库相关概念做了简单了解，并通过创建「欢迎页信息」对象类型详细讲解了使用一站式集成工具DevEco Studio开发、部署云数据库至AGC云端，同时提供了如何查看部署到AGC云端的云数据库资源。