鸿蒙个人记账本拆解:ECS 自托管 Appwrite 的聚合与安全边界
华为云鸿蒙开发实践中心的个人记账本案例,把“登录、记账、明细、统计”放进一个三 Tab 应用,云侧则在华为云 ECS 上自托管 Appwrite 1.9。这个案例的关键不在页面数量,而在服务端如何收口金额校验、用户归属、分页查询和分类聚合。本文按案例页公开资料拆解四层结构、密码与凭据边界、分页和聚合规则,以及 19 项接口验收;没有把文档步骤写成实际部署结果。
一、四层结构把端侧和数据库隔开
案例把工程分成四层:
- 端侧应用层:
Login.ets处理注册与登录,Home.ets用 Tabs 承载记账、明细和统计;HttpUtil.ets是统一网络入口,Session.ets用 Preferences 保存登录态。 - 接入层:所有业务请求都走
POST {endpoint}/functions/{fnId}/executions,请求头只带公开的项目 ID。 - 云函数层:6 个
node-16.0零依赖 CommonJS 函数,负责注册、登录、新增、列表、删除和统计。 - 数据层:Appwrite 文档库
account_book_db下的users与transactions集合。
端侧不直接调用数据库 API,也不持有 API Key。这个边界很重要:客户端的接口地址、函数 ID 和项目 ID 可以被看到,服务端密钥不能进入 HAP、日志或仓库。案例把密钥放在 harmony_cloud/.env 和服务器环境变量中,端侧只读取公开配置。
Appwrite 的执行端点返回 201,外层是 {status, responseBody},业务结果又在 responseBody 字符串里,需要再次解析成 {code, message, data}。只判断 201 会把“网络成功、业务失败”当成成功;页面必须继续检查业务 code,否则登录失败、越权删除或金额校验错误都可能被渲染成空页面。
二、业务规则不能由页面自己计算
这个记账本把四类校验放在云函数:
- 金额必须大于 0,最多两位小数。
- 分类只能来自固定的 7 类枚举。
- 日期使用
YYYY-MM-DD格式。 - 删除只能操作当前用户自己的记录。
如果端侧一边记账、一边自己累加本月支出,统计页和明细页就会出现两套口径。案例把 get-stats 设为分类占比的唯一数据源:云函数按 user_id 和月份聚合,返回每个分类的金额与占比,端侧只负责 Canvas 环形图和图例渲染。
同一个原则也适用于分页。明细页使用 page 和 pageSize,而不是一次拿走全部账目。Appwrite 单次查询存在上限,案例资料提到默认页大小可能只返回 25 或 100 条;全量聚合时需要在服务端用 offset 循环,明细页则继续“加载更多”。把分页查询和全量聚合混成一个接口,会让统计结果受当前页大小影响。
三、密码和权限边界
案例的注册流程使用 node:crypto 的 scrypt 加盐哈希,存储格式为 scrypt$N$salt$hash;登录时用 timingSafeEqual 做常量时间比对。数据库里没有明文密码,手工插入旧数据也不能绕过统一注册函数,否则登录校验会一直失败。
API Key 要按实际 scope 创建。案例页列出 databases、collections、documents、functions、execution、users 等权限,同时提醒 platforms.*、projects.*、account.*、sessions.read 在自托管 Appwrite 1.9 中可能出现在列表里但不可用。看到全选框就全部勾选,常会在保存时报 scope 非法。
还要区分演示权限和生产权限。案例当前使用 read("any") 与 documentSecurity:false,目的是让学习环境先跑通;这不适合直接上线。真实业务需要收紧到用户或团队范围,云函数执行权限也不应一直保持公开。API Key、数据库权限和端侧登录态是三件不同的事,任何一项放宽都要重新检查越权删除和跨用户查询。
四、部署和验收要按依赖顺序
案例依赖一台已装 Docker、放行 80 端口的 ECS。/v1/health 返回正常只是第一步;建库脚本还要创建属性、等待状态从 processing 变成 available,再建索引。属性和索引是异步资源,顺序颠倒会一直失败。
仓库的一键链路依次执行:
init-database.mjs:幂等创建数据库、集合、属性和索引。deploy-functions.mjs:打包上传 6 个函数,并轮询到ready。verify-api.mjs:只用公开项目 ID 调执行端点,完成 19 项端到端断言。
19 项覆盖注册、重复邮箱、登录、错误密码、三次新增、负数金额、非法分类、分页倒序、云端聚合、空月份、删除和越权拒绝。这个顺序比只看控制台“6 个函数 ready”更有意义:函数存在不代表业务链路完整,真正的验收要同时看到接口结果和集合数据。
端侧还要用与云侧一致的 endpoint 和 projectId 写进 app.config.json,不要写 API Key。编译产物是 entry-default-unsigned.hap,安装到匹配的模拟器或真机后再走注册、登录、记账、明细分页、统计、删除和错误输入。案例提示首次调用 node-16 函数可能有约 1.5 秒冷启动,因此函数超时和端侧读超时都要留足时间。
五、收尾比启动更重要
ECS、弹性公网 IP 和自托管 Appwrite 都会持续占资源。案例要求结束时删除测试数据、项目专属 API Key,不再使用时释放 ECS 与弹性公网 IP。云函数的公开执行、HTTP 明文、演示账号和数据库开放读权限都只适合实验环境。
这个案例可复用的骨架是“端侧只管交互,云函数统一校验和聚合,数据库凭据不下发”。记账、门店流水或打卡统计都可以替换业务字段,但分页、用户归属、聚合口径、幂等初始化和 19 项验收顺序仍然适用。
- 点赞
- 收藏
- 关注作者
评论(0)