鸿蒙单词打卡案例拆解：Appwrite 六函数与端云验收边界

华为云鸿蒙开发实践中心里的“单词打卡学习：HarmonyOS + Appwrite 端云一体化”案例，解决的是一个很具体的端云协作问题：端侧负责登录、单词卡和答题交互，服务端负责身份校验、取词、记录学习结果和计算进度。本文按案例页公开资料拆解架构、函数分工、数据集合和验收顺序，不把文档步骤写成实际部署结果；文中的实现细节都来自当前案例页，未另行连接自托管 Appwrite 或真机验证。

一、先划清三层边界

端侧是 ArkTS + ArkUI 的四个页面：登录、首页、闪卡、测试。首页展示今日打卡状态、连续天数和 10 个未学单词；闪卡页负责翻转查看释义；测试页用看词选义判断是否掌握；每次答对才推进学习进度。

云侧不是直接让 App 读写数据库，而是让 ArkTS 调用 Appwrite Functions 的执行端点：

POST /v1/functions/{id}/executions

函数在服务端使用 API Key 访问 Appwrite Database，再把结果包在 responseBody 返回。数据路径可以概括为：ArkTS 页面 → 函数执行端点 → 云函数 → NoSQL 集合 → responseBody → 页面。

这里要把三种标识分开看。APPWRITE_HOST 和公开的 Project ID 会进入端侧配置；API Key 只放在本地 .env 或云函数的服务端环境里，不能写进端侧代码，也不能提交仓库。Project ID 是项目定位信息，API Key 才是具备 functions、databases 读写权限的凭据。案例页给出的基础实现使用 execute:["any"]，属于便于演示的公开执行配置，不等于已经具备正式鉴权、限流和 HTTPS；这些在案例中被列为拓展任务。

二、六个函数组成一条完整链路

案例把云侧拆成 6 个函数：

1. register：创建用户记录。
2. login：校验账号并返回登录结果。
3. getDailyWords：取今日待学的 10 个单词。
4. learnWord：记录一次学习或答题结果。
5. getProgress：返回进度和连续打卡数据。
6. db-init：创建 3 个集合、导入 58 个单词和初始管理员。

这 6 个函数可以按职责分成四组：账号、取词、学习记录、初始化。统一响应结构使用 { code: 0, data, msg }，端侧不能只看 HTTP 请求是否成功，还要检查业务 code。例如登录失败、单词已学完或记录写入异常，都可能返回 200 状态下的业务失败；如果端侧把“接口能通”当成“业务成功”，进度条和打卡状态就会和真实数据脱节。

learnWord 是整条链路的关键写入口。连续快速点击、网络重试或页面重复提交，都可能让同一个学习动作被记录多次。案例页没有把这一层展开成完整的幂等设计，只把 db-init 的可重复执行列为拓展项。做二次开发时，需要为“同一用户、同一天、同一单词”的重复提交设边界，并在端侧禁用重复按钮之后，再以服务端记录为准校验。

三、三个集合对应三类事实

案例使用 users_col、words_col、learn_records_col 三个集合：

• users_col 保存用户身份与登录相关信息。
• words_col 保存词库内容，案例页给出的种子数据是 58 个单词。
• learn_records_col 保存学习动作和答题结果，是进度、今日已学单词和连续打卡的计算依据。

这三类数据不能混成一个“学习状态”字段。用户资料会变，词库会更新，学习记录会持续追加；把三者塞进同一个文档，后续做统计、补词或修复单条记录时很难判断原始事实。getProgress 应该根据记录聚合出进度，而不是让端侧自己累加。案例把连续打卡和学习进度列为需要固定样例复核的核心业务规则，截图只能说明界面显示，无法证明云端聚合正确。

文档库还需要单独检查初始化行为。db-init 如果每次部署都重复插入 58 个单词，词库会膨胀；管理员账号的重复创建也会带来冲突。案例把“改成幂等、可重复执行”列为拓展任务，说明基础版本的目标是先把链路跑通，生产化仍需补唯一约束和重复检查。

四、部署最容易卡在运行时和打包

案例页列出的依赖边界很具体：

• node-appwrite@^11.0.0，因为 v14 要求更高的 Node 版本。
• 自托管 Appwrite 需要确认 node-16.0 运行时可用。
• Appwrite 1.9 不会替函数自动安装依赖，必须执行 npm install --omit=dev 后把 node_modules 一起打进 .tar.gz。
• 上传格式是 .tar.gz，不是 .zip。
• API Key 必须包含 functions 和 databases 的读写权限。
• 前端调用返回 401 时，先查函数的 execute 配置和 API Key 权限。

这里最容易出现“命令成功就以为部署完成”的误判。deploy.py 上传成功只说明包和配置已经送达，不能证明函数能处理请求。正确的顺序是：先访问 /v1/health，再查询可用运行时，部署后逐个调用函数，确认都返回 code:0，最后检查集合和 58 个单词是否落库。

另一个细节是 responseBody 的二次解析。Appwrite 执行端点返回的外层是执行结果，业务 JSON 可能被包在 responseBody 里。端侧如果直接把外层响应当业务数据，就会出现“接口成功但页面没有进度”的情况。调试时应先打印完整响应，再固定字段结构，避免在多个页面里各写一套解析逻辑。

五、验收顺序要同时覆盖界面和数据

案例给出的业务验收表可以整理成一条顺序：

1. 登录成功，首页显示今日状态和连续天数。
2. 首页出现 10 个未学单词。
3. 闪卡可以翻转并显示释义。
4. 看词选义答对后，进度和已学单词发生变化。
5. 完成一次学习后，打卡状态和连续天数符合规则。
6. 重启应用，进度和打卡数据仍然保留。
7. 用固定输入复核连续天数的递增、重置和进度计算。

前 4 项可以在界面看到，第 5 到 7 项必须结合函数返回、集合文档和固定样例。重启后数据保留这一项尤其不能只靠刷新页面确认，它同时涉及端侧重新取数、云端记录持久化和 responseBody 解析。如果只截一张进度条截图，不能证明云函数和数据库链路正确。

最后是资源边界。自托管 Appwrite 没有按函数调用的独立费用，但承载它的服务器本身有成本；案例建议实践结束后删除测试函数与集合。做这个案例时，先把 execute:["any"]、HTTP 明文和基础账号密码当作学习环境的临时配置，再按自己的场景补正式鉴权、TLS、限流和数据清理。

这个案例真正可复用的部分不在六个函数本身，而在三层边界：端侧只组织交互，函数执行端点是唯一入口，数据库凭据始终留在服务端。只要这三层没有被混在一起，替换成题库、习惯打卡或课堂练习时，验收顺序仍然适用。