项目架构与职责
介绍
本节说明 HarmonyKit 的整体架构与模块职责，重点解释三层架构中各层承担的功能边界，帮助你在开发时保持依赖收敛与职责清晰。
架构目标
- 职责清晰：框架能力、业务基础设施、业务功能三层分离，降低耦合。
- 依赖收敛：业务模块只通过 foundation 层的仓库访问数据能力。
- 可维护：模块关系稳定，便于替换与扩展。
- 无业务侵入：core 层完全不包含任何业务逻辑，只提供通用的框架能力，可单独迭代演进。
三层架构概览
┌─────────────────────────────────────────────────────────────┐
│ feature/ (业务功能层) │
│ auth / demo / main / user │
│ 页面、ViewModel、业务组件 ... │
├─────────────────────────────────────────────────────────────┤
│ foundation/ (业务基础设施层) │
│ biz_model / biz_navigation / biz_state │
│ database / datastore / network / repository │
│ 业务模型、业务路由、业务状态、数据源、仓库 ... │
├─────────────────────────────────────────────────────────────┤
│ core/ (框架核心层) │
│ base / designsystem / ibestui / model / navigation │
│ result / state / ui / util │
│ 基类、设计系统、通用模型、导航框架、UI组件、工具类 ... │
└─────────────────────────────────────────────────────────────┘模块职责概览
entry（应用入口）
应用入口与启动流程，负责初始化与路由入口，不承载业务逻辑。
core（框架核心层）
提供与业务无关的通用能力，可直接复用到其他项目。
| 模块 | 职责 |
|---|---|
| base | ViewModel 基类（BaseViewModel、BaseNetWorkViewModel、BaseNetWorkListViewModel） |
| designsystem | 设计系统（布局常量、通用属性、基础组件封装） |
| ibestui | IBest UI 组件库的封装与适配层 |
| model | 通用数据模型（NetworkResponse、NetworkPageData 等） |
| navigation | 导航框架能力（RouteBuild、RouteGraph、NavigationService） |
| result | 统一结果封装与请求辅助（RequestHelper） |
| state | 框架级状态（断点状态 BreakpointState、安全区状态 WindowSafeAreaState 等） |
| ui | 通用 UI 组件（AppNavDestination、BaseNetWorkView、Empty 等） |
| util | 工具类（PreferencesUtil、ContextUtil、ToastUtils 等） |
foundation（业务基础设施层）
提供业务相关的基础能力，是 core 与 feature 之间的桥梁。
| 模块 | 职责 |
|---|---|
| biz_model | 业务实体与请求对象（Auth、Goods、User、PasswordLoginRequest 等） |
| biz_navigation | 业务路由封装（AuthNavigator、MainNavigator、DemoNavigator 等） |
| biz_state | 业务状态管理（UserState、DemoCounterState 等） |
| database | 本地数据库数据源（DemoLocalDataSource、DemoEntity 等） |
| datastore | 本地存储数据源（TokenStoreDataSource、AccountStoreDataSource 等） |
| network | 网络数据源（AuthNetworkDataSource、GoodsNetworkDataSource 等） |
| repository | 仓库层，聚合各数据源（AuthRepository、DemoRepository 等） |
feature（业务功能层）
按业务域拆分的功能模块，包含页面与 ViewModel。
| 模块 | 职责 |
|---|---|
| auth | 认证模块（登录页） |
| demo | 示例模块（网络、数据库、存储、状态管理等示例） |
| main | 主模块（首页、导航示例） |
| user | 用户模块（用户资料） |
依赖关系与边界
feature/*
↓ 依赖
foundation/repository ← foundation/database
↓ ← foundation/datastore
↓ ← foundation/network
foundation/biz_model
foundation/biz_navigation → foundation/biz_state
foundation/biz_state
↓ 依赖
core/*依赖规则
- feature 依赖 foundation 和 core：业务模块通过 foundation 层访问数据和业务能力。
- foundation 依赖 core：业务基础设施层使用 core 的框架能力。
- core 不依赖任何业务模块：保持框架层的纯净，可直接复用。
- feature 之间不互相依赖：业务模块保持隔离，避免交叉依赖。
数据访问路径示例
ViewModel (feature)
↓ 调用
Repository (foundation/repository)
↓ 聚合
NetworkDataSource (foundation/network)
LocalDataSource (foundation/database)
StoreDataSource (foundation/datastore)
↓ 使用
NetworkClient / IBest-ORM / PreferencesUtil (core)- 业务模块的 ViewModel 调用
repository提供的仓库方法。 - 仓库内部按需访问网络、数据库或本地存储数据源。
- 数据源使用 core 层的基础能力完成实际操作。
- 结果通过统一封装返回给业务层。
设计约束
- core 层只做通用能力，不掺杂任何业务逻辑，可直接复用到其他项目。
- foundation 层做业务基础设施，定义业务模型、业务路由、业务状态和数据源对接。
- feature 层只做业务，不直接调用网络/数据库，通过 repository 访问数据。
- 导航分两层：core/navigation 提供框架能力，foundation/biz_navigation 封装业务路由。
- 状态分两层：core/state 管理框架状态，foundation/biz_state 管理业务状态。