鸿蒙端云一体待办清单实战:FunctionGraph+APIG+RDS 全链路搭建与排障经验
今天在鸿蒙开发实践中心把“云同步待办清单”这个案例完整看了一遍:它是一个端云一体的待办清单应用,鸿蒙端用 ArkTS 写界面,数据不放在手机本地,而是通过华为云 FunctionGraph、API 网关 APIG 和云数据库 RDS PostgreSQL 走全链路同步。把案例的架构、搭建步骤和几个容易翻车的点整理下来,方便同样想照着做一遍的开发者少走弯路。
一、这个案例长什么样
从界面上看,它就是一个常见的待办清单:首页可以新增、编辑、删除和标记完成待办事项,支持按优先级排序、按状态筛选和全文搜索,待办列表支持下拉刷新,离线时也能先在本地操作,等网络恢复后再同步。
从架构上看,关键点不在界面,而在分层。鸿蒙端只负责展示和交互,业务逻辑和数据都放在云端。数据模型很简单,只有两张表:users 存用户信息,todos 存待办事项,每条待办包含内容、优先级、状态和创建时间。接口也只有四个:GET /api/tasks 拉取列表,POST /api/tasks 新增,PUT /api/tasks/{id} 更新,DELETE /api/tasks/{id} 删除。接口少,恰好适合第一次做端云一体的人对照着学:先把一条链路跑通,再扩展功能。
二、云端链路是怎么串起来的
数据流是这样的:鸿蒙端发出请求,先到 API 网关 APIG,网关做鉴权和路由,再转发给 FunctionGraph 里的函数,函数用 Node.js 18 运行时连接 RDS PostgreSQL,读写 todos 表,最后把结果原路返回。
这里有三处设计值得注意。第一,函数里不直接暴露数据库地址,数据库放在 VPC 内网,函数通过 VPC 访问,公网只能通过网关进来。第二,网关层统一做鉴权,函数层只关心业务逻辑,分工清楚。第三,待办的同步状态用本地与云端两份数据对照,离线操作先写本地,联网后按时间戳合并,避免直接覆盖。
三、照着案例搭建,一共六步
第一步,拉代码。案例仓库在 GitCode 的 harmony-practice-center 组织下,项目名是 HarmonyOS-APP-todo-list,克隆到本地后用 DevEco Studio 打开,确认 SDK 和设备配置没有报错。
第二步,建数据库。在 RDS 控制台创建 PostgreSQL 实例,建库后执行案例给出的建表语句,创建 users 和 todos 两张表,并给待办的创建时间、状态字段建好索引,列表按时间倒序查询时会快很多。
第三步,部署函数。把云函数代码上传到 FunctionGraph,选择 Node.js 18 运行时,配好数据库连接信息和环境变量。注意函数要绑定 VPC,才能访问内网的 RDS;超时时间不要设得太短,首次连接数据库慢一点也属正常。
第四步,配网关。在 APIG 里创建 API 分组,把四个接口逐一注册上去,分别对应函数的四个操作,开启鉴权。发布后先在网关控制台用测试功能逐个调一遍,确认返回码和数据格式都对,再让端侧调用。
第五步,接 AppGallery Connect。案例里登录和推送相关能力走 AGC,按文档开通对应服务,把配置文件放进工程,端侧初始化一次即可。
第六步,端侧联调。把网关地址和鉴权方式填进端侧的网络层,跑一次完整流程:新增一条待办,刷新列表能看到它,改优先级后重新拉取能同步,删掉后再拉取就消失。四个接口都通,才算链路跑通。
四、五个容易翻车的点
第一个是时区。函数返回的时间是 UTC,端侧直接显示会比北京时间晚八小时,待办的创建时间看起来总是不对。解决办法是统一存 UTC、展示时再转本地时区,不要在两端各存一份本地时间。
第二个是请求体编码。APIG 转发到函数时,请求体可能是 Base64 编码后的,函数里要先判断并解码再解析 JSON,否则会报解析失败。这个问题在网关测试时看不出来,端侧第一次调用时最容易撞上。
第三个是跨域和鉴权。直接用浏览器或调试工具调网关接口时,如果鉴权头没带对,返回的是 401 而不是业务错误,容易误以为是函数挂了。联调时先在网关控制台测通,再在端侧测,出了问题先看网关的调用日志,分清是哪一层报的错。
第四个是冷启动。FunctionGraph 按量计费,长时间没人调用后首次访问会慢一两秒,待办列表第一次加载时能感觉到。测试时不要把它当成接口故障,正式使用可以结合定时触发做保活,或者在端侧加一个加载状态,别让界面一直空白。
第五个是重复提交。网络抖动时点一次新增可能发出两次请求,列表里会出现两条一模一样的待办。稳妥的做法是端侧生成一个唯一请求标识,服务端按标识去重;退一步说,列表按内容加创建时间展示,重复项也更容易被发现。
五、成本和收尾
这个案例的云端资源基本是按量计费,函数按调用次数和运行时间算,网关按调用量算,数据库是主要固定成本。只做学习验证的话,数据库选最小规格即可,跑完后记得把测试用的实例和函数清理掉,避免一直产生费用。
小结
端云一体听起来复杂,拆开看就是四条接口、两张表和一条“端—网关—函数—数据库”的链路。先把这条链路跑通,再去加登录、推送、搜索这些功能,顺序对了,排障也容易:端侧问题看网络请求,网关问题看调用日志,函数问题看运行日志,数据库问题看慢查询,一层一层往下查,很少有查不到原因的故障。
- 点赞
- 收藏
- 关注作者
评论(0)