HarmonyOS 端云一体待办清单：从架构到同步的实践要点

今天体验了一个基于 HarmonyOS 与华为云 Serverless 的端云一体待办清单案例。这个案例把端侧应用、API 网关、云函数和数据库串成了一条完整链路，适合用来理解端云协同应用的基本设计方法。

一、整体架构

端侧使用 ArkTS 和 ArkUI 构建登录页与任务列表页。所有业务请求统一通过 APIG 进入云端，再由 FunctionGraph 云函数完成身份校验、任务增删改以及数据同步，最终将数据保存到 RDS for MySQL。端侧不直接接触数据库凭据，职责边界更加清晰。

二、统一接口契约

云函数统一返回 code、message 和 data 字段。端侧只需要依据 code 判断成功、业务错误或登录失效，减少了不同接口之间的特殊处理。对于 APIG 传入的请求体，还要注意 base64 解码，避免直接解析导致异常。

三、多端同步设计

案例采用客户端生成任务 UUID、云端幂等写入和定时拉取的方式实现多端同步。客户端 UUID 可以减少弱网重试造成的重复数据；updated_at 字段可以作为后续增量同步的游标；软删除标记则能让删除操作在不同设备之间正确传播。

四、冷启动与超时

云函数接入 VPC 后，首次调用可能需要创建网络连接，因此冷启动时间会明显增加。实践时应合理设置函数超时与 APIG 后端超时，并在端侧加入有限次数的重试。遇到 504 时，应先区分冷启动、网络配置和数据库响应慢，而不是直接认定业务逻辑失败。

五、安全边界

教学环境可以简化认证流程，但生产环境不能照搬。正式上线前至少要补齐可信 HTTPS 域名、接口认证、Token 有效期与撤销机制、登录限流、审计日志和密钥管理。AK、SK、数据库密码等敏感信息不应进入代码仓库或端侧安装包。

总结

这个案例的价值不只在于完成一个待办清单，更重要的是建立端云一体应用的结构化思路：端侧负责交互，网关负责统一入口，云函数负责业务，数据库负责持久化，再通过统一契约、幂等机制和可观测日志保证链路稳定。