HarmonyOS 端云一体案例实测拆解:CodeArts Agent 生成签到 App 的 5 轮流程与 7 个构建坑

举报
yd_253835047 发表于 2026/11/13 00:35:28 2026/11/13
【摘要】 按五轮对话拆解 CodeArts Agent 生成 HarmonyOS 端云签到 App 的流程:端云分层、Haversine 签到判定、JWT 鉴权链路,以及 hvigor 构建、hdc 安装、Node 版本、明文 HTTP 等 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 个最容易卡住的坑

  1. DEVECO_SDK_HOME 指向子目录:hvigor 会报 invalid,必须指向 DevEco Studio 下的 sdk 根目录。
  2. spawn java ENOENT:JBR 的 jbrin 没进 PATH。
  3. @kit.ArkDataKit 不存在:API 24 起 Kit 更名,改成 @kit.ArkData。
  4. 端侧 HTTP 请求无响应:默认禁明文,需补 network_security_config.json,仅调试阶段放开。
  5. install version downgrade:HAP 版本号没升,先 uninstall 或递增 versionCode。
  6. Ubuntu apt 装出的 Node 太旧:apt 源里的 v12 连 npm 都没有,用 NodeSource setup_20.x。
  7. 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 生成的东西才敢往生产走。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。