鸿蒙单词打卡应用：ArkTS 闪卡翻转 + Appwrite 自托管云函数的端云一体化实践

背单词是每天都要重复的小事。把“每天背十个单词、打卡不断档”做成应用，是练习端云一体化的好切口。本文以 HarmonyOS 端侧 ArkTS 与 Appwrite 自托管云侧结合的单词打卡应用为例，讲清楚一条可复现的端云链路。

一、整体架构

端侧是 ArkTS 的四个页面：登录、首页、闪卡、测试；云侧是 Appwrite Functions 的六个函数：register、login、getDailyWords、learnWord、getProgress、db-init；数据层是三个集合：users_col、words_col、learn_records_col。端侧不直接连数据库：ArkTS 页面发起 HTTP 请求调用函数执行端点，函数在服务端用 Server SDK 读写数据库，结果包在 responseBody 字段里返回；API Key 只存在服务端。

二、端侧：流程即状态机

登录页是入口：输入邮箱与密码后调用 login 函数，成功进入首页。首页是“仪表盘”：展示今日打卡状态、连续打卡天数与今日 10 个未学单词。闪卡页是核心交互：卡片正面是单词，点击翻转显示释义；翻转不写库，写库发生在“学会这个词”的确认时。测试页“看词选义”：答对调用 learnWord 写入学习记录，进度重新计算并返回，端侧刷新进度条与打卡状态。

三、云侧：一个函数只做一件事

六个函数各司其职：register 创建用户并写入 users_col；login 校验邮箱与密码；getDailyWords 取当日 10 个未学单词；learnWord 记录一次学习行为，写入 learn_records_col，是打卡状态的唯一写入口；getProgress 汇总学习记录，算出已学数量、总进度与连续打卡天数；db-init 一次性创建三个集合并写入 58 个单词与演示账号。函数入口遵循 Appwrite Functions 规范：ESM 默认导出，node-appwrite v11，execute=[“any”] 公开执行。

四、responseBody 的二次解析

端侧调用函数执行端点后，拿到的不是业务数据本身，而是一层包装：真正的业务结果包在响应 responseBody 字段里，是 JSON 字符串，需二次解析才能拿到 code 与 data。初次联调时若直接取外层字段，会读不到进度与打卡数据。正确做法是先解析外层响应，再对 responseBody 做第二次 JSON.parse，然后按 code 判断业务成功与否。

五、部署与排障

部署流程：每个函数目录执行 npm install --omit=dev 安装依赖，打包成 tar.gz 上传，配置环境变量并设置执行权限。常见报错：Runtime “node-18.0” is not supported，改用 node-16.0；Cannot find package ‘node-appwrite’，依赖未打进 tar.gz；storage_file_type_unsupported，上传了 .zip。

小结

单词打卡应用虽小，端云一体化的关键环节一个不少：端侧四个页面驱动状态流转，云侧六个函数各司其职，函数执行端点是端云之间的唯一入口。同一套做法可以复用到题库应用、习惯打卡等场景，换掉词库与业务规则，骨架不用变。案例源码在 GitCode 的 word-check-in 仓库。