鸿蒙端云一体实战：ArkTS + 华为云 Serverless 做一个多端同步待办清单

端云一体最容易翻车的不是写业务，而是那条「App → APIG → 云函数 → RDS」的链路能不能稳定跑通。这篇基于鸿蒙开发实践中心的「云同步待办清单」案例，把真实部署中踩过的坑和关键实现整理成一份可复用的基线。

一、为什么用「端云一体」而不是纯端侧

纯端侧 App 数据只在本机，换设备就丢。要做多端同步，就得有一个云端。这个案例给的骨架很适合照抄：

• 端侧（ArkTS/ArkUI）只带两个公开配置：APIG 公网入口 BASE_URL 和调试域名 APIG_HOST
• 云侧由 8 个 FunctionGraph 云函数（Node.js 18.15）+ APIG 专享版 + RDS for MySQL 8.0 组成
• 数据库凭据只存在云函数环境变量里，端侧永远拿不到

一句话原则：端侧只放公开入口地址，业务校验和数据读写全部收口到云端。

二、云函数基线：四个绕不开的坑

这四条是把「能跑」和「稳定跑」区分开的关键，每一条都来自真实报错。

1. base64 解码（parseBody）

APIG 会把 POST body 做 base64 编码再交给函数。如果直接 JSON.parse(event.body)，就会收到 Unexpected token e in JSON。正确做法是：判断 event.isBase64Encoded 后用 Buffer.from(body,‘base64’).toString(‘utf8’) 解码再 parse。8 个函数都要统一用它，改动时别删。

2. 时区（差 8 小时）

云函数运行环境是 UTC，mysql2 又可能按 UTC 转换 DATETIME，两者叠加就出现「时间差 8 小时」。解法是连接池加 dateStrings 为 true，写入时用 getBeijingTime 显式取北京时间。

3. 幂等写入（ON DUPLICATE KEY UPDATE）

APIG 超时返回 504 不等于函数失败——函数可能还在执行。客户端一重试就会重复写入。所以任务表用客户端 UUID 作主键、ON DUPLICATE KEY UPDATE 做幂等 upsert，弱网重试也只落一次。

4. 统一响应契约

所有函数统一返回 code、message、data 三字段：code 为 0 成功、1 业务错误、2 未登录。端侧据此分流，比解析各种 HTTP 状态码省心得多。

三、三张表撑起账号与任务

• users：scrypt 加盐哈希（salt 与 hash 分开存）
• sessions：会话 token，外键级联删除，承担登录态校验
• tasks：客户端 UUID 主键、deleted 软删除、updated_at 作同步游标

tasks 上建 idx_user_updated 索引（user_id、updated_at），后续要做增量同步可以直接命中。

四、端侧 30 秒轮询与冷启动处理

TodoList 页面每 30 秒调 GET /todo/pull 全量重建列表。这里有个容易被忽略的问题：VPC 函数冷启动挂 ENI 大约 6 秒，超过 APIG 默认 5000ms 后端超时，首次调用会 504。

处理办法：

• HttpUtil 里 MAX_RETRY 设为 3，冷启动 504 自动重试
• 函数超时调到 30s，APIG 后端超时调到 30000ms（删除重建触发器）
• 如果反复 504 后连热实例查询也稳定 5 到 6 秒，说明实例连接池被打坏了，重传代码强制换新实例即可

页面底部放一个请求日志面板，就能直观区分是「冷启动重试后成功」还是「配置错误」。

五、一键部署与自动验收

一条部署脚本完成：打包 8 个函数 → 建 DEDICATEDGATEWAY 触发器 → 发布 API 到 RELEASE → 内部调用 db-init 建表加种子。另一个验收脚本自动跑一遍「登录 → 建任务 → 幂等 → 改 → 读回 → 删」全链路，任一步非 0 就退出。

部署完生成的部署摘要文件里带着 base_url、ingress_ip、apig_host，直接填进端侧配置即可。

六、验收清单

• 双端登录同一账号，30 秒内数据自动一致
• 换另一账号登录，数据互不可见
• 重启 App 登录态保留（token 走 Preferences 持久化）
• 请求日志面板能看到请求记录，冷启动 504 显示重试后成功
• 用 hdc shell hilog 查看日志，无 FATAL、JsError、CppCrash

七、小结

这个案例最值钱的不是待办清单本身，而是那套「唯一公网入口 + 云函数基线规范 + 幂等 upsert + 脚本化部署验收」的骨架。把 base64、时区、幂等、冷启动这四个坑一次性踩平，之后迁移到打卡、记账、工单看板都是同一套模式。

上生产前记得按 README 的「从演示到生产」清单补齐：token 改走 Authorization 头并加过期、开 APIG APP 认证签名、端侧敏感数据别明文存。