HarmonyOS 端云一体案例实测拆解:CodeArts Agent 生成签到 App 的 5 轮流程与 7 个构建坑
HarmonyOS 端云一体案例实测拆解:CodeArts Agent 生成签到 App 的 5 轮流程与 7 个构建坑
一、为什么值得拆这个案例
华为云开发者社区「鸿蒙开发实践中心」里的《使用 Agent 生成鸿蒙端云一体员工签到 App》案例,是少数把 AI 编程从"生成一段代码"推进到"交付一个可验收系统"的完整实践。它用 HarmonyOS ArkTS 做端侧、Node.js + Express + MySQL 做云侧,由 CodeArts Agent 从一句话需求依次产出 PRD、HLD、代码、部署与联调结果。本文按我实际阅读与验证的路径,把它的工程价值与踩坑点整理一遍。
二、五轮对话的真实分工
| 轮次 | 你说的话 | Agent 产出 | 验收物 |
|---|---|---|---|
| 1 | 描述业务:注册、admin 配置、GPS 签到、管理列表 | PRD 需求文档 | 功能清单 + 数据模型 + 接口定义 + 端云时序 |
| 2 | 给出部署形态与端侧 SDK 约束 | HLD 架构设计 | 技术选型表、分层、接口路径、表结构 |
| 3 | 按 PRD + HLD 生成前后端代码 | 端侧 17 个 .ets、云侧 22 个 .js | 可构建工程 |
| 4 | 部署到指定服务器与路径 | Node/MySQL/Nginx/PM2 全链路 | curl /health 返回 code=0 |
| 5 | 构建安装并截图验收 | HAP 构建 + hdc 安装 + 5 项验收 | 5/5 通过 |
关键经验是第 1 轮就把端云接口契约钉死。很多人让 AI 一把梭生成代码,最后返工的根因都在"端侧以为字段叫 A,云侧返回 B"。
三、端云分层怎么划
- 端侧:ArkTS + ArkUI,6 个页面(登录/注册/签到/历史/管理员首页/签到列表)、4 个 Service(Api/Auth/Checkin/Admin)、ConfigCenter 用 preferences 持久化 BaseUrl、AppContext 管 token 与登录态、GeoUtil 实现 Haversine 距离。
- 云侧:Express 三路由组
pjm-auth、pjm-admin、pjm-emp,加上 Services 业务层、DAO 数据层、JWT 中间件、统一错误中间件。 - 数据层:MySQL 8.0 三张表(user / config / checkin),启动时自动建表,连接池复用。
- 部署:Nginx 反代 80→3000,PM2 守护,
cwd必须用__dirname。
签到判定是业务核心:端侧取 GPS 经纬度 → HTTP POST → Nginx 反代 → 云侧读配置 → Haversine 算距离 → 时间判定迟到 → 写记录。注意 Haversine 用的是球面距离近似,城市级签到范围足够,横向几公里的误差可以忽略。
四、7 个最容易卡住的坑
DEVECO_SDK_HOME指向子目录:hvigor 会报 invalid,必须指向 DevEco Studio 下的sdk根目录。spawn java ENOENT:JBR 的jbrin没进 PATH。@kit.ArkDataKit不存在:API 24 起 Kit 更名,改成@kit.ArkData。- 端侧 HTTP 请求无响应:默认禁明文,需补
network_security_config.json,仅调试阶段放开。 install version downgrade:HAP 版本号没升,先 uninstall 或递增 versionCode。- Ubuntu apt 装出的 Node 太旧:apt 源里的 v12 连 npm 都没有,用 NodeSource setup_20.x。
snapshot not found:模拟器不支持该截图命令,改用uitest screenCap。
排查顺序建议固定为:环境与版本 → 配置与权限 → 网络与资源状态 → 云侧日志 → 接口响应 → 端侧日志。这个顺序能把 80% 的"玄学失败"降到具体一层。
五、一个容易被忽略的安全细节
ConfigCenter.ets 里 API_BASE_URL_DEFAULT 必须是空字符串。如果图省事写成内网地址,打包进 HAP 就等于把后端入口公开了。同理,.env 生产模式要 fail closed——缺失或过短的 JWT_SECRET 直接 process.exit(1),别用默认值兜底。
六、从案例到真实项目的迁移边界
这套架构能迁到考勤系统(加请假审批与报表)、配送轨迹(GPS + WebSocket)、IoT 设备管理(MQTT 换 HTTP)。迁移时真正要复用的是三样:端云职责划分方式、JWT 鉴权链路、GPS 距离判定抽象。页面和路由都可以重写,但这三块重写成本最高。
最后提醒一句:案例里 FlexusL 按需约 ¥0.3/小时,实践完记得释放实例。免费实践和计费实践要分清,别让一次学习变成持续扣费。
七、小结
这个案例的价值不在"AI 能写代码",而在它演示了 AI 参与交付的验收闭环:需求有文档、架构有表格、代码有构建、部署有 health 检查、安装有截图 5 项对照。把这套验收物固定下来,AI 生成的东西才敢往生产走。
- 点赞
- 收藏
- 关注作者
评论(0)