210 lines
8.9 KiB
Markdown
210 lines
8.9 KiB
Markdown
# HarmonyOS NEXT 客户端 · 架构设计文档
|
||
|
||
> 项目：`harmony-client`（ArkTS + ArkUI，SDK 6.0.2 / API 22，仅 phone）
|
||
> 业务形态：对接自有后端的通用业务客户端（HTTP + 鉴权 + CRUD）
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
本工程从 DevEco 空脚手架起步，目标是建立一套**可持续演进、可测试、低耦合**的客户端架构骨架，为后续业务开发打底。设计依据来自一轮 deep-research 调研（交叉验证华为官方文档与社区实践，9 条结论全部通过对抗式验证）。
|
||
|
||
核心决策：
|
||
|
||
| 决策点 | 选择 | 理由 |
|
||
|---|---|---|
|
||
| 工程结构 | 官方三层 commons / features / products | 单向依赖、官方白皮书推荐 |
|
||
| 模块化 | **单 HAP + 多 HAR** | HAR 编译期打包、可裁剪；HSP 仅按需加载 |
|
||
| 代码分层 | **MVVM + 独立 data 层** | 官方指南 + 网络/数据解耦 |
|
||
| 状态管理 | **全量 StateManagement V2** | API 22 下 V2 能力完整，字段级精准刷新 |
|
||
|
||
---
|
||
|
||
## 2. 模块划分与依赖
|
||
|
||
```
|
||
harmony-client/
|
||
├── entry/ HAP 应用壳 + 业务功能（唯一入口，EntryAbility）
|
||
├── common/ HAR 基础设施层（网络 / 日志 / 状态 / 工具，无业务、无 UI 组件）
|
||
└── uikit/ HAR 通用 UI 组件库 + 主题（无业务、无网络依赖）
|
||
```
|
||
|
||
依赖方向严格单向，禁止反向/循环：
|
||
|
||
```
|
||
entry ──依赖──▶ common
|
||
entry ──依赖──▶ uikit
|
||
common / uikit 各自独立，互不依赖
|
||
```
|
||
|
||
- **common**：`HttpClient`、鉴权拦截器、统一错误模型、`Logger`、`SessionStore`（PersistenceV2 持久化）、工具函数。
|
||
- **uikit**：主题 token（`AppColor/AppSpacing/AppFontSize`）、通用组件（`AppButton/LoadingView/EmptyView`）。
|
||
- **entry**：应用壳装配、路由、DI 容器、MVVM 分层业务代码。
|
||
|
||
---
|
||
|
||
## 3. 分层与目录结构（entry 内）
|
||
|
||
采用官方 MVVM 指南的**层优先**结构，叠加独立 `data/` 层与横切的 `router/`、`di/`：
|
||
|
||
```
|
||
entry/src/main/ets/
|
||
├── entryability/
|
||
│ └── EntryAbility.ets # 生命周期装配：Logger / ServiceLocator / SessionStore
|
||
├── router/
|
||
│ ├── RouteMap.ets # 路由名常量 + name→页面 分发
|
||
│ └── AppRouter.ets # Navigation 导航封装（push/replace/pop/...）
|
||
├── di/
|
||
│ └── ServiceLocator.ets # 轻量服务定位器（ArkTS 无反射，手动注册/解析）
|
||
├── model/ # 领域模型：@ObservedV2 + @Trace 实体
|
||
├── data/
|
||
│ ├── api/ # DTO + 请求服务（调 common 的 HttpClient）
|
||
│ └── repository/ # 数据仓库契约（抽象类）+ 实现
|
||
├── viewmodel/ # @ObservedV2 状态容器（data/loading/error 三态）
|
||
├── view/ # 可复用 UI 组件（@ComponentV2）
|
||
└── pages/ # 页面，仅编排（组合 view + viewmodel）
|
||
```
|
||
|
||
**单向数据流**：
|
||
|
||
```
|
||
pages → viewmodel → repository(契约) → api → HttpClient → 后端
|
||
↑ 状态回传由 @Trace 触发自动刷新
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 状态管理约定（全量 V2，禁用 V1）
|
||
|
||
| 场景 | 使用 |
|
||
|---|---|
|
||
| 组件/页面 | `@ComponentV2` |
|
||
| 组件内部状态 | `@Local` |
|
||
| 父→子输入 | `@Param` |
|
||
| 子→父输出/回调 | `@Event`（**不用 `@Link`**；需双向时用 `@Param` 的 `!!` 语法糖） |
|
||
| 类/模型可观察 | `@ObservedV2` 类 + `@Trace` 字段 |
|
||
| 跨层共享 | `@Provider` / `@Consumer` |
|
||
| 变化监听 | `@Monitor` |
|
||
| 全局会话 | `SessionStore`（`@ObservedV2` 单例，见 `common/state/SessionStore.ets`） |
|
||
| 轻量持久化 | `PersistenceV2.globalConnect(...)`；结构化数据后续用 relationalStore(RDB) |
|
||
|
||
**核心约定**：ViewModel 是 `@ObservedV2` 类，持有 `@Trace` 的 `data/loading/error` 三态；页面只读状态、调方法，不直接碰 Repository / 网络层。
|
||
|
||
---
|
||
|
||
## 5. 网络与数据层
|
||
|
||
### 5.1 网络层（`common/src/main/ets/network/`）
|
||
|
||
- `HttpClient`：封装 `@kit.NetworkKit` 的 http，统一超时/请求头，支持**拦截器链**。
|
||
- `HttpInterceptor`：拦截器接口（`onRequest` / `onResponse`）。
|
||
- `AuthInterceptor`：请求前注入 `Authorization: Bearer <token>`；401 时清空会话。
|
||
|
||
### 5.2 鉴权流程
|
||
|
||
```
|
||
请求 → AuthInterceptor.onRequest 注入 token → 发出
|
||
→ AuthInterceptor.onResponse 检查 401
|
||
→ (当前) 清空 SessionStore，由上层跳登录
|
||
→ (TODO) token 刷新 + 原请求重放（防并发刷新），需后端 refresh 接口约定后实现
|
||
```
|
||
|
||
### 5.3 Repository 模式
|
||
|
||
- `data/repository/` 中定义**抽象类契约**，ViewModel 只依赖契约，实现可替换（真实 / mock）。
|
||
- 用抽象类而非 interface，是为了在 `ServiceLocator` 中做 `Object → 契约` 强转时兼容 ArkTS。
|
||
- `data/api/` 返回 DTO，Repository 负责 **DTO → 领域模型** 映射。
|
||
|
||
### 5.4 统一响应与错误
|
||
|
||
- `ApiResult<T>`：`{ code, message, data }`，`code === 0` 为成功。
|
||
- `ApiError`：区分网络异常 / HTTP 状态码 / 业务错误码。
|
||
|
||
---
|
||
|
||
## 6. 横切关注点
|
||
|
||
### 6.1 依赖注入
|
||
|
||
`di/ServiceLocator.ets`：`Map<string, Object>` 单例注册表。启动时在 `EntryAbility.onCreate` 注册 `HttpClient`、各 Repository、`SessionStore`；业务侧 `get(key)` 后强转。
|
||
|
||
> ArkTS 无反射，用字符串 key + 显式强转；若后续规模增大可引入类型安全的 key 常量或轻量注入容器。
|
||
|
||
### 6.2 导航
|
||
|
||
`Navigation` + `NavPathStack`（官方推荐，替代旧 Router）。`RouteMap.ets` 定义路由名常量与 `name→页面` 分发；`AppRouter` 持有全局 `NavPathStack` 提供 `push/replace/pop/popToName/clear`。HAR 不承载路由。
|
||
|
||
### 6.3 日志
|
||
|
||
`common/logging/Logger.ets`：封装 `hilog`，统一 DOMAIN，后续可加等级开关/上报。
|
||
|
||
### 6.4 持久化
|
||
|
||
- `PersistenceV2`：轻量 KV（token / 用户偏好），`@Trace` 字段自动落盘。
|
||
- `relationalStore(RDB)`：结构化数据（订单、列表缓存等），后续引入。
|
||
|
||
---
|
||
|
||
## 7. 编码规范
|
||
|
||
1. **状态管理只用 V2**：新组件一律 `@ComponentV2`，禁止混入 V1 装饰器。
|
||
2. **单向数据流**：父→子用 `@Param`，子→父用 `@Event`；页面不直接改 ViewModel 之外的全局状态。
|
||
3. **页面只编排**：`pages/` 下只做组件组合与 ViewModel 调用，业务逻辑进 ViewModel，数据进 Repository/Api。
|
||
4. **跨模块引用走 `Index.ets`**：entry 只 `import { ... } from 'common'/'uikit'`，不直接引 HAR 内部路径。
|
||
5. **魔法值收敛到 `uikit/theme/Theme.ets`**：颜色/间距/字号统一取 token。
|
||
|
||
---
|
||
|
||
## 8. 演进指南
|
||
|
||
### 8.1 抽取 feature HAR（业务领域明确后）
|
||
|
||
当某个业务领域（如订单、支付）足够独立时，新增 `feature_xxx` HAR：
|
||
|
||
```
|
||
feature_order/
|
||
├── src/main/ets/{model,data,viewmodel,view,pages}
|
||
└── oh-package.json5 (name: feature_order, main: Index.ets)
|
||
```
|
||
|
||
- 根 `build-profile.json5` 的 `modules` 增加该模块。
|
||
- 依赖它的模块在其 `oh-package.json5` 增加 `"feature_order": "file:../feature_order"`。
|
||
- 依赖方向：`entry → feature_xxx → common/uikit`，禁止 feature 之间横向依赖（确实需共享时下沉到 `common`）。
|
||
|
||
### 8.2 迁移到 feature-first
|
||
|
||
当 feature 数量增多、单层目录过深时，可将 `model/data/viewmodel/view/pages` 按 feature 重组：
|
||
|
||
```
|
||
ets/features/<feature>/{model,data,viewmodel,view,pages}
|
||
ets/shared/… # 跨 feature 共享
|
||
```
|
||
|
||
迁移原则：先把稳定边界抽 HAR，再在 HAR 内部做 feature 分组。
|
||
|
||
---
|
||
|
||
## 9. 调研结论摘要与引用
|
||
|
||
- 官方 MVVM（StateManagement V2）指南给出 `model/viewmodel/view/pages` 分层。
|
||
- 官方三层工程结构：commons（禁止反向依赖）/ features / products（不可横向调用），打包形态 HAR/HSP/Feature HAP/Entry HAP。
|
||
- V2 装饰器映射：`@State→@Local`、`@Prop→@Param`、`@Link→@Param+@Event`、`@Observed→@ObservedV2+@Trace`、`@Watch→@Monitor`、`AppStorage→AppStorageV2`、`PersistentStorage→PersistenceV2`。
|
||
- V1/V2 不可混用（编译错误）；API 19+ 提供 `UIUtils.enableV2Compatibility/makeV1Observed` 放宽混合约束。
|
||
|
||
主要引用：
|
||
|
||
- https://developer.huawei.com/consumer/en/doc/harmonyos-guides/arkts-mvvm-v2
|
||
- https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/arkts-decorator-overview
|
||
- https://device.harmonyos.com/en/docs/apiref/harmonyos-guides/arkts-v1-v2-update-difference
|
||
- https://github.com/openharmony/docs（arkts-v1-v2-migration-application / mixusage / inner-component）
|
||
- https://github.com/OpeNopEn2007/arkts-patterns
|
||
|
||
---
|
||
|
||
## 10. 边界与后续
|
||
|
||
- 本次为**骨架级**交付，未实现真实后端对接与具体业务（保留示例链路）。
|
||
- 未新增 feature HAR（无业务领域），仅写入抽取指南。
|
||
- 未做多设备适配（已确认仅 phone）。
|
||
- 后续待办：token 刷新策略、RDB 持久化、自动化测试基建、环境配置注入（BASE_URL）。
|