端云一体化（一）：端云一体化概述与项目迁移准备

学习目标

搞清楚端云一体化到底是个啥，能解决什么问题
了解鸿蒙端云一体化开发需要哪些技术
把轻食刻项目从单机版改造成端云版，做好前期准备
搭好开发环境，创建好云开发资源

1.1 什么是端云一体化

1.1.1 传统单机应用的问题

以前像轻食刻这种健康管理应用，数据都存在手机本地，用 SQLite 或者鸿蒙的 RDB 数据库：

复制代码

┌─────────────────┐
│   鸿蒙应用端     │
│  ┌───────────┐  │
│  │  ArkUI    │  │
│  └───────────┘  │
│  ┌───────────┐  │
│  │  业务逻辑  │  │
│  └───────────┘  │
│  ┌───────────┐  │
│  │ 本地数据库 │  │  ← SQLite/RDB
│  └───────────┘  │
└─────────────────┘

这种模式用久了就会发现不少问题：

问题	具体表现	后果
数据容易丢	换手机、重装App，数据全没了	用户用了一段时间不敢换机
多设备不同步	手机记录的断食数据，平板上看不到	体验很割裂
功能做不大	没法做排行榜、好友互动	用户玩着玩着就腻了
备份很麻烦	要手动导出JSON文件	操作繁琐，容易忘

1.1.2 端云一体化架构

端云一体化就是鸿蒙提供的一套方案，让手机端和云端服务打通，数据自动同步：

复制代码

┌─────────────────┐         ┌─────────────────────────────┐
│   鸿蒙应用端     │ ←────→ │      AppGallery Connect      │
│  ┌───────────┐  │  HTTPS  │  ┌─────────────────────┐   │
│  │  ArkUI    │  │         │  │    云函数 (Node.js)  │   │
│  └───────────┘  │         │  └─────────────────────┘   │
│  ┌───────────┐  │         │  ┌─────────────────────┐   │
│  │  业务逻辑  │  │         │  │    云数据库 (CloudDB)│   │
│  └───────────┘  │         │  └─────────────────────┘   │
│  ┌───────────┐  │         │  ┌─────────────────────┐   │
│  │ 本地数据库 │  │         │  │    云存储 (Storage)  │   │
│  └───────────┘  │         │  └─────────────────────┘   │
└─────────────────┘         │  ┌─────────────────────┐   │
                            │  │    Push Kit         │   │
                            │  └─────────────────────┘   │
                            └─────────────────────────────┘

这样做的好处很明显：

数据不会丢：云端自动备份，换手机登录账号就能恢复
多设备同步：手机、平板、手表数据实时保持一致
能力更强：推送、认证、AI 这些能力开箱即用，不用自己搭服务器
省钱省心：按量付费，不用自己买服务器、配运维

1.1.3 轻食刻改造后的变化

拿轻食刻来举例，改造后端云一体化后，功能会有这些提升：

功能模块	单机版	端云一体化版
断食记录	只存在手机本地	云端同步，多设备都能看
体重记录	本地简单图表	云端长期趋势分析
饮水打卡	只能看当天的	历史统计+智能提醒
运动记录	自己看自己的	排行榜+好友互动
健康报告	本地生成	云端AI分析+分享
数据备份	手动导出JSON	自动同步，一键恢复

1.2 技术架构详解

1.2.1 端侧技术栈

端侧就是我们写的鸿蒙 App，主要用到这些：

typescript 复制代码

// 端侧核心依赖
import cloud from '@hw-agconnect/cloud';           // AGC云SDK
import { authentication } from '@kit.AccountKit';   // 华为账号认证
import { pushService } from '@kit.PushKit';         // 推送服务
import relationalStore from '@ohos.data.relationalStore'; // 本地数据库

端侧代码结构建议这样组织：

复制代码

entry/src/main/ets/
├── pages/              # UI页面层
├── components/         # 可复用组件
├── services/           # 业务服务层
│   ├── AuthService.ets       # 认证服务
│   ├── SyncService.ets       # 同步服务
│   ├── PushService.ets       # 推送服务
│   └── ...
├── database/           # 数据访问层
│   ├── DatabaseManager.ets   # 数据库管理
│   ├── FastingDao.ets        # 断食数据访问
│   └── ...
└── model/              # 数据模型层
    ├── FastingModels.ets     # 断食相关模型
    └── SyncModels.ets        # 同步相关模型

1.2.2 云侧技术栈

云侧就是跑在华为云上的服务：

复制代码

CloudProgram/
├── cloudfunctions/     # 云函数目录
│   ├── huawei-auth/          # 华为账号认证
│   ├── data-sync-upload/     # 数据上传同步
│   ├── data-sync-download/   # 数据下载同步
│   └── sync-meta/            # 同步元数据
├── clouddb/            # 云数据库对象类型定义
│   └── objecttype/
└── cloud-config.json   # 云开发配置

云函数用的是 Node.js 18+，写 TypeScript，数据库用 AGC 的 CloudDB（文档型数据库）。

1.2.3 数据怎么流转

数据在端侧和云侧之间是这样流转的：

复制代码

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   端侧UI     │ ←→ │  业务Service │ ←→ │   本地DAO    │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌─────────────┐            │
                    │  云函数API   │ ←─────────┘
                    │  (HTTPS)    │    增量同步
                    └──────┬──────┘
                           │
                    ┌──────┴──────┐
                    │   AGC CloudDB │
                    └─────────────┘

同步策略有这几种：

登录时全量同步：一登录就把云端数据和本地数据对比，智能合并
操作时增量同步：添加一条断食记录，马上同步到云端
定时后台同步：每天自动检查一遍，确保两端数据一致
冲突解决：如果手机和云端都改了同一条数据，按时间戳判断谁最新

1.3 开发环境准备

1.3.1 需要准备什么

工具/环境	版本要求	说明
DevEco Studio	5.0.0+	鸿蒙开发IDE
HarmonyOS SDK	API 12+	支持端云一体化API
Node.js	18.x	云函数开发
AGC账号	实名认证	华为开发者账号

1.3.2 创建AGC项目

步骤1：登录AppGallery Connect

打开 https://developer.huawei.com/consumer/cn/service/josp/agc/index.html

步骤2：创建新项目

复制代码

我的项目 → 添加项目 → 输入项目名称"轻食刻端云版" → 创建

步骤3：添加应用

复制代码

项目设置 → 添加应用 → 选择HarmonyOS平台
→ 输入包名 com.xxxx.health
→ 下载 agconnect-services.json

1.3.3 配置DevEco Studio

步骤1：安装CloudDev插件

复制代码

Settings → Plugins → 搜索"CloudDev" → 安装 → 重启IDE

步骤2：登录AGC账号

复制代码

Tools → AGC → Login → 扫码/账号密码登录

步骤3：关联项目

复制代码

项目根目录右键 → AGC → Associate App → 选择创建的AGC项目

步骤4：放置配置文件

把下载的 agconnect-services.json 放到：

复制代码

Application/entry/src/main/resources/rawfile/agconnect-services.json

1.4 项目迁移准备

1.4.1 现有项目分析

轻食刻现在用的是纯本地存储，数据库管理代码大概长这样：

typescript 复制代码

// DatabaseManager.ets - 本地数据库管理
export class DatabaseManager {
  private store: relationalStore.RdbStore | null = null;
  private readonly DATABASE_NAME = 'fastone.db';
  private readonly DATABASE_VERSION = 5;

  init(context: common.UIAbilityContext): Promise<void> {
    const config: relationalStore.StoreConfig = {
      name: this.DATABASE_NAME,
      securityLevel: relationalStore.SecurityLevel.S1,
      encrypt: false
    };
    // 初始化RDB数据库...
  }
}

需要同步到云端的数据表：

表名	用途	是否需要同步
fasting_logs	断食记录	✅ 是
weight_records	体重记录	✅ 是
water_records	饮水记录	✅ 是
exercise_records	运动记录	✅ 是
settings	应用设置	✅ 是
health_reports	健康报告	✅ 是
daily_life_records	生活记录	✅ 是

1.4.2 添加端云依赖

在 Application/entry/oh-package.json5 里加上：

json5 复制代码

{
  "dependencies": {
    "@hw-agconnect/cloud": "^1.0.0",
    "@hw-agconnect/hmcore": "^1.0.0"
  }
}

然后执行安装：

bash 复制代码

cd Application/entry
ohpm install

1.4.3 初始化云SDK

在 EntryAbility.ets 里初始化云SDK：

typescript 复制代码

import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import cloud from '@hw-agconnect/cloud';

export default class EntryAbility extends UIAbility {
  async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
    // 初始化AGC云SDK
    try {
      await cloud.initialize(this.context);
      console.info('AGC Cloud SDK 初始化成功');
    } catch (error) {
      console.error('AGC Cloud SDK 初始化失败:', error);
    }
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err) => {
      if (err) {
        console.error('加载页面失败:', err);
      }
    });
  }
}

1.4.4 创建云开发目录

在项目根目录创建云开发工程：

bash 复制代码

mkdir -p CloudProgram/cloudfunctions
mkdir -p CloudProgram/clouddb/objecttype

创建 CloudProgram/cloud-config.json：

json 复制代码

{
  "cloudfunction": {
    "runtime": "nodejs18",
    "region": "cn-north-4"
  },
  "clouddb": {
    "zoneName": "fastone"
  }
}

1.5 数据模型设计

1.5.1 本地模型和云端模型的区别

本地用的是 RDB 表结构，云端用的是 CloudDB 对象类型，两者要对应起来：

本地模型（RDB表结构）：

typescript 复制代码

// model/FastingModels.ets
export interface FastingRecord {
  id: number;           // 本地自增ID
  startTime: number;    // 开始时间戳
  endTime: number;      // 结束时间戳
  duration: number;     // 持续时长(分钟)
  status: number;       // 状态 0:进行中 1:已完成
  createdAt: number;    // 创建时间
  updatedAt: number;    // 更新时间
}

云端模型（CloudDB对象类型）：

typescript 复制代码

// CloudProgram/clouddb/objecttype/FastingLog.json
{
  "objectTypeName": "FastingLog",
  "fields": [
    { "fieldName": "id", "fieldType": "String", "isPrimaryKey": true },
    { "fieldName": "userId", "fieldType": "String", "notNull": true },
    { "fieldName": "localId", "fieldType": "Integer" },
    { "fieldName": "startTime", "fieldType": "Long", "notNull": true },
    { "fieldName": "endTime", "fieldType": "Long" },
    { "fieldName": "duration", "fieldType": "Integer" },
    { "fieldName": "status", "fieldType": "Integer", "defaultValue": "0" },
    { "fieldName": "createdAt", "fieldType": "DateTime" },
    { "fieldName": "updatedAt", "fieldType": "DateTime" }
  ]
}

1.5.2 模型映射关系

复制代码

┌─────────────────┐         ┌─────────────────┐
│   本地RDB模型    │         │   云端CloudDB   │
├─────────────────┤         ├─────────────────┤
│ id: number      │ ──────→ │ id: string      │  UUID生成
│                 │         │ userId: string  │  关联用户
│ startTime       │ ←─────→ │ startTime       │  字段映射
│ endTime         │ ←─────→ │ endTime         │
│ duration        │ ←─────→ │ duration        │
│ status          │ ←─────→ │ status          │
│ createdAt       │ ←─────→ │ createdAt       │
│ updatedAt       │ ←─────→ │ updatedAt       │
└─────────────────┘         └─────────────────┘

1.5.3 创建云端对象类型

在AGC控制台创建CloudDB对象类型：

复制代码

云数据库 → 对象类型 → 导入→ 选择FastingLog.json → 确定

1.6 本章总结

知识点回顾

端云一体化核心价值：数据不丢、多设备同步、能力更强
技术架构：端侧（ArkTS + ArkUI + RDB）+ 云侧（Cloud Functions + CloudDB）
开发流程：AGC项目创建 → 环境配置 → SDK集成 → 数据建模
迁移策略：保留本地数据库，增加云端同步层

下章预告

第2篇会讲云函数开发与调用，包括：

创建第一个云函数
端侧调用云函数
华为账号认证流程
云函数调试技巧

练习任务

在AGC控制台创建自己的项目并下载配置文件
在DevEco Studio中完成CloudDev插件安装和登录
分析轻食刻项目中还有哪些数据需要同步到云端