云同步待办清单案例阅读笔记：ArkTS 端 + APIG + 云函数 + RDS 的端云一体链路与三个实测坑

本文是鸿蒙开发实践中心案例《云同步待办清单：鸿蒙端云一体实战》的阅读笔记。今天先把案例从头到尾读了一遍，重点记下这条端云链路是怎么搭起来的，以及案例里用真实部署踩出来的几个坑。

一、案例一句话

用 ArkTS 端侧 + 华为云 Serverless 云侧，构建一个可多端同步的待办清单 App：注册登录、任务增删改、优先级与截止日期全部收口云端。云侧是 8 个 FunctionGraph 云函数 + APIG 专享版 + RDS for MySQL 三张表，端侧每 30 秒轮询同步一次。快速部署路线约 60 分钟跑通，完整实践约 150 分钟。

二、端云一体链路：请求到底走了哪些环节

请求链路是：HarmonyOS App（ArkTS）→ APIG 专享版（统一前缀 /todo）→ FunctionGraph 云函数（Node.js 18.15）→ RDS for MySQL（Todo_DB）→ 响应原路返回，30 秒轮询刷新列表。

有三点设计值得记下来：

1. 端侧只带两个公开配置：BASE_URL 填 APIG 公网入口地址（只到 host、不含路径），APIG_HOST 填分组调试域名，由 HttpUtil 作为 Host 头随每个请求携带。数据库凭据只存在云函数环境变量里，端侧不直连数据库。
2. 云侧 8 个函数各司其职：login / register / taskCreate / taskUpdate / taskDelete / pull / db-init / diag。登录用 scrypt 加盐哈希校验并签发 64 位 hex token，会话 token 校验归属后再读写数据。
3. 三张表撑起账号与任务：users / sessions / tasks，tasks 用客户端 UUID 主键 + ON DUPLICATE KEY UPDATE 做幂等 upsert，软删除配合同步游标。

三、实测坑一：APIG 会把 POST body 做 base64 编码

案例高频问题里的第一条：云函数报 Unexpected token e in JSON。原因是 APIG 把 POST body 做了 base64 编码传给函数，函数没解码就直接 JSON.parse，解析到的是 base64 字符串。修复办法是 8 个函数统一补 parseBody()：先判断 event.isBase64Encoded，再 Buffer.from(body,'base64').toString('utf8')。

这个坑的教训是：端云联调出问题时，先确认网关层对请求体做过什么变换，再怀疑业务代码。

四、实测坑二：时间差 8 小时

云函数环境是 UTC，而 mysql2 又可能把 DATETIME 按 UTC 转换，两端叠加就会差 8 小时。案例的做法是：连接池加 dateStrings: true，写入统一用 getBeijingTime()，三张表的时间字段注释均为北京时间。改造成本很小，但如果一开始没统一，后面每处时间显示都要逐个排查。

五、实测坑三：ForEach 的 key 只用 id，勾选后界面“点了没反应”

这是端侧最有意思的一个坑。任务列表用 ForEach 渲染，key 如果只写 t.id，当任务的完成状态或优先级变化时，key 不变，ArkUI 会复用原来的组件实例做原地更新，内部状态和动画残留，界面看起来就像“点了没反应”。

案例的修复是把 key 改成含可变字段的组合：t.id + '|' + t.done + '|' + t.priority + '|' + t.due_date，本地回显用新数组引用（this.tasks = this.tasks.map(...)）。状态一变，key 就变，ArkUI 销毁旧节点、创建新实例，视觉切换干净。我在 AI 开发者空间里就这个问题问了 AI Shell，得到的解释与案例一致：key 应该唯一标识“这条数据当前应该呈现的 UI 状态”，而不只是“这条数据本身”。

六、冷启动 504 不是失败：超时参数要按实测设定

首次调用 504 属于冷启动：VPC 函数冷启动挂 ENI 约 6 秒，超过了 APIG 后端默认超时 5000ms，重试 2–5 次即恢复。案例把函数超时调到 30 秒、APIG 后端超时调到 30000 毫秒，并用临时 diag 函数判定是冷启动还是实例劣化。对应的，客户端也要做重试：案例的 HttpUtil 对冷启动 504 自动重试 3 次，页面底部请求日志面板可以区分“冷启动”与“配置错误”。

和这个坑配套的是幂等设计：APIG 超时返回 504 不等于函数没执行，客户端重试就会重复写入，所以写操作按幂等设计，客户端 UUID 主键 + ON DUPLICATE KEY UPDATE，排查“失败”时先查库确认数据是否已写入。

七、这套骨架能迁移到哪里

案例的场景扩展部分指出，“ArkTS 端 + APIG + FunctionGraph + RDS”骨架可迁移到任何需要账号体系与云端存储的应用：签到打卡（把 tasks 换成打卡记录表，用户 + 日期唯一键）、记账（把任务改为账单）、团队工单（引入负责人维度和状态机，把 30 秒轮询升级为按 updated_at 游标的增量同步）。

但要注意安全边界：这是教学示范，APIG 为 NONE 认证、token 走 URL 查询参数且永不过期、端侧明文存 Preferences。上生产前，案例建议按最小改造清单补齐三件事：token 改用 Authorization 头传输并加过期与撤销、补齐 APIG APP 认证签名、给清单加本地缓存实现离线优先。

八、一句话总结

端云一体最省事的链路是“端侧只放两个公开配置，业务校验与数据读写全部收口云端”；而最容易踩的坑，集中在网关对请求体的变换、云端与本地的时区、以及端侧列表 diff 的 key 设计这三处——案例把每一步的完成标志都写清楚了，照着走就能复现。

阅读来源：鸿蒙开发实践中心案例《云同步待办清单：鸿蒙端云一体实战》（含 README 与 docs/BUILD.md 的部署记录）。