云同步待办清单：鸿蒙端云一体实战学习总结

今天在鸿蒙开发实践中心学习了《云同步待办清单：鸿蒙端云一体实战》案例。它用 HarmonyOS ArkTS 做端侧、华为云 Serverless 做云侧，把注册登录、任务增删改、优先级与截止日期全部收口到云端，是一条可以完整复现的端云一体最短链路。案例预计学习时间约 150 分钟，快速部署路线约 60 分钟就能跑通，全程不用写代码。

一、端云一体架构：唯一公网入口

端侧不直连数据库：数据库放在 VPC 内网、不暴露公网，端侧被视为不可信终端，请求统一经 APIG 网关进入云函数再访问 RDS。请求链路是：HarmonyOS App（ArkTS）→ APIG 专享版（统一前缀斜杠 todo）→ FunctionGraph 云函数（Node 18.15）→ RDS for MySQL（Todo_DB）。端侧只有两个公开配置：BASE_URL 填 APIG 公网入口地址（只到 host，不含路径），APIG_HOST 填分组调试域名，随每个请求作为 Host 头携带。数据库凭据只存在云函数环境变量里，这个“凭据隔离”是全文最值得记住的设计。

二、云侧 8 个云函数与三张表

云侧共有 8 个 FunctionGraph 云函数：login、register、taskCreate、taskUpdate、taskDelete、pull、db-init、diag。login 用 scrypt 加盐哈希校验密码并签发 64 位 hex token；register 只建账号、不签发 token。RDS 里是 users、sessions、tasks 三张表：sessions 承担会话校验，tasks 用客户端 UUID 主键加 ON DUPLICATE KEY UPDATE 实现幂等写入，弱网重试也不会重复建任务；任务还支持软删除与同步游标。

三、容易踩的坑，案例都给了实证

第一，APIG 会把 POST body 做 base64 编码，云函数要先用 parseBody 解码再做 JSON 解析，否则会报 Unexpected token e in JSON。第二，云函数运行在 UTC 时区，连接池要加 dateStrings 参数取字符串日期，写入统一用北京时间转换函数，否则时间会差 8 小时。第三，挂 VPC 的函数冷启动约 6 秒，超过 APIG 后端默认 5 秒超时，首次调用出现 504 属于正常，端侧网络工具类会自动重试 3 次；函数超时建议调到 30 秒，APIG 后端超时调到 30000 毫秒。第四，端侧 ForEach 的 key 不能只写任务 id，要把 done、priority、due_date 等可变字段拼进去，否则勾选或改优先级后界面点了没反应。第五，APIG 超时返回 504 不等于函数没执行，排查“失败”时要先查库确认数据是否已经写入。

四、多端同步与一键部署

TodoList 每 30 秒调用 GET 斜杠 todo 斜杠 pull 全量重建列表，多台设备登录同一账号，30 秒内就能看到一致的任务状态。一键部署脚本完成打包 8 个函数、创建触发器、发布到 RELEASE 环境、用 db-init 建表，端到端验收脚本则做登录、建任务、幂等、改、读回、删、pull 的验收；部署前可以用 dry-run 模式预演。快速体验时只需填好环境变量文件，把 APIG_HOST 与 BASE_URL 填进端侧配置文件，再编译出未签名 HAP 安装到模拟器，用案例提供的演示账号登录即可验证。

五、从演示到生产的改造方向

案例也坦白了教学示范的安全边界：APIG 采用 NONE 认证、token 走 URL 查询参数且永不过期、端侧用 Preferences 明文保存 token。上生产之前，要把 token 迁到 Authorization 头并加上过期与撤销，补齐 APIG APP 认证签名，把 30 秒全量轮询升级为按 updated_at 游标的增量同步，再给清单加上本地缓存实现离线优先。案例的 README 还给出了从演示到生产的最小改造清单，值得照着逐条做一遍。

总结：这个案例的价值不在待办清单本身，而在于它把“端 + 网关 + 云函数 + 数据库”这条链路的每一环都做成了可验证、可排障的闭环：每一步都有完成标志，每一个坑都有真实的复现记录。对想系统走一遍 HarmonyOS 端云开发的开发者来说，先按快速路线跑通全链路，再按完整实践从零写一遍，是性价比很高的学习路径。