从一个待办清单看鸿蒙端云一体：APIG + 云函数 + RDS 全链路实录

今天我在华为云开发者成长中心做每日任务时，认真读完了鸿蒙开发实践中心的一个案例——《云同步待办清单：鸿蒙端云一体实战》，并顺手体验了 AI DevSpace，还给案例的代码仓点了 Star。这篇文章把今天真实看到、学到的东西记下来，重点是这个待办清单 App 的端云一体架构，以及新手最容易踩的几个坑。

案例要做的事一句话就能说清：一个 HarmonyOS 待办清单 App，注册登录、新增任务、勾选完成、循环切换优先级、设截止日期、删除任务，全部数据存在云上；两台设备登录同一个账号，一端改了，另一端 30 秒内自动同步一致。听起来就是个普通的待办 App，难在“端云一体”四个字：端侧只负责界面和调用，业务校验和数据读写统一收口在云端。

它的技术栈是这样的：端侧用 ArkTS / ArkUI 写 HarmonyOS 应用，只有登录页和清单页两个页面；云侧是华为云 FunctionGraph 上的 8 个云函数（Node.js 18.15），管注册登录、任务增删改、云同步、建表初始化和诊断；数据库是 RDS for MySQL 8.0，库名 Todo_DB，三张表 users、sessions、tasks；唯一的公网入口是 APIG 专享版，所有请求统一加 /todo 前缀，由 APIG 转发给后端函数，同时负责认证和限流。云函数和数据库挂在同一个 VPC 里，通过内网 3306 端口互访，数据库不暴露公网。端侧调接口只带 APIG 调试域名，BASE_URL 填 APIG 公网入口地址，APIG_HOST 填调试域名。业务接口统一返回 code 为 0 表示成功、1 是业务错误、2 是未登录或会话失效。

案例里我印象最深的是它列出的几个“基线规范”，每一个背后都是真实踩过的坑。第一，APIG 会把请求体 base64 编码，云函数如果不先解码就会报错，办法是统一加一个 parseBody。第二，时区：函数环境是 UTC，数据库驱动也会转 UTC，时间会差 8 小时，要用 dateStrings 加 getBeijingTime 处理。第三，密码用 scrypt 加盐哈希，校验用 timingSafeEqual 防时序泄漏，而且登录时对不存在的邮箱也要执行等代价哈希，避免被枚举出邮箱是否存在。第四，冷启动：VPC 冷启动大约 6 秒，会超过 APIG 的后端超时，首次调用出现 504 是预期现象，端侧内置了 3 次重试，重试几次就能恢复。第五，端侧 ForEach 渲染列表必须给稳定的 key，否则数据变化时界面会错乱。还有一个细节：db-init 初始化建库时，连接池不能预选 database，否则建库语句永远执行不到。

部署方式有两种：让编码智能体按 docs/BUILD.md 自动部署，或者手动按手册一步步在控制台操作。仓库里已经给了端侧全部源码、云侧 8 个云函数和一键部署脚本。费用方面案例也写得很实在：RDS 最小规格、APIG 专享版最小规格都是按需约数元每天，函数按调用量计费，实践用量下通常不足 1 元，用完就删实例、释放弹性 IP、撤销临时 AK/SK。这一点我很认同：做实验之前先看清理清单，比做完再想起来要好。

安全边界这部分案例写得也很坦诚。它明确说这只是教学示范代码，不是生产代码：演示环境默认无认证，APIG 用调试域名，端侧跳过证书名校验，token 永不过期、走 URL 查询参数、明文存在 Preferences 里，登录没有限流和审计。生产要改造的三件事是：token 改走 Authorization Bearer 头并加过期和撤销；APIG 切 APP/IAM 认证，AppSecret 不要放在端侧可分发代码里；登录加限流和审计。已经做到的也不少：SQL 全参数化、写操作按会话归属过滤、DEBUG 日志自动剔除密码和 token、注册不签发孤儿会话。

今天还体验了 AI DevSpace。我选的是体验版：免费试用、秒级启动、全功能，数据不保留，体验时长结束后自动重置，不消耗任何额度。进去后看到工作空间是 1 核 2G，剩余时长 2.0 小时。进入时弹出了“临时 AK/SK 自动配置”的提示，说临时凭据拥有 IAM 全部权限、会同步到所有空间，我按事先的决定没有点同意，直接关掉了弹窗。体验可以以后再做，但把一个全权限凭据交给一个刚打开的空间，性价比太低。顺带给案例的 GitCode 代码仓 harmony-practice-center/todo_list 点了 Star，Star 数从 245 涨到 246。

总结一下今天的收获：第一，端云一体不是“端加云”简单拼接，关键是把“谁说了算”定清楚——入口、校验、数据收口都在云端，端侧越薄越不容易出错；第二，云函数的基线规范（解码、时区、幂等、冷启动重试）值得在写第一行代码之前就定下来；第三，安全上要分清“演示取舍”和“生产要求”，案例里明确列出来的未做项，恰恰是学习时最有价值的部分。明天我打算按案例的快速部署路线，把云侧 8 个函数真正跑起来，再回来写一篇部署实录。