鸿蒙端云一体待办清单实战复盘：云函数基线、轮询同步与一键部署

今天在鸿蒙开发实践中心完整走读了云同步待办清单案例，案例仓库地址是https://gitcode.com/harmony-practice-center/todo_list.git。案例把端云一体拆成一条最短链路：端侧只做界面与请求，业务校验与数据读写全部收口云端。把这条链路的几个关键点复盘下来，能少踩很多坑。

端侧只带两个公开配置

端侧真正需要手工填写的只有两个值：BASE_URL与APIG_HOST。前者填网关公网入口地址，只到主机部分，不含路径；后者填分组调试域名，随每个请求作为请求头参与路由。数据库凭据只存在云函数环境变量里，端侧不直连数据库。配置改错是最常见的联调失败来源，先核对这两个值再排查别处，能省一半时间。

云函数要先立基线规范

云侧八个函数遵循同一套基线。第一，请求体解码：网关会把请求体做 Base64 编码，函数先判断再解码，随后统一解析并返回统一格式的响应。第二，时间：云函数运行在协调世界时，写入时间要统一换算成北京时间，连接池也要开启字符串日期，避免出现八小时偏差。第三，密码只存加盐哈希，登录成功签发六十四位十六进制令牌，后续请求都要校验令牌归属。第四，写入要幂等：客户端生成唯一标识作为主键，入库用存在即更新的写法，网关超时重试也不会重复建账。基线先立好，八个函数才不会各自为政。

三十秒轮询与冷启动

清单页每三十秒请求一次拉取接口，全量重建列表，多端登录同一账号就能在半分钟内看到同步结果。冷启动值得单说：函数挂载虚拟私有云后首次调用可能超过五秒，网关先返回超时，但函数仍在执行，客户端要自动重试两到五次。排查时先确认是冷启动还是配置错误，不要一见超时就改代码。请求日志面板可以区分两种情况，是联调时最实用的排障入口。

一键部署与自动验收

部署脚本把打包八个函数、创建触发器、发布网关、建表初始化串成一步，验收脚本按登录、建任务、幂等写入、改任务、读回、删除、拉取的顺序自动检查，任一步失败即退出。建议先用演练模式打印将要执行的命令，核对无误再正式执行。联调结束及时释放网关与数据库资源，避免持续计费。

从演示到生产的最小改造

演示默认网关无认证、令牌走查询参数且永不过期，只能用于学习。改造清单很短：令牌改走请求头并加过期与撤销，网关启用签名认证，清单加本地缓存实现离线优先，拉取接口支持按更新时间增量同步。先把最小闭环跑通，再逐项加固，比一开始就追求完备更稳。

这条链路的价值不在待办清单本身，而在于可迁移的骨架：端侧只带两个公开配置，云侧用统一契约与幂等写入守住数据，部署与验收全部脚本化。换成签到打卡、记账、团队看板，改的只是表结构与字段，链路不用重写。