架构设计
概述
HCompass 采用四层架构设计，从下到上依次为：Core（框架核心）、Shared（共享契约）、Packages（业务功能包）、Entry（应用入口）。这种分层设计确保了代码的清晰性、可维护性和可复用性。
四层架构
Core / 框架核心层
职责
Core 层是框架的基础，提供与业务无关的通用能力。这一层的代码可以直接复用到其他 HarmonyOS 项目，无需任何修改。
设计原则
- 无业务依赖：不包含任何业务逻辑，保持框架的纯净性
- 可复用：可直接复制到其他项目使用
- 稳定：作为底层基础，接口稳定，不频繁变动
模块组成
| 模块 | 职责 | 主要内容 |
|---|---|---|
| base | 基础父类 | BaseViewModel、BaseNetWorkViewModel 等 |
| common | 通用模块 | 通用常量、枚举等 |
| components | 通用组件 | 可复用的 UI 组件 |
| database | 数据库 | 数据库封装和操作 |
| designsystem | 设计系统 | 颜色、间距、字体等视觉规范 |
| di | 依赖注入 | DI 容器和注入机制 |
| ibestui | IBest UI | IBest-UI-V2 组件库封装 |
| layoutstate | 布局状态 | 响应式布局状态管理 |
| module | 模块管理 | 模块注册和管理 |
| navigation | 导航系统 | 路由配置和导航服务 |
| network | 网络请求 | HTTP 请求封装 |
| util | 工具类 | 各种工具函数 |
Shared / 共享契约层
职责
Shared 层定义功能包之间的共享契约。如果功能包需要对外提供服务或资源，都需要在 Shared 层定义好共享业务属性。
设计原则
- 契约优先：先定义契约，再实现功能
- 解耦：通过契约实现功能包之间的解耦
- 类型安全：使用 TypeScript 类型系统确保类型安全
模块组成
| 模块 | 职责 | 主要内容 |
|---|---|---|
| contracts | 契约定义 | 服务接口、数据接口等 |
| state | 共享状态 | 跨功能包的共享状态 |
| types | 类型定义 | 通用类型定义 |
示例
typescript
// shared/contracts/IUserService.ets
export interface IUserService {
getUserInfo(): Promise<UserInfo>;
updateUserInfo(info: UserInfo): Promise<void>;
}
// packages/user/UserServiceImpl.ets
export class UserServiceImpl implements IUserService {
async getUserInfo(): Promise<UserInfo> {
// 实现逻辑
}
async updateUserInfo(info: UserInfo): Promise<void> {
// 实现逻辑
}
}Packages / 业务功能包层
职责
Packages 层包含具体的业务功能包，每个功能包都是一个独立的业务模块。功能包通过 Shared 层定义的契约对外提供服务，通过 DI 注入实现功能包之间的解耦。
设计原则
- 高内聚：每个功能包内部高度内聚，职责单一
- 低耦合：功能包之间通过契约解耦，不直接依赖
- 可复用：功能包可以跨项目复用
- 独立开发：功能包可以独立开发、测试和部署
功能包结构
packages/
└── user/ # 用户功能包
├── navigation/ # 导航构建器
├── services/ # 服务
│ └── UserServiceImpl.ets
├── view/ # 页面
│ ├── UserProfilePage.ets
│ └── UserSettingsPage.ets
├── viewmodels/ # ViewModel
│ ├── UserProfileViewModel.ets
│ └── UserSettingsViewModel.ets
├── models/ # 数据模型
│ └── UserModel.ets
└── UserModule.ets # 功能包生命周期Entry / 应用入口
职责
Entry 层是应用的入口，负责初始化框架和配置应用。
主要任务
- 初始化 DI 容器
- 注册功能包
- 配置路由
- 启动应用
示例
typescript
// entry/src/main/ets/entryability/EntryAbility.ets
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
// 初始化上下文工具
ContextUtil.init(this.context);
// 初始化数据库
IBestORMInit(this.context, { name: "app.db" });
// 获取 DI 容器
const container = getContainer();
// 注入初始化配置
const NetConf: NetworkConfig = {
baseUrl: "https://xxxxx/app/",
timeout: 10000,
responseParser: {
successCode: 1000,
dataField: 'data',
messageField: 'message',
codeField: 'code'
},
headers: {
'Content-Type': 'application/json'
},
enableLog: true
};
container.register<NetworkConfig>(CoreServiceKeys.ConfigManager, () => NetConf);
// 注入 HTTP 客户端
container.register<AxiosHttpClient>(CoreServiceKeys.HttpClient, () => new AxiosHttpClient(NetConf))
// 获取模块注册器
const module = getModuleRegistry();
// 注册模块
module.register(createMainModule());
...
}
}依赖关系
Entry
↓ 依赖
Packages
↓ 依赖
Shared
↓ 依赖
Core ← 不依赖任何上层模块- Core 不依赖任何上层模块：保持底层的独立性
- Shared 依赖 Core：使用 Core 提供的基础能力
- Packages 依赖 Shared 和 Core：使用契约和基础能力
- Entry 依赖所有层：组装和启动应用
MVVM 架构
在功能包内部，采用 MVVM（Model-View-ViewModel）架构：
View (页面)
↓ 绑定
ViewModel (视图模型)
↓ 调用
Service (服务)
↓ 操作
Model (数据模型)职责划分
- View：仅负责渲染，不包含业务逻辑
- ViewModel：封装所有业务逻辑，管理状态
- Service：处理数据获取和业务操作
- Model：定义数据结构
设计优势
1. 清晰的分层
四层架构清晰地划分了职责，每一层都有明确的边界和职责。
2. 高度模块化
以功能包为单元，实现高度模块化，功能包可以独立开发、测试和复用。
3. 解耦
通过 Shared 层的契约和 DI 注入，实现功能包之间的解耦。
4. 可复用
Core 层和功能包都可以跨项目复用，减少重复劳动。
5. 易于维护
清晰的架构和规范使得代码易于理解和维护。