HarmonyOS 实战教程（一）：项目架构与环境搭建 —— 以「柚兔自测量表」为例

一、项目概述「柚兔自测量表」MeCharts是一款基于 HarmonyOS NEXT 开发的心理健康自测应用集成了 ABC 自闭症行为评定量表、CARS 儿童孤独症评定量表、多动症诊断量表、SDS 抑郁自评量表、SAS 焦虑自评量表、ECR 亲密关系经历量表以及 MBTI 职业性格测试等七大心理量表同时提供 AI 智能咨询功能帮助用户解读测评结果并给出专业建议。本文将从项目架构、开发环境搭建、工程配置等方面入手带你从零理解一个 HarmonyOS 商业级应用的架构设计。二、开发环境准备2.1 安装 DevEco StudioHarmonyOS 应用开发需要使用华为官方 IDE —— DevEco Studio。请前往华为开发者官网下载最新版本安装过程与常规 IDE 类似此处不再赘述。2.2 SDK 版本要求本项目基于 HarmonyOS NEXTAPI 12开发需确保 DevEco Studio 中已下载对应版本的 SDKCompile SDK Version12 及以上Compatible SDK Version12 及以上Runtime SDK Version12 及以上三、项目架构分析3.1 整体目录结构MeCharts/ ├── AppScope/ # 应用级配置 │ └── app.json5 # 应用全局配置bundleName、版本号等 ├── entry/ # 主模块 │ └── src/main/ │ ├── ets/ # ArkTS 源码 │ │ ├── entryability/ # UIAbility 入口 │ │ ├── pages/ # 页面文件 │ │ ├── view/ # 视图组件Tab 页面 │ │ ├── component/ # 可复用 UI 组件 │ │ ├── model/ # 业务模型层 │ │ ├── data/ # 数据模型与数据源 │ │ ├── http/ # 网络请求封装 │ │ ├── constant/ # 常量定义 │ │ └── util/ # 工具类 │ ├── resources/ # 资源文件 │ └── module.json5 # 模块配置 ├── build-profile.json5 # 构建配置 ├── oh-package.json5 # 依赖管理 └── hvigorfile.ts # 构建脚本3.2 分层架构设计本项目采用了清晰的分层架构各层职责明确层级目录职责表现层pages/、view/、component/UI 渲染与用户交互业务层model/业务逻辑处理、单例管理数据层data/、http/数据模型定义、网络请求基础设施层util/、constant/工具类、常量定义这种分层方式使得代码职责清晰便于维护和扩展。四、核心配置文件详解4.1 应用全局配置app.json5{ app: { bundleName: com.youtoo.mechat, vendor: example, versionCode: 1001012, versionName: 1.0.0.1012, icon: $media:layered_image, label: $string:app_name } }关键字段说明bundleName应用唯一标识采用反域名格式发布后不可更改versionCode版本号用于版本比较每次更新必须递增versionName用户可见的版本名称icon/label引用资源文件实现多语言适配4.2 模块配置module.json5{ module: { name: entry, type: entry, mainElement: EntryAbility, deviceTypes: [phone, tablet, 2in1], requestPermissions: [ { name: ohos.permission.INTERNET } ], abilities: [{ name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, exported: true, skills: [{ entities: [entity.system.home], actions: [ohos.want.action.home] }] }], routerMap: $profile:router_map } }关键配置解读deviceTypes支持手机、平板和 2in1 设备实现多设备适配requestPermissions声明网络权限AI 咨询功能需要网络访问routerMap导航路由映射配置文件用于 Navigation 路由系统skills声明 Ability 能处理的主页 Intent使应用可从桌面启动4.3 依赖管理oh-package.json5项目使用了多个三方库来加速开发{ dependencies: { hw-agconnect/ui-swiper: 版本号, // 轮播组件 ibestservices/ibest-orm: 版本号, // ORM 数据库 backup_air: 版本号, // 华为云备份与登录 jjr/lottie_component: 版本号 // Lottie 动画 } }五、创建新工程如果你要从零创建一个类似项目可以在 DevEco Studio 中执行以下步骤选择File → New → Create Project选择Empty Ability模板填写项目信息注意bundleName一旦确定不可更改选择 Compatible SDK 版本为 12 及以上点击 Finish 完成创建创建完成后IDE 会自动生成基础目录结构和配置文件你可以参照本项目的架构进行扩展。六、ArkTS 语法规范须知在正式开发前需要了解 ArkTS 的一些关键约束与标准 TypeScript 的差异禁止使用any和unknown类型必须为所有变量提供明确类型禁止as类型断言需使用显式继承替代对象字面量必须有明确类型上下文不能直接使用未类型化的对象字面量禁止动态属性访问如obj[dynamicKey]是不允许的组件结构约束Component装饰的 struct 必须包含build()方法这些约束确保了 ArkTS 在运行时的高性能表现但也要求开发者在编码时更加注重类型安全。七、小结本篇我们了解了 MeCharts 项目的整体架构设计、开发环境配置以及核心配置文件。良好的架构设计是项目可维护性的基础建议在开始编码前先规划好目录结构和分层策略。下一篇将深入讲解 UIAbility 生命周期管理与应用初始化流程。