尧图网站建设 
简介在移动应用开发领域云原生与端侧协同已成为主流趋势。HarmonyOS NEXT作为华为自研操作系统采用ArkTS语言与ArkUI声明式UI为开发者提供了高效的开发体验。借助AGCApp Gallery Connect平台开发者可以快速集成云数据库、云函数、认证服务等后端能力无需自建服务器即可构建完整应用闭环。以个人记账类应用为例这类典型业务场景涵盖列表、表单、图表统计与预算管理能充分检验ArkTS的数据绑定、状态管理与组件化能力。通过拆解鸿蒙记账应用的工程结构、核心模块实现、真机调试与签名打包流程可以系统地掌握从开发到上架的完整路径为开发鸿蒙应用、参赛或毕设提供实用参考。 收到这个HarmonyOS 鸿蒙小应用.zip压缩包的时候我下意识看了一眼大小和文件结构第一反应是这不是一个随手写两页界面的Demo而是一个把鸿蒙端、云后端、用户体系全串起来的完整闭环。压缩包里是一个典型的前后端分离记账应用端侧用ArkTS ArkUI开发用户认证、账单记录、分类管理、统计分析、预算管理五个模块齐全后端跑在AGCAppGallery Connect上。说实话这类“小应用”反而是现阶段鸿蒙生态里最有参考价值的样例因为它把一条从开发到上线的实用路径全部走通了。这篇内容适合两类人一是刚接触HarmonyOS NEXT、想找一个完整项目来拆解的开发者二是在校学生或独立开发者准备用鸿蒙应用参加比赛、做毕设或上线商店需要一个能快速落地的参考模板。我会把这个压缩包里能拆出来的技术决策、实现细节和坑全部讲透顺便把开发环境、签名打包、真机调试这些绕不开的流程一起梳理干净。1. 先看懂这个“小应用”项目定位与设计思路拆解1.1 解开压缩包这里面到底装了什么先别急着双击运行。压缩包里的工程结构通常分这么几块entry模块是主入口模块负责应用启动、页面路由和UI展示common或shared目录放公共工具类和常量后端部分一般不会把源代码放进压缩包而是把云函数、云数据库集合结构、认证服务配置以文档或导出文件的形式附上。个人记账应用的功能划分很清晰对应关系大致是这样模块端侧职责云端职责用户认证登录页、登录状态管理AGC Auth 认证服务账单记录新增/编辑/删除账单页面云数据库账单集合分类管理分类选择器、图标映射云数据库分类集合统计分析图表展示、汇总卡片云函数聚合计算预算管理预算设置页、进度展示云数据库预算集合这里有个值得注意的细节HarmonyOS NEXT 5.0及以上版本的应用端侧只能使用ArkTS语言开发这意味着整个前端代码都是基于Stage模型和声明式UI写出来的。你打开工程后如果看到大量Entry、Component、State装饰器不用慌这些都是ArkUI的常规语法跟传统Android的XML布局思路完全不同。1.2 为什么选“个人记账”这个场景记账应用能成为鸿蒙生态里的“样板房”项目不是偶然的。它的数据模型足够简单不需要复杂的网络通信和实时同步但麻雀虽小五脏俱全有列表页、表单页、图表统计页、设置页基本覆盖了移动应用最常见的页面类型。对于学习鸿蒙开发的人来说这比单纯做一个“Hello World”或者一个单页工具类应用有价值得多。更深一层看记账应用涉及的核心技术点都很“通用”。列表渲染和状态管理对应了日常业务开发最频繁的操作表单输入和校验考验的是事件处理和数据绑定统计图表需要处理Canvas绘制或第三方库集成预算管理则涉及本地计算与云端数据的配合。把这套逻辑跑通了换成“笔记应用”“任务管理应用”也一样能套用。这个项目选择后端用AGC而不是自己搭服务器也是个很实际的决定——个人开发者或学生团队根本没精力去维护一台云主机更不用说搞域名备案和HTTPS证书了。AGC云数据库、云函数、认证服务这些能力能让你把90%的后端工作外包出去端侧只需要关注UI和业务交互。1.3 技术选型HarmonyOS NEXT 5.0 AGC后端能省掉多少事HarmonyOS NEXT的版本策略和Android、iOS不一样每个大版本之间的API变化明显5.0及以上版本开始强制使用ArkTS不再支持Java和兼容Android应用的运行。所以开发前第一件事就是确认你的DevEco Studio版本对得上SDK版本否则工程打开后会提示SDK不匹配。AGC后端提供的几个核心服务在记账场景里是这样落地的AGC Auth支持华为账号、手机号、邮箱等多种认证方式不用自己维护用户表和密码加密逻辑。云数据库直接创建集合类似MongoDB的collection客户端SDK可以像操作本地数据库一样读写云端数据。云函数写JavaScript或TypeScript函数跑在华为云上适合做统计汇总、预算月度重置这类不方便在端侧完成的计算。云存储如果将来要加头像上传、账单附件能直接存文件。这套组合拳的好处在于整个项目不需要一台自己的服务器不需要处理CORS跨域问题甚至连HTTPS证书都不用操心因为AGC的接口域名和证书都是华为统一管理的。这几乎是鸿蒙应用开发里起步成本最低的路径。2. 开发环境搭建与工程结构设计2.1 DevEco Studio版本、API Level和模拟器选择打开压缩包之前先把开发环境搞定。我用的是DevEco Studio 5.x版本配合HarmonyOS SDK API 12及以上编译目标选的是HarmonyOS NEXT 5.0.0。如果你工程里的build-profile.json5文件里写的compatibleSdkVersion比我高就需要去升级DevEco Studio否则编译会直接报错。关于调试设备我的经验是真机优先。鸿蒙模拟器在API 10之后的版本虽然在不断进步但有些硬件能力比如摄像头、传感器、指纹还是模拟不全而AGC登录、推送这类服务在模拟器上也容易出现环境差异。你有一台HarmonyOS NEXT手机的话用USB连上电脑DevEco Studio会自动识别设备点一下Run就能跑到真机上。这里插一个关键词解释方便新手听明白hdc是鸿蒙开发者命令行工具类似于Android的adb。你在命令行里敲hdc list targets能看到已连接的设备列表hdc install xxx.hap可以直接安装应用包hdc shell可以进入设备的Shell环境。很多热词里提到的“鸿蒙hdc安装”“hdc shell怎么开”其实都是通过DevEco Studio自带的终端工具就能解决的。2.2 三层架构在项目里怎么落地鸿蒙官方推荐的“应用程序级三层架构”一般分为UI层、能力层、公共层。这个记账项目在工程结构上完全可以照搬这套思路UI层放在entry/src/main/ets/pages和entry/src/main/ets/views下所有页面和自定义组件都归这里。页面负责布局、交互事件、状态展示不直接写业务逻辑。能力层放在entry/src/main/ets/model和entry/src/main/ets/service下Model层定义账单、分类、预算这些数据模型Service层封装调用AGC云数据库、云函数的方法。页面要数据就调Service层接口页面不关心数据是从哪来的。公共层放在entry/src/main/ets/common下包含工具函数、常量定义、通用样式、日期格式化方法等。这么分层的直接好处是当你把云数据库从AGC换成本地首选项存储只需要改Service层的实现页面代码一行都不用动。我在实际开发里见过很多初学者把所有代码堆在aboutToAppear()生命周期里一个页面几百行后期维护非常痛苦。2.3 应用沙箱和hap包先搞清楚东西装在哪儿HarmonyOS的沙箱机制比Android更严格。应用安装后所有的私有数据都存在一个沙箱目录里应用A无法访问应用B的数据文件即使通过文件管理器也看不到其他应用的内部目录。对于记账应用来说这意味着你缓存的用户头像、本地备份文件默认都是安全的。你打出来的entry-default-signed.hap包就是鸿蒙应用的安装包格式。通过DevEco Studio Run运行的时候IDE自动帮你完成签名和安装如果要把包发给别人对方可以通过hdc install安装。这里有一个小坑不同调试证书签名的hap包不能覆盖安装如果遇到“安装失败”提示先检查签名是否一致卸载重装通常能解决但会清掉本地数据。3. 五大核心模块的实现要点3.1 用户认证接AGC Auth别自己写session记账应用的数据是强隐私的每个人只能看到自己的账单所以用户认证是全部功能的前提。压缩包里如果用了AGC Auth集成路径一般是在AGC控制台开通认证服务配置支持的认证方式比如手机号、华为账号然后在工程里引入hw-agconnect/auth-component依赖调用登录接口后拿到用户唯一标识uid。很多Web转鸿蒙的开发者会习惯性地想自己设计token和session我的建议是别折腾。AGC Auth已经帮你处理好了token生命周期、自动刷新、用户信息缓存你只要在Service层写一个getCurrentUid()方法拿到这个ID之后所有的账单记录都带上这个字段作为筛选条件天然就能实现“用户A看不到用户B的账单”的隔离效果。登录页面的UI在ArkUI里写也不复杂一个手机号输入框、一个验证码输入框、一个登录按钮就够了。验证码发送走AGC的短信服务几分钟就能配好。唯一要留意的是AGC Auth在API 12之后的SDK包名和方法签名有过调整如果编译报找不到AGConnectAuth类检查一下依赖版本是否和你的SDK匹配。3.2 账单记录数据模型和状态管理是关键账单数据模型建议这样设计Bill { id: string // 账单ID云数据库自动生成 uid: string // 所属用户标识 amount: number // 金额单位分或元注意精度 categoryId: string // 分类ID remark: string // 备注 type: number // 0-支出 1-收入 createTime: number // 创建时间戳毫秒 }金额字段是我特别想提醒的。浮点数在计算机里存在精度问题0.1 0.2 不等于 0.3这在记账应用里会酿成大祸。推荐用法是金额以“分”为单位存整数展示的时候再除以100格式化这样既避免精度问题也方便统计聚合。新增账单页面在ArkUI里用State装饰器管理表单状态用户输入金额、选择分类、填写备注点击保存后调用Service层把数据写入云数据库。列表页用ListForEach渲染下拉刷新用PullToRefreshV2这类第三方库上拉加载更多通过监听滚动位置的onReachEnd事件触发。状态管理方面如果预算页和统计页需要实时反映账单变化建议在页面间用路由参数传递刷新标记或者用AppStorage存储一个全局的“数据版本号”。每当你增删改账单就把版本号加1其他页面监听版本号变化后重新拉取数据。这个方案比用Watch监听复杂对象靠谱得多。3.3 分类管理图标映射和颜色匹配的细节分类管理模块看起来简单但实际做起来有不少细节。首先是分类数据从哪来我建议做成“云端预置 本地缓存”的结构首次启动时从云数据库拉取默认分类列表餐饮、交通、购物、住房、娱乐、医疗等用户也可以自定义分类。云数据库里每条分类记录包含name、icon、color、sortOrder字段这样客户端拿到数据后能直接渲染。图标映射是容易踩坑的地方。鸿蒙的资源文件放在resources/base/media目录下如果你打算分类图标用本地资源那么云端存的应该是资源名称字符串比如ic_food前端通过$r(app.media. iconName)动态加载。这里有个限制动态拼接资源名的写法在编译期可能无法校验如果资源不存在会直接崩掉。稳妥做法是建一个图标名到资源对象的映射表查询不到时给一个默认图标。颜色匹配也有讲究。支出分类用偏暖色红橙收入分类用偏冷色绿蓝统计图表里同色系会比较好区分。分类选择器如果做成宫格形式用Grid组件渲染选中态通过State selectedCategoryId控制边框高亮。整体交互要做到用户新增账单时点击分类弹出一个半屏的底部弹窗选完自动返回并填充分类名。3.4 统计分析图表是表面聚合逻辑才是核心统计分析模块是这个项目里有技术含金量的部分。月度账单汇总页需要展示本月总支出、总收入、结余分类占比饼图以及近6个月的支出趋势折线图。这些数据如果全部拉明细在端侧算数据量大了之后性能会很差正确做法是让云函数做聚合。// 云函数伪代码按月份和分类统计支出 export async function aggregateMonthlyExpense(uid: string, year: number, month: number) { const db cloud.database(); const start new Date(year, month - 1, 1).getTime(); const end new Date(year, month, 1).getTime(); const bills await db.collection(bills) .where({ uid, type: 0, createTime: db.command.gte(start).and(db.command.lt(end)) }) .get(); const mapping {}; bills.data.forEach(bill { if (!mapping[bill.categoryId]) { mapping[bill.categoryId] 0; } mapping[bill.categoryId] bill.amount; }); return mapping; }云函数把聚合结果以轻量的JSON对象返回给端侧端侧拿到数据后直接驱动图表组件。图表实现有两种选择一是用Svg组件配合Path元素手动画饼图和折线图优点是零依赖、包体小缺点是代码量大二是第三方图表库省事但引入之前要先确认它支持HarmonyOS NEXT的ArkTS环境不能直接用React/Vue的组件库。我个人的建议是饼图用Svg手绘就行原理很简单Path元素里d属性画圆弧根据每个分类的占比算出弧度的起始角和终止角。折线图稍复杂一些但核心也就是计算坐标点然后连线。手绘的好处是你对每一个像素都有掌控力样式调整也不用受限于组件库的API。3.5 预算管理预警逻辑怎么设计才不烦人预算模块的逻辑闭环是用户给某个分类设置月度预算金额然后实时计算该分类当月已支出金额展示剩余额度和进度条。如果支出超过预算的80%进度条变黄提示“快超了”超过100%变红提示“已超支”。这里的核心是“预算计算”的时机不需要每次都去云数据库拉全量账单。我建议在云数据库里加一个budgets集合每次用户新增/编辑/删除账单时在Service层同步调用云函数更新对应分类的usedAmount字段。虽然牺牲了一点实时性但换取的是首页加载时只需要查一条预算记录就能展示进度条不用做JOIN查询或二次聚合。预警逻辑放在端侧做更灵活。因为推送通知的权限配置相对繁琐我在项目里优先选择应用内提示进入首页时如果发现某分类预算使用率超过100%首页顶部弹出一条警示卡片展示“餐饮分类本月已超出预算”。如果后续要接系统通知再通过AGC推送服务补充。这里设计时要注意避免“狼来了”——用户每天被超支提醒轰炸很快就会把通知权限关掉所以预警阈值要给用户一个设置入口别把80%和100%写死。4. 真机调试、打包安装与常见坑4.1 从热词里扒出来的几个高频问题在整理这个项目资料的过程中我注意到网上搜鸿蒙开发相关问题的人非常多其中几个高频词在这个项目里全部会碰到列一下我的排障经验。关于 node-gyp有些鸿蒙开发者会在项目里引入需要编译原生代码的npm依赖然后node-gyp报错。这类问题的本质是鸿蒙ArkTS的运行时不兼容Node.js的原生模块不能用常规的C插件编译方式。解决方案是找纯TypeScript/JavaScript实现的替代库或者用鸿蒙生态独有的ohos适配版本。如果你看到某个依赖的README里写着支持HarmonyOS也要确认版本号是适配NEXT 5.0的老API版本重灾区。关于Charles抓包排查网络请求时抓包工具很常用但鸿蒙NEXT应用的证书信任机制比较特殊下载Charles证书时可能没反应。这是因为系统默认不信任用户级CA证书需要在手机设置里进入“加密与凭据 - 信任的凭据”手动启用Charles证书。另外从Android 7和鸿蒙NEXT开始应用默认不信任用户证书的情况下抓包工具很难看到HTTPS明文因为客户端是鸿蒙应用数据走的是AGC的HTTPS接口。这里额外提醒一句抓包只应该用在你自己的应用调试上对别人开发的App做抓包分析涉及隐私安全问题尤其涉及个人账号和数据时请务必注意使用边界。关于hdc很多人不知道hdc在DevEco Studio集成的路径里Windows上是DevEco Studio安装目录\sdk\default\openharmony\toolchains\hdc.exe。把它加进系统PATH之后就能在任意终端执行hdc list targets、hdc install这些命令。真机连接后如果一直显示离线检查手机上的“开发者模式”和“USB调试”是否打开还有USB线是否是数据线很多Type-C线只支持充电。关于应用签名DevEco Studio的自动签名只适合调试如果要发布到应用市场或给其他人安装需要去AGC后台申请发布证书和Profile文件。调试包和发布包不能共用签名否则应用市场上架会报签名冲突。自己测试时遇到“安装失败证书不一致”这类错误先删掉手机上旧版应用再重新安装。4.2 签名和hap安装流程真机调试的完整流程是这样的先在AGC控制台创建项目、添加应用记录下应用的AppGallery Connect配置文件agconnect-services.json把它放到工程根目录。然后在DevEco Studio里打开File Project Structure Signing Configs勾选“Automatically generate signature”登录华为开发者账号让IDE自动生成调试证书。最后点击Run按钮选择你的鸿蒙手机等编译完成自动安装启动。打包发布版hap更直观一点在DevEco Studio右上角选择Build Build Hap(s)/APP(s) Build Hap(s)产物在entry/build/default/outputs/default/目录下。把entry-default-signed.hap发给别人对方用hdc install entry-default-signed.hap就能装上。如果对方没有hdc环境可以把hap包通过第三方应用市场分发或者用华为的“应用调试分发”服务生成下载二维码那边测试人员扫码就能装。4.3 一条实用的排查路径我把自己在真机调试中总结的排查顺序分享出来遇到“应用闪退”“页面白屏”这类诡异问题时按这个顺序检查效率高得多先看DevEco Studio的Log窗口应用崩溃会打印Fatal exception日志定位到具体行号。如果报错信息里出现undefined is not a function大概率是Json解析时字段不存在检查数据模型是否和云数据库返回字段严格一致。如果页面能打开但数据加载不出来检查AGC的API密钥配置是否生效以及agconnect-services.json是否放在了正确位置。如果所有接口都超时把手机和电脑切到同一Wi-Fi关闭代理工具再试。这套路径解决了我在多个鸿蒙项目里90%的疑难杂症核心思想就是先区分是UI层、逻辑层还是网络层的问题不要一个劲地看代码。5. 从“小应用”到“完整项目”的延伸建议5.1 功能扩展的可能性个人记账这个业务模型的可扩展性其实很强。一个典型的升级路径是从单用户记账变成家庭共享账本或者多账本管理日常账、旅行账、装修账。一旦引入多人共享数据模型就需要引入“账本”集合账单和用户的关系变成多对多权限控制逻辑也要重新设计。如果你想把这个项目当作毕设或参赛作品我建议在现有基础上加一到两个有亮点的功能而不是铺太多功能面。比如“语音记账”就是一个体验很好的方向HarmonyOS NEXT提供了一套语音识别API用户说“早上打车花了23块”应用自动识别出金额、分类和备注生成账单。再比如“智能分析”端侧跑一个小模型按消费行为给用户打标签比如“外卖重度用户”生成个性化周报。5.2 工程规范与组件化沉淀参加鸿蒙高校创新赛或者正式商业项目时代码规范比功能实现更影响上线质量。我建议把你写好的几个通用组件沉淀成HAR包金额输入框、分类宫格选择器、月度封面对比卡片、预算进度条这些在不同页面里复用率很高。HAR包和HSP包动态共享包的差别在于HAR会被编译到宿主应用里HSP支持独立升级。对于小型应用用HAR就够了。另外如果能给这个项目写一套简单的单元测试比如金额计算、云函数聚合逻辑、预算进度计算会让整个项目的可信度高很多。HarmonyOS NEXT支持使用ohos/hypium测试框架写起来和JUnit差不多。5.3 上架与合规要点如果要把应用发到华为应用市场除了完善功能和UI有几件合规的事要提前准备隐私政策记账应用涉及用户账单数据和个人信息必须提供隐私政策页面并在首次启动时弹窗获得用户同意。权限最小化鸿蒙的权限申请是动态的不要提前申请用不到的系统权限权限越少过审越容易。内容审核分类图标和默认数据别用可能涉及版权问题的素材自绘风格最安全。签名证书用发布证书打包不要在详情里写“测试版”否则审核会被打回。关于热门讨论的“开源鸿蒙PC版”目前OpenHarmony的桌面版本还在快速迭代如果将来想在PC端也跑这套记账应用需要留意屏幕适配逻辑。手机端的窄屏布局直接放到宽屏上文本和按钮会被拉得很奇怪建议在布局阶段就多用自适应组件如Row/Column的权重布局少写固定像素值为将来多端部署留一条后路。按我个人实操的体会拆解这个鸿蒙记账小应用的过程比从零看文档写一个全新项目收获要大得多。因为你不只是在学API而是在学一套完整的设计决策为什么记账场景适合做鸿蒙样板项目为什么后端用AGC为什么预算计算放在云函数而不是端侧这些选择背后都有成本和效益的考量。你把这个项目里的每一处选择都弄明白后再去看其他鸿蒙项目会发现很多套路都是相通的。最后再分享一个小技巧如果你拿到手的是一个别人传的压缩包别直接双击打开先解压到一个纯英文路径下DevEco Studio对中文路径的支持偶尔会出幺蛾子别在这个地方浪费一晚上。本文还有配套的精品资源点击获取 HarmonyOS鸿蒙记账应用开发实战：从工程拆解到上架全流程
简介在移动应用开发领域云原生与端侧协同已成为主流趋势。HarmonyOS NEXT作为华为自研操作系统采用ArkTS语言与ArkUI声明式UI为开发者提供了高效的开发体验。借助AGCApp Gallery Connect平台开发者可以快速集成云数据库、云函数、认证服务等后端能力无需自建服务器即可构建完整应用闭环。以个人记账类应用为例这类典型业务场景涵盖列表、表单、图表统计与预算管理能充分检验ArkTS的数据绑定、状态管理与组件化能力。通过拆解鸿蒙记账应用的工程结构、核心模块实现、真机调试与签名打包流程可以系统地掌握从开发到上架的完整路径为开发鸿蒙应用、参赛或毕设提供实用参考。 收到这个HarmonyOS 鸿蒙小应用.zip压缩包的时候我下意识看了一眼大小和文件结构第一反应是这不是一个随手写两页界面的Demo而是一个把鸿蒙端、云后端、用户体系全串起来的完整闭环。压缩包里是一个典型的前后端分离记账应用端侧用ArkTS ArkUI开发用户认证、账单记录、分类管理、统计分析、预算管理五个模块齐全后端跑在AGCAppGallery Connect上。说实话这类“小应用”反而是现阶段鸿蒙生态里最有参考价值的样例因为它把一条从开发到上线的实用路径全部走通了。这篇内容适合两类人一是刚接触HarmonyOS NEXT、想找一个完整项目来拆解的开发者二是在校学生或独立开发者准备用鸿蒙应用参加比赛、做毕设或上线商店需要一个能快速落地的参考模板。我会把这个压缩包里能拆出来的技术决策、实现细节和坑全部讲透顺便把开发环境、签名打包、真机调试这些绕不开的流程一起梳理干净。1. 先看懂这个“小应用”项目定位与设计思路拆解1.1 解开压缩包这里面到底装了什么先别急着双击运行。压缩包里的工程结构通常分这么几块entry模块是主入口模块负责应用启动、页面路由和UI展示common或shared目录放公共工具类和常量后端部分一般不会把源代码放进压缩包而是把云函数、云数据库集合结构、认证服务配置以文档或导出文件的形式附上。个人记账应用的功能划分很清晰对应关系大致是这样模块端侧职责云端职责用户认证登录页、登录状态管理AGC Auth 认证服务账单记录新增/编辑/删除账单页面云数据库账单集合分类管理分类选择器、图标映射云数据库分类集合统计分析图表展示、汇总卡片云函数聚合计算预算管理预算设置页、进度展示云数据库预算集合这里有个值得注意的细节HarmonyOS NEXT 5.0及以上版本的应用端侧只能使用ArkTS语言开发这意味着整个前端代码都是基于Stage模型和声明式UI写出来的。你打开工程后如果看到大量Entry、Component、State装饰器不用慌这些都是ArkUI的常规语法跟传统Android的XML布局思路完全不同。1.2 为什么选“个人记账”这个场景记账应用能成为鸿蒙生态里的“样板房”项目不是偶然的。它的数据模型足够简单不需要复杂的网络通信和实时同步但麻雀虽小五脏俱全有列表页、表单页、图表统计页、设置页基本覆盖了移动应用最常见的页面类型。对于学习鸿蒙开发的人来说这比单纯做一个“Hello World”或者一个单页工具类应用有价值得多。更深一层看记账应用涉及的核心技术点都很“通用”。列表渲染和状态管理对应了日常业务开发最频繁的操作表单输入和校验考验的是事件处理和数据绑定统计图表需要处理Canvas绘制或第三方库集成预算管理则涉及本地计算与云端数据的配合。把这套逻辑跑通了换成“笔记应用”“任务管理应用”也一样能套用。这个项目选择后端用AGC而不是自己搭服务器也是个很实际的决定——个人开发者或学生团队根本没精力去维护一台云主机更不用说搞域名备案和HTTPS证书了。AGC云数据库、云函数、认证服务这些能力能让你把90%的后端工作外包出去端侧只需要关注UI和业务交互。1.3 技术选型HarmonyOS NEXT 5.0 AGC后端能省掉多少事HarmonyOS NEXT的版本策略和Android、iOS不一样每个大版本之间的API变化明显5.0及以上版本开始强制使用ArkTS不再支持Java和兼容Android应用的运行。所以开发前第一件事就是确认你的DevEco Studio版本对得上SDK版本否则工程打开后会提示SDK不匹配。AGC后端提供的几个核心服务在记账场景里是这样落地的AGC Auth支持华为账号、手机号、邮箱等多种认证方式不用自己维护用户表和密码加密逻辑。云数据库直接创建集合类似MongoDB的collection客户端SDK可以像操作本地数据库一样读写云端数据。云函数写JavaScript或TypeScript函数跑在华为云上适合做统计汇总、预算月度重置这类不方便在端侧完成的计算。云存储如果将来要加头像上传、账单附件能直接存文件。这套组合拳的好处在于整个项目不需要一台自己的服务器不需要处理CORS跨域问题甚至连HTTPS证书都不用操心因为AGC的接口域名和证书都是华为统一管理的。这几乎是鸿蒙应用开发里起步成本最低的路径。2. 开发环境搭建与工程结构设计2.1 DevEco Studio版本、API Level和模拟器选择打开压缩包之前先把开发环境搞定。我用的是DevEco Studio 5.x版本配合HarmonyOS SDK API 12及以上编译目标选的是HarmonyOS NEXT 5.0.0。如果你工程里的build-profile.json5文件里写的compatibleSdkVersion比我高就需要去升级DevEco Studio否则编译会直接报错。关于调试设备我的经验是真机优先。鸿蒙模拟器在API 10之后的版本虽然在不断进步但有些硬件能力比如摄像头、传感器、指纹还是模拟不全而AGC登录、推送这类服务在模拟器上也容易出现环境差异。你有一台HarmonyOS NEXT手机的话用USB连上电脑DevEco Studio会自动识别设备点一下Run就能跑到真机上。这里插一个关键词解释方便新手听明白hdc是鸿蒙开发者命令行工具类似于Android的adb。你在命令行里敲hdc list targets能看到已连接的设备列表hdc install xxx.hap可以直接安装应用包hdc shell可以进入设备的Shell环境。很多热词里提到的“鸿蒙hdc安装”“hdc shell怎么开”其实都是通过DevEco Studio自带的终端工具就能解决的。2.2 三层架构在项目里怎么落地鸿蒙官方推荐的“应用程序级三层架构”一般分为UI层、能力层、公共层。这个记账项目在工程结构上完全可以照搬这套思路UI层放在entry/src/main/ets/pages和entry/src/main/ets/views下所有页面和自定义组件都归这里。页面负责布局、交互事件、状态展示不直接写业务逻辑。能力层放在entry/src/main/ets/model和entry/src/main/ets/service下Model层定义账单、分类、预算这些数据模型Service层封装调用AGC云数据库、云函数的方法。页面要数据就调Service层接口页面不关心数据是从哪来的。公共层放在entry/src/main/ets/common下包含工具函数、常量定义、通用样式、日期格式化方法等。这么分层的直接好处是当你把云数据库从AGC换成本地首选项存储只需要改Service层的实现页面代码一行都不用动。我在实际开发里见过很多初学者把所有代码堆在aboutToAppear()生命周期里一个页面几百行后期维护非常痛苦。2.3 应用沙箱和hap包先搞清楚东西装在哪儿HarmonyOS的沙箱机制比Android更严格。应用安装后所有的私有数据都存在一个沙箱目录里应用A无法访问应用B的数据文件即使通过文件管理器也看不到其他应用的内部目录。对于记账应用来说这意味着你缓存的用户头像、本地备份文件默认都是安全的。你打出来的entry-default-signed.hap包就是鸿蒙应用的安装包格式。通过DevEco Studio Run运行的时候IDE自动帮你完成签名和安装如果要把包发给别人对方可以通过hdc install安装。这里有一个小坑不同调试证书签名的hap包不能覆盖安装如果遇到“安装失败”提示先检查签名是否一致卸载重装通常能解决但会清掉本地数据。3. 五大核心模块的实现要点3.1 用户认证接AGC Auth别自己写session记账应用的数据是强隐私的每个人只能看到自己的账单所以用户认证是全部功能的前提。压缩包里如果用了AGC Auth集成路径一般是在AGC控制台开通认证服务配置支持的认证方式比如手机号、华为账号然后在工程里引入hw-agconnect/auth-component依赖调用登录接口后拿到用户唯一标识uid。很多Web转鸿蒙的开发者会习惯性地想自己设计token和session我的建议是别折腾。AGC Auth已经帮你处理好了token生命周期、自动刷新、用户信息缓存你只要在Service层写一个getCurrentUid()方法拿到这个ID之后所有的账单记录都带上这个字段作为筛选条件天然就能实现“用户A看不到用户B的账单”的隔离效果。登录页面的UI在ArkUI里写也不复杂一个手机号输入框、一个验证码输入框、一个登录按钮就够了。验证码发送走AGC的短信服务几分钟就能配好。唯一要留意的是AGC Auth在API 12之后的SDK包名和方法签名有过调整如果编译报找不到AGConnectAuth类检查一下依赖版本是否和你的SDK匹配。3.2 账单记录数据模型和状态管理是关键账单数据模型建议这样设计Bill { id: string // 账单ID云数据库自动生成 uid: string // 所属用户标识 amount: number // 金额单位分或元注意精度 categoryId: string // 分类ID remark: string // 备注 type: number // 0-支出 1-收入 createTime: number // 创建时间戳毫秒 }金额字段是我特别想提醒的。浮点数在计算机里存在精度问题0.1 0.2 不等于 0.3这在记账应用里会酿成大祸。推荐用法是金额以“分”为单位存整数展示的时候再除以100格式化这样既避免精度问题也方便统计聚合。新增账单页面在ArkUI里用State装饰器管理表单状态用户输入金额、选择分类、填写备注点击保存后调用Service层把数据写入云数据库。列表页用ListForEach渲染下拉刷新用PullToRefreshV2这类第三方库上拉加载更多通过监听滚动位置的onReachEnd事件触发。状态管理方面如果预算页和统计页需要实时反映账单变化建议在页面间用路由参数传递刷新标记或者用AppStorage存储一个全局的“数据版本号”。每当你增删改账单就把版本号加1其他页面监听版本号变化后重新拉取数据。这个方案比用Watch监听复杂对象靠谱得多。3.3 分类管理图标映射和颜色匹配的细节分类管理模块看起来简单但实际做起来有不少细节。首先是分类数据从哪来我建议做成“云端预置 本地缓存”的结构首次启动时从云数据库拉取默认分类列表餐饮、交通、购物、住房、娱乐、医疗等用户也可以自定义分类。云数据库里每条分类记录包含name、icon、color、sortOrder字段这样客户端拿到数据后能直接渲染。图标映射是容易踩坑的地方。鸿蒙的资源文件放在resources/base/media目录下如果你打算分类图标用本地资源那么云端存的应该是资源名称字符串比如ic_food前端通过$r(app.media. iconName)动态加载。这里有个限制动态拼接资源名的写法在编译期可能无法校验如果资源不存在会直接崩掉。稳妥做法是建一个图标名到资源对象的映射表查询不到时给一个默认图标。颜色匹配也有讲究。支出分类用偏暖色红橙收入分类用偏冷色绿蓝统计图表里同色系会比较好区分。分类选择器如果做成宫格形式用Grid组件渲染选中态通过State selectedCategoryId控制边框高亮。整体交互要做到用户新增账单时点击分类弹出一个半屏的底部弹窗选完自动返回并填充分类名。3.4 统计分析图表是表面聚合逻辑才是核心统计分析模块是这个项目里有技术含金量的部分。月度账单汇总页需要展示本月总支出、总收入、结余分类占比饼图以及近6个月的支出趋势折线图。这些数据如果全部拉明细在端侧算数据量大了之后性能会很差正确做法是让云函数做聚合。// 云函数伪代码按月份和分类统计支出 export async function aggregateMonthlyExpense(uid: string, year: number, month: number) { const db cloud.database(); const start new Date(year, month - 1, 1).getTime(); const end new Date(year, month, 1).getTime(); const bills await db.collection(bills) .where({ uid, type: 0, createTime: db.command.gte(start).and(db.command.lt(end)) }) .get(); const mapping {}; bills.data.forEach(bill { if (!mapping[bill.categoryId]) { mapping[bill.categoryId] 0; } mapping[bill.categoryId] bill.amount; }); return mapping; }云函数把聚合结果以轻量的JSON对象返回给端侧端侧拿到数据后直接驱动图表组件。图表实现有两种选择一是用Svg组件配合Path元素手动画饼图和折线图优点是零依赖、包体小缺点是代码量大二是第三方图表库省事但引入之前要先确认它支持HarmonyOS NEXT的ArkTS环境不能直接用React/Vue的组件库。我个人的建议是饼图用Svg手绘就行原理很简单Path元素里d属性画圆弧根据每个分类的占比算出弧度的起始角和终止角。折线图稍复杂一些但核心也就是计算坐标点然后连线。手绘的好处是你对每一个像素都有掌控力样式调整也不用受限于组件库的API。3.5 预算管理预警逻辑怎么设计才不烦人预算模块的逻辑闭环是用户给某个分类设置月度预算金额然后实时计算该分类当月已支出金额展示剩余额度和进度条。如果支出超过预算的80%进度条变黄提示“快超了”超过100%变红提示“已超支”。这里的核心是“预算计算”的时机不需要每次都去云数据库拉全量账单。我建议在云数据库里加一个budgets集合每次用户新增/编辑/删除账单时在Service层同步调用云函数更新对应分类的usedAmount字段。虽然牺牲了一点实时性但换取的是首页加载时只需要查一条预算记录就能展示进度条不用做JOIN查询或二次聚合。预警逻辑放在端侧做更灵活。因为推送通知的权限配置相对繁琐我在项目里优先选择应用内提示进入首页时如果发现某分类预算使用率超过100%首页顶部弹出一条警示卡片展示“餐饮分类本月已超出预算”。如果后续要接系统通知再通过AGC推送服务补充。这里设计时要注意避免“狼来了”——用户每天被超支提醒轰炸很快就会把通知权限关掉所以预警阈值要给用户一个设置入口别把80%和100%写死。4. 真机调试、打包安装与常见坑4.1 从热词里扒出来的几个高频问题在整理这个项目资料的过程中我注意到网上搜鸿蒙开发相关问题的人非常多其中几个高频词在这个项目里全部会碰到列一下我的排障经验。关于 node-gyp有些鸿蒙开发者会在项目里引入需要编译原生代码的npm依赖然后node-gyp报错。这类问题的本质是鸿蒙ArkTS的运行时不兼容Node.js的原生模块不能用常规的C插件编译方式。解决方案是找纯TypeScript/JavaScript实现的替代库或者用鸿蒙生态独有的ohos适配版本。如果你看到某个依赖的README里写着支持HarmonyOS也要确认版本号是适配NEXT 5.0的老API版本重灾区。关于Charles抓包排查网络请求时抓包工具很常用但鸿蒙NEXT应用的证书信任机制比较特殊下载Charles证书时可能没反应。这是因为系统默认不信任用户级CA证书需要在手机设置里进入“加密与凭据 - 信任的凭据”手动启用Charles证书。另外从Android 7和鸿蒙NEXT开始应用默认不信任用户证书的情况下抓包工具很难看到HTTPS明文因为客户端是鸿蒙应用数据走的是AGC的HTTPS接口。这里额外提醒一句抓包只应该用在你自己的应用调试上对别人开发的App做抓包分析涉及隐私安全问题尤其涉及个人账号和数据时请务必注意使用边界。关于hdc很多人不知道hdc在DevEco Studio集成的路径里Windows上是DevEco Studio安装目录\sdk\default\openharmony\toolchains\hdc.exe。把它加进系统PATH之后就能在任意终端执行hdc list targets、hdc install这些命令。真机连接后如果一直显示离线检查手机上的“开发者模式”和“USB调试”是否打开还有USB线是否是数据线很多Type-C线只支持充电。关于应用签名DevEco Studio的自动签名只适合调试如果要发布到应用市场或给其他人安装需要去AGC后台申请发布证书和Profile文件。调试包和发布包不能共用签名否则应用市场上架会报签名冲突。自己测试时遇到“安装失败证书不一致”这类错误先删掉手机上旧版应用再重新安装。4.2 签名和hap安装流程真机调试的完整流程是这样的先在AGC控制台创建项目、添加应用记录下应用的AppGallery Connect配置文件agconnect-services.json把它放到工程根目录。然后在DevEco Studio里打开File Project Structure Signing Configs勾选“Automatically generate signature”登录华为开发者账号让IDE自动生成调试证书。最后点击Run按钮选择你的鸿蒙手机等编译完成自动安装启动。打包发布版hap更直观一点在DevEco Studio右上角选择Build Build Hap(s)/APP(s) Build Hap(s)产物在entry/build/default/outputs/default/目录下。把entry-default-signed.hap发给别人对方用hdc install entry-default-signed.hap就能装上。如果对方没有hdc环境可以把hap包通过第三方应用市场分发或者用华为的“应用调试分发”服务生成下载二维码那边测试人员扫码就能装。4.3 一条实用的排查路径我把自己在真机调试中总结的排查顺序分享出来遇到“应用闪退”“页面白屏”这类诡异问题时按这个顺序检查效率高得多先看DevEco Studio的Log窗口应用崩溃会打印Fatal exception日志定位到具体行号。如果报错信息里出现undefined is not a function大概率是Json解析时字段不存在检查数据模型是否和云数据库返回字段严格一致。如果页面能打开但数据加载不出来检查AGC的API密钥配置是否生效以及agconnect-services.json是否放在了正确位置。如果所有接口都超时把手机和电脑切到同一Wi-Fi关闭代理工具再试。这套路径解决了我在多个鸿蒙项目里90%的疑难杂症核心思想就是先区分是UI层、逻辑层还是网络层的问题不要一个劲地看代码。5. 从“小应用”到“完整项目”的延伸建议5.1 功能扩展的可能性个人记账这个业务模型的可扩展性其实很强。一个典型的升级路径是从单用户记账变成家庭共享账本或者多账本管理日常账、旅行账、装修账。一旦引入多人共享数据模型就需要引入“账本”集合账单和用户的关系变成多对多权限控制逻辑也要重新设计。如果你想把这个项目当作毕设或参赛作品我建议在现有基础上加一到两个有亮点的功能而不是铺太多功能面。比如“语音记账”就是一个体验很好的方向HarmonyOS NEXT提供了一套语音识别API用户说“早上打车花了23块”应用自动识别出金额、分类和备注生成账单。再比如“智能分析”端侧跑一个小模型按消费行为给用户打标签比如“外卖重度用户”生成个性化周报。5.2 工程规范与组件化沉淀参加鸿蒙高校创新赛或者正式商业项目时代码规范比功能实现更影响上线质量。我建议把你写好的几个通用组件沉淀成HAR包金额输入框、分类宫格选择器、月度封面对比卡片、预算进度条这些在不同页面里复用率很高。HAR包和HSP包动态共享包的差别在于HAR会被编译到宿主应用里HSP支持独立升级。对于小型应用用HAR就够了。另外如果能给这个项目写一套简单的单元测试比如金额计算、云函数聚合逻辑、预算进度计算会让整个项目的可信度高很多。HarmonyOS NEXT支持使用ohos/hypium测试框架写起来和JUnit差不多。5.3 上架与合规要点如果要把应用发到华为应用市场除了完善功能和UI有几件合规的事要提前准备隐私政策记账应用涉及用户账单数据和个人信息必须提供隐私政策页面并在首次启动时弹窗获得用户同意。权限最小化鸿蒙的权限申请是动态的不要提前申请用不到的系统权限权限越少过审越容易。内容审核分类图标和默认数据别用可能涉及版权问题的素材自绘风格最安全。签名证书用发布证书打包不要在详情里写“测试版”否则审核会被打回。关于热门讨论的“开源鸿蒙PC版”目前OpenHarmony的桌面版本还在快速迭代如果将来想在PC端也跑这套记账应用需要留意屏幕适配逻辑。手机端的窄屏布局直接放到宽屏上文本和按钮会被拉得很奇怪建议在布局阶段就多用自适应组件如Row/Column的权重布局少写固定像素值为将来多端部署留一条后路。按我个人实操的体会拆解这个鸿蒙记账小应用的过程比从零看文档写一个全新项目收获要大得多。因为你不只是在学API而是在学一套完整的设计决策为什么记账场景适合做鸿蒙样板项目为什么后端用AGC为什么预算计算放在云函数而不是端侧这些选择背后都有成本和效益的考量。你把这个项目里的每一处选择都弄明白后再去看其他鸿蒙项目会发现很多套路都是相通的。最后再分享一个小技巧如果你拿到手的是一个别人传的压缩包别直接双击打开先解压到一个纯英文路径下DevEco Studio对中文路径的支持偶尔会出幺蛾子别在这个地方浪费一晚上。本文还有配套的精品资源点击获取