鸿蒙端云一体开发实践:用 ArkTS 与云函数做一个可同步的待办清单
引言
做过几个纯端侧的鸿蒙小应用之后,我一直在想一个问题:手机上的数据,怎样才能在换设备、清数据之后不丢失,又能在多台设备之间保持一致?待办清单就是一个很好的切入点——它功能简单、数据结构清晰,却能把端云一体开发里最核心的几件事都串起来:端侧界面、本地缓存、云端接口、数据同步和冲突处理。本文就以一个可同步的待办清单为例,记录一次完整的鸿蒙端云一体实践,分享其中的取舍和踩过的坑。
一、为什么选择端云一体
纯端侧应用开发起来最快,数据存在本地,离线也能用。但它的短板也很明显:卸载应用数据就没了,换手机要重新录入,也没法在手机和平板之间同步。端云一体并不是要把所有逻辑都搬到云上,而是让端侧和云侧各做自己擅长的事:端侧负责交互和即时反馈,云侧负责持久化、多端同步和需要集中维护的业务逻辑。
对新手来说,待办清单这个场景刚好卡在合适的难度上。它的实体只有一个:一条待办事项,字段不过是标题、完成状态、创建时间、更新时间。再复杂一点,可以加优先级和截止日期。数据模型简单,就能把精力放在端云协作本身,而不是业务复杂度上。
二、整体架构:端侧、云侧与数据流
这次实践的架构可以概括为三层。端侧是 ArkTS 编写的鸿蒙应用,负责页面渲染、用户输入和本地缓存;云侧是云函数加云数据库,云函数对外提供新增、查询、更新、删除四类接口,云数据库保存待办数据;中间是网络层,端侧通过 HTTPS 调用云函数接口,返回统一格式的 JSON。
数据流向设计成一条线:用户在端侧新建一条待办,先写入本地缓存并立即刷新界面,再把请求发给云函数;云函数写入数据库后返回结果,端侧用返回的记录更新本地缓存里的时间戳和同步状态。启动应用时,先展示本地缓存,再向云端拉取最新数据做合并。这样即使网络不稳定,界面也不会长时间空白,用户体验明显更好。
三、端侧实践:ArkTS 声明式 UI 与本地状态
端侧我用 ArkTS 的声明式 UI 写了两个页面:列表页和编辑页。列表页用 LazyForEach 渲染待办,左滑删除、点击勾选完成,顶部有一个输入框加一个添加按钮,输入后直接生成一条新记录。状态管理上,列表数据放在一个 @State 修饰的数组里,新增和勾选都直接改这个数组,界面随之刷新。
一个容易忽略的细节是本地缓存。只靠内存里的 @State,应用退出后数据就没了。所以我在本地加了一层持久化:每次数据变化后,把列表序列化保存到本地偏好设置里;启动时先读本地数据渲染,再去云端同步。这个做法成本很低,却解决了离线可用和启动白屏两个问题。
示例代码只保留最核心的结构,细节可以根据自己的工程调整:
@Observed
class TodoItem {
id: string = '';
title: string = '';
done: boolean = false;
updatedAt: number = 0;
}
@Component
struct TodoListPage {
@State todos: TodoItem[] = [];
build() {
Column() {
List() {
LazyForEach(this.todos, (item: TodoItem) => {
ListItem() {
TodoRow({ item: item })
}
})
}
}
}
}
四、云侧实践:云函数与数据接口
云侧我只写了一个云函数,用请求里的动作字段区分操作:新增、列表、更新、删除。每个接口都只做一件事,返回结构保持一致,包含状态码、数据和提示信息。这样端侧解析起来很轻松,出问题也容易定位。
以新增接口为例,云函数收到请求后先做基础校验:标题不能为空、长度不超过合理上限;校验通过后写入数据库,写入时由云侧生成 id 和时间戳,再把完整记录返回给端侧。把时间戳和 id 的生成放在云侧,是一个有意的设计——多端同时新建时,由云侧统一编号,可以减少端侧生成重复 id 的风险。
云函数里还要注意错误处理。数据库写入失败、参数缺失、网络异常,都应该返回明确的错误信息,而不是让调用方去猜。端侧收到错误后,把对应记录标记为未同步,下次联网时再重试,而不是直接丢掉用户的数据。
五、端云联调:从本地调试到多端同步
联调建议分三步走。第一步先在本地跑通端侧界面,用本地假数据验证增删改查的交互,确认界面和状态都没有问题。第二步把云函数单独调通,用工具直接调用接口,确认新增、查询、更新、删除都能正常返回。第三步再把端侧和云侧接起来,重点验证三件事:新建后云端有没有落库、启动时能不能拉到最新数据、离线新建后联网能不能补同步。
同步策略上,我采用的是“更新时间优先”:每条记录都有 updatedAt,拉取时以云端数据为准,但本地有未同步的修改时,先把本地修改推送上去,再拉取合并。待办清单这个场景冲突很少,更新时间优先已经够用;如果业务里多人同时改同一条记录,就需要再引入版本号或操作日志,那是另一个层面的设计了。
六、常见问题与排障思路
实践中遇到最多的是三类问题。第一类是网络请求失败,先看域名和证书配置,再看请求头和参数格式,最后看云函数日志,大部分问题都能在这三个环节定位。第二类是数据不同步,通常是本地缓存和云端数据没有按更新时间合并,或者端侧用了旧的 id 覆盖了新记录,解决办法是把同步逻辑写成独立的函数,单独测试合并规则。第三类是界面不刷新,多数是因为状态修饰符用错了,数组里对象属性的变化没有触发刷新,把数据类标记为可观察对象就能解决。
排障时还有一个习惯值得养成:端侧和云侧都记日志,关键节点打印请求参数和返回结果。同步问题往往不是某一端单独的错,而是两端对同一条数据的理解不一致,日志是最直接的证据。
七、成本与安全要点
这类小应用的云侧成本一般不高,但也要有意识地控制。云函数按调用次数计费,列表接口可以做分页,避免一次拉取全部历史数据;不用的测试数据定期清理;开发阶段用测试环境,确认稳定后再切到正式环境。
安全方面,至少要做到三点:接口做基础的身份校验,不要让任何人都能读写别人的待办;不要把密钥和敏感配置写进端侧代码;用户输入要做长度和内容校验,云侧再校验一次,前后端双重校验比只靠一端可靠得多。
小结
回顾这次实践,最大的收获不是做出了一个待办清单,而是走通了一条可复用的端云一体路线:端侧先行验证交互,云侧接口保持简单,同步用更新时间兜底,联调分步验证,日志贯穿两端。这条路线同样适用于打卡记录、读书笔记、轻量记账等场景,换一个数据模型就能复用。
如果你也在学习鸿蒙开发,不妨从待办清单这样的小应用开始,先让端云跑通,再慢慢加功能。把一次完整的端云联调经验沉淀下来,比同时开十个半途而废的项目更有价值。
- 点赞
- 收藏
- 关注作者
评论(0)