鸿蒙端云一体待办清单：APIG统一入口与FunctionGraph幂等写入实践

本文基于华为云鸿蒙开发实践中心“云同步待办清单”案例的公开说明整理分析，讨论一个看似简单的待办清单在端云一体架构下真正需要解决的问题：统一入口、请求解析、密码安全、幂等写入与统计口径。

一、背景与问题

待办清单的端侧功能并不复杂：新增、勾选完成、删除、按分类查看、统计完成率。真正的复杂度在端与云之间。端侧用 ArkTS 开发，云侧由 API 网关（APIG）、8 个 FunctionGraph 云函数和 RDS 数据库组成，端侧不直接访问数据库。

实践中容易出问题的恰恰是这些交界处：网关转发后请求体被编码，云函数拿到的不是原始 JSON；同一条待办被重复提交会产生两条记录；密码若只做简单散列，泄露后难以补救；统计若每次实时全表扫描，数据量稍大就拖慢列表接口。

二、关键分析

1. 统一入口比多入口更易管控

案例把 APIG 作为唯一入口，8 个云函数分别承担注册登录、账号校验、待办列表、新增、更新、删除和两类统计。端侧只与网关对话，云函数只通过网关被调用。这样做的好处是鉴权、限流、日志可以集中在入口层做，坏处是入口一旦配置错误，所有接口同时受影响，部署后必须先验证网关路由再验证业务。

2. 请求体解析是第一道暗坑

APIG 转发时请求体常以 Base64 形式传递，云函数需要先判断 isBase64Encoded，再决定是否解码，然后才做 JSON 解析。这个步骤写在公共解析函数 parseBody 里，所有函数复用。经验是：解析失败不要直接返回 500，而要区分“请求体不是合法 JSON”与“上游编码异常”，否则排障时会在端侧、网关、函数之间来回推诿。

3. 密码与会话要分开处理

案例用 scrypt 对密码做散列存储，登录成功后签发 Token 会话，端侧把登录凭证持久化到本地，之后调用接口携带 Token。scrypt 的计算成本高于普通散列，登录接口会稍慢，但换来的是密码泄露后更难被暴力还原。需要注意的是，Token 的有效期、吊销与多设备登录策略要在设计之初定好，事后补很容易出现旧 Token 仍可用的窗口。

4. 统计口径决定数据一致性

案例的 RDS 库 Todo_DB 有 users、todos、todo_statistics 三张表，其中 todo_statistics 是用户聚合统计的缓存视图，由存储过程加事件调度器每天 00:00 刷新。这是一种用延迟换性能的做法：列表接口不用每次实时聚合，统计查询很快；代价是统计结果最多滞后一天，实时性要求高的场景不能直接用这张表。

三、方案或实现

整体链路如下：

ArkTS 端侧 -> APIG（唯一入口）-> FunctionGraph（8 个云函数）-> RDS Todo_DB

云函数分工为 userAuth、accountCheck、getTodoList、addTodo、updateTodo、deleteTodo、getStatistics、getTodoStatistics；数据库三张表分别存用户、待办与聚合统计。

幂等写入是关键实现点。新增待办使用“存在则更新”的写法，避免网络重试或端侧重复点击产生重复记录：

INSERT INTO todos (id, user_id, title, status)
VALUES (?, ?, ?, ?)
ON DUPLICATE KEY UPDATE title = VALUES(title), status = VALUES(status);

同步策略采用登录凭证本地持久化加 30 秒轮询：端侧每 30 秒调用一次待办列表接口刷新数据。多设备场景下，这个策略能保证最终一致，但实时性上限就是轮询间隔，正在编辑的待办若在另一台设备上被删除，本地在下一次轮询前仍会显示旧数据，删除操作需要对“记录已不存在”做容错。

四、验证

对照案例给出的验收说明逐项复核，核心验收项包括：注册与登录、新增待办、完成与删除、分类筛选、统计展示、30 秒自动刷新。案例标注最后验证于 2026-08-14，运行环境为 HarmonyOS NEXT 5.0.1，验收结论为已验收。

在复核时，值得单独验证的三点是：第一，重复提交同一条待办是否只产生一条记录；第二，退出登录后旧 Token 是否立即失效；第三，跨设备修改后 30 秒内列表是否刷新。任何一点不通过，都说明链路上有未闭环的环节，而不是单一接口的问题。

五、限制与风险

第一，30 秒轮询的成本随用户数线性增长，调用量与函数执行次数都要计入成本模型，不适合高频实时协同场景，实时性要求高时应改用推送或长连接。第二，scrypt 会增加登录接口的计算耗时，函数冷启动会进一步放大首访延迟，登录超时时间的设置要留出余量。第三，APIG 共享版存在限流与配额上限，突发流量下要先确认网关侧的返回码，而不是只看函数日志。第四，统计视图每日刷新，实时统计需求要另设聚合路径，不能直接复用缓存视图。第五，费用方面，案例给出的参考为 FunctionGraph 每月 100 万次免费额度、RDS 约 36.6 元/月、域名约 10 元/个/年、APIG 流量费 0.26 元/百万次起，价格验证日期为 2026-08-14，实际费用以华为云官网实时价格与所选规格为准，部署前应重新核对。第六，API Key、数据库密码与散列参数不得硬编码进端侧代码或提交到代码仓。

六、结论

待办清单的端云一体实践，价值不在界面，而在四处收敛：入口收敛到 APIG 一处，解析收敛到 parseBody 一个公共函数，写入收敛到幂等 SQL 一条语句，统计收敛到明确口径的一张缓存表。把这四处想清楚并逐项验收，端云联调的大部分返工都可以避免；反之，任何一处含糊，都会在多设备同步、重复提交或统计不一致时以线上问题的形式暴露出来。