从零搭建鸿蒙端云一体应用：ArkTS + FunctionGraph + APIG 实战

在 HarmonyOS 应用开发中，典型的企业级场景（员工签到、待办清单、订单管理）几乎都需要同时处理界面渲染、本地状态持久化与多端数据同步。纯端侧方案在离线可用性上占优，但难以支撑团队协作与实时数据一致性；纯云端方案则牺牲了体验的即时性。

端云一体提供了一条折中路径：端侧只保留必要的公开配置与交互逻辑，全部业务校验与数据读写收口到云端，通过 APIG 作为唯一公网入口，配合 FunctionGraph 云函数承载无状态业务逻辑，最终落到 RDS for MySQL 完成数据持久化。

一、整体架构

ArkTS 端侧携带 BASE_URL 与 APIG_HOST 两个公开配置，通过 HTTPS 请求 APIG 专享版；APIG 作为唯一公网入口把流量转发给 FunctionGraph 云函数（Node.js 18.15），云函数再访问 RDS for MySQL 8.0 上的 Todo_DB（三张表）。

这个结构的关键收益是：APIG 是唯一公网暴露面，云函数无需处理鉴权以外的边界逻辑，端侧也不需要直连数据库，任何一次架构调整都收敛在云函数内部完成。

二、端侧实现要点

2.1 配置收敛

端侧代码里只应出现两个常量：BASE_URL 指向你的 API 端点，APIG_HOST 指向 APIG 实例域名。其余全部交给云端，这样换环境时端侧不需要重新打包。

2.2 状态管理与跨页同步

跨页面共享状态使用 @StorageLink 配合 AppStorage 实现。关键陷阱是 AppStorage 的写入异步刷新，跨页面读取可能拿到旧值。需要强一致的场景（例如登录态、当前用户信息），应当以服务端返回为准，在 aboutToAppear 生命周期中主动重新拉取一次，不要信任本地缓存。

2.3 数据持久化

简单 KV 场景用 preferences 即可，但要注意它单例的缓存行为——跨页面读取可能拿到旧值，需要主动 flush。如果数据量稍大或需要复杂查询，直接用 @ohos.file.fs 直读 JSON 更可控。

2.4 端云同步策略

常见的轮询同步模式是在 aboutToAppear 里启动 30 秒的 setInterval 定时器拉取远端，在 aboutToDisappear 里 clearInterval。30 秒是一个平衡点：再短会显著增加云函数调用量与流量成本，再长则影响多端一致性体验。

三、云端实现要点

3.1 FunctionGraph 云函数

Node.js 18.15 运行时，每个云函数保持单一职责：注册登录、任务增删改、优先级与截止日期、同步查询等。云函数之间不共享内存，共享状态一律通过数据库。

3.2 一键部署脚本

手工部署 8 个云函数加 APIG 加数据库表非常繁琐。推荐写 deploy.sh 完成打包上传各云函数、创建 APIG 触发器、发布环境与建表四步，再配套一个 verify_api.sh 自动跑一遍接口验收，把「部署完了」和「部署对了」这两件事区分开。

四、踩坑与经验

1. APIG 路径前缀要统一。所有后端路由统一挂在 /todo 前缀下，端侧请求路径拼接时只需处理一次，避免各处硬编码。

2. 数据库连接不要放在云函数全局。冷启动复用连接是常见优化，但要注意连接超时与 RDS 侧最大连接数的匹配。

3. 端侧不要缓存业务判断结果。所有权限与状态流转校验都放云端，端侧只做展示，否则不同端版本会出现校验口径不一致的问题。

4. 时区要显式处理。签到、截止日期这类业务强烈依赖时区，建议在云端统一存 UTC，端侧按用户时区渲染。

五、总结

端云一体不是把逻辑拆成两半，而是明确划分边界：端负责交互与离线可用，云负责真相与一致性。当这个边界清晰之后，绝大多数 CRUD 型业务应用的开发效率会有明显提升，因为端侧和云端可以并行开发，通过 API 契约对齐即可。

鸿蒙开发实践中心提供了配套的完整案例仓库，包含 deploy.sh、verify_api.sh 与可运行的 ArkTS 工程，可以直接拉下来跑一遍，比从零搭建省不少时间。