HarmonyOS 应用开发

📖 OfficeFlow README.md✓ 标记已学

一个 HarmonyOS 企业办公示例工程：覆盖登录鉴权 / 审批流 / 消息通知 / 多端协同四条主链路， 用一套真实可跑的多模块骨架，把"模块怎么分、状态怎么管、错怎么传、跨设备怎么同步"讲清楚。

这个工程不是 Hello World 集合，而是一份带取舍说明的参考实现： 每个关键设计都写了"为什么这样做"和"不这样做会踩什么坑"，注释里出现的反例都是真实踩过的。

---

1. 技术基线

项	值	说明
运行时	HarmonyOS 7.0
API 版本	API 26.0.0	compileSdkVersion / targetSdkVersion
兼容下限	6.0.0(20)	compatibleSdkVersion，即最低可安装系统版本
模型	Stage 模型	全工程无 FA 模型
IDE	DevEco Studio 26.0.0
状态管理	仅 V2	@ComponentV2 / @ObservedV2 / @Trace / @Local / @Param / @Computed / @Monitor
导入风格	仅 @kit.*	禁止 @ohos.* 分命名空间导入
构建	hvigor（hvigorw）

兼容下限与能力门禁

compatibleSdkVersion 是 6.0.0(20)，而 compileSdkVersion 是 26.0.0 —— 这个组合意味着 可以调用 API 21~26 的新接口，但必须在运行期确认设备支持。

本工程的纪律是：业务代码里不允许裸写 canIUse，一律经 lib_base 的 CapabilityGate 收口。 原因写在 lib_base/src/main/ets/gate/CapabilityGate.ets 的注释里，简单说三条：

1. 判断分散在各处时，升级 SDK 后无法一次性找出哪些是"新能力"；
2. 裸写 canIUse 容易只在支持分支写逻辑，忘了降级分支，在旧设备上静默失败；
3. 需要统一捕获 canIUse 自身可能抛出的异常。

已登记的能力字符串见 Capability 常量类（通知、RDB、分布式数据同步、分布式设备管理、网络栈、Web）。

---

2. 模块依赖图

                          ┌────────────────────────────────────────────┐
                          │   entry（HAP，唯一可安装入口）              │
                          │   持有唯一 NavPathStack + 路由表分发        │
                          └───────────────┬────────────────────────────┘
                                          │ 依赖所有 feature 与部分 lib
             ┌────────────────────────────┼────────────────────────────┐
             ▼                            ▼                            ▼
   ┌──────────────────┐        ┌──────────────────┐        ┌──────────────────┐
   │ feature_login    │        │ feature_approval │        │ feature_message  │
   │ （登录鉴权）      │        │ （审批流）        │        │ （消息与通知）    │
   └────────┬─────────┘        └────────┬─────────┘        └────────┬─────────┘
            │                           │                           │
            │                  ┌────────┴─────────┐                 │
            │                  ▼                  │                 │
            │        ┌──────────────────┐         │                 │
            └───────►│ feature_collab   │◄────────┘                 │
                     │（多端协同）       │                           │
                     └────────┬─────────┘                           │
                              │                                     │
   ┌──────────────────────────┴─────────────────────────────────────┴──────┐
   │                        能力库层（lib_*，不感知业务）                    │
   │                                                                       │
   │  lib_ui(HSP)   lib_router   lib_storage   lib_distributed   lib_network│
   │  lib_auth                                     lib_log                 │
   └──────────────────────────────────┬────────────────────────────────────┘
                                      ▼
                     ┌────────────────────────────────┐
                     │ lib_base（契约与工具，零依赖）   │
                     │ Result / AppError / JsonReader │
                     │ CapabilityGate / UiState / Paged│
                     └────────────────────────────────┘

规则（由 scripts/check-deps.mjs 自动校验，违规直接 CI 失败）：

规则	允许	违反后的症状
feature → lib	✅	—
lib → feature	❌ 禁止	改一个 feature 导致多个 lib 重编译，且 lib 无法单测
feature ↔ feature（横向）	❌ 禁止	两个 feature 互相 import，任一模块无法被删除或复用
lib_base → 任何模块	❌ 禁止	底层契约被业务污染，"公共库"再也不公共
依赖环	❌ 禁止	模块无法独立编译与单测
依赖未在 build-profile.json5 注册的模块	❌ 禁止	构建期报错位置离原因很远
同层 lib ↔ lib	⚠️ 慎用	仅允许指向更稳定的 lib，脚本给警告

feature 之间要跳转怎么办：只依赖 lib_router 的路由名常量，不 import 对方的页面。 例如 feature_message 跳到审批详情：

import { RouteNames, Router } from 'lib_router';
import type { ApprovalDetailParam } from 'lib_router';

// 参数键名必须逐字匹配 ApprovalDetailParam（id + from，两者都必填）
const param: ApprovalDetailParam = { id: message.relatedId, from: RouteNames.MESSAGE_LIST };
Router.push(RouteNames.APPROVAL_DETAIL, param);

这把"跳转"从代码依赖降级为契约依赖（只依赖路由名），运行时由路由表解析到具体页面。

---

3. 目录结构

office-flow/
├── AppScope/                     # 应用级配置（bundleName / versionCode / versionName）
│   ├── app.json5                 #   ← scripts/inject-version.mjs 会改写版本号
│   └── resources/
├── hvigor/                       # 构建工具链配置
├── build-profile.json5           # ★ 工程级构建配置：modules 注册 + product + 签名（刻意留空）
├── oh-package.json5              # ★ 工程级依赖（本工程的脚本无需任何 npm 依赖，见第 7 节）
├── hvigorfile.ts                 # 工程级构建入口（appTasks）
│
├── entry/                        # HAP：唯一入口 + 唯一 NavPathStack
│   └── src/main/
│       ├── module.json5
│       ├── ets/
│       │   ├── entryability/EntryAbility.ets     # 生命周期 + 窗口尺寸监听 + onNewWant 深链
│       │   ├── init/AppInitializer.ets           # 应用级初始化编排（同步段 / 延迟段）
│       │   ├── pages/Index.ets                   # Navigation 根容器 + route_map 构建函数
│       │   └── state/WindowState.ets             # 断点状态（应用级唯一来源）
│       └── resources/base/profile/route_map.json  # ★ 系统路由表（纯字符串，靠脚本兜住）
│
├── feature_login/                # HAR：登录鉴权
├── feature_approval/             # HAR：审批流（列表 / 详情 / 发起）
├── feature_message/              # HAR：消息与通知  ← 本工程新增
├── feature_collab/               # HAR：多端协同    ← 本工程新增
│
├── lib_ui/                       # HSP：公共组件与主题（AppButton/AppEmpty/AppDialog/Theme/断点）
├── lib_base/                     # HAR：契约与工具（Result/AppError/JsonReader/CapabilityGate）★最底层
├── lib_auth/                     # HAR：会话与令牌
├── lib_network/                  # HAR：rcp 封装 + 拦截器链 + Mock 基建
├── lib_storage/                  # HAR：Preferences / RDB / 文件
├── lib_log/                      # HAR：日志 / 打点 / 埋点 / 脱敏
├── lib_router/                   # HAR：路由名常量（RouteNames）+ Router 门面
├── lib_distributed/              # HAR：设备管理 / 草稿同步通道 / 合并算法 / 权限
│
├── scripts/                      # ★ 构建与 CI 脚本（详见第 6 节）
│   ├── check-deps.mjs            #   模块依赖图校验
│   ├── check-banned-api.sh       #   禁用 API 扫描
│   ├── banned-api.list           #   禁用 API 白名单（当前为空）
│   ├── check-route-map.mjs       #   路由表校验
│   ├── inject-version.mjs        #   版本号 / IS_RELEASE 注入
│   ├── setup-signing.sh          #   生成本地签名配置片段
│   └── ci.sh                     #   一条命令跑完整流水线
│
├── signature/                    # 签名材料目录（内容全部被 .gitignore 忽略）
│   └── README.md                 #   ★ 必须读：证书从哪来、怎么配、怎么排错
│
├── server/                       # 本地假后端（可选，默认走 Mock 不需要它）
│   ├── mock-server.js            #   零依赖 Node 假后端，支持 ?simulate= 故障注入
│   └── README.md                 #   启动方式、接口清单、与拦截器级 Mock 的分工
└── build-artifacts/              # CI 归档产物（.gitignore 忽略）

---

4. 如何运行

4.1 默认路径：Mock 模式，无需后端

工程默认环境是 MOCK（lib_base/src/main/ets/const/AppConst.ets 的 EnvConfig.CURRENT）。 此时所有 HTTP 请求都被 lib_network 的 MockInterceptor 拦下， 用各模块注册的规则返回数据 —— 不出网、不需要后端。

# 1) 用 DevEco Studio 26.0.0 打开工程根目录
# 2) 等待首次 Sync 完成（hvigor 会下载依赖，需要联网）
# 3) 选择 entry 模块 → 运行到模拟器或真机

首次 Sync 会下载 hvigor 与 ohpm 依赖，需联网。之后可离线构建。

4.2 切到真实后端

改 lib_base/src/main/ets/const/AppConst.ets 里的 EnvConfig.CURRENT：

static readonly CURRENT: Env = Env.PROD;   // 或 DEV / STAGING

同时起本地假后端（可选）：

PORT=3000 node server/mock-server.js    # 端口被占用时用 PORT 换一个
# 然后访问 http://127.0.0.1:3000/approval/list 验证服务已起

mock-server.js 支持 故障注入：任意接口追加 ?simulate=timeout|500|401|403|404|429|slow|malformed|raw-array， 可在真实链路上演练超时、鉴权失效、非法 JSON 等分支。接口清单与演示数据见 server/README.md。

注意：切到非 Mock 环境后，各模块的 *MockRules 不会被注册 （AppInitializer.initMock() 里有 if (!EnvConfig.isMock()) return;）—— 这条判断是刻意保留的，"生产包里带了一份能返回假数据的规则"是最难排查的一类事故。 为防止这条依赖人工记忆的规则失效，scripts/inject-version.mjs 增加了 发布环境门禁：打 release 包时若 EnvConfig.CURRENT 仍是 MOCK/DEV/STAGING， 直接 exit 1 中断（scripts/ci.sh 的第 6 阶段会调用它）。确实要出演示包时显式加 --allow-mock-in-release。

4.3 常用命令

# ---- 静态检查（不需要 DevEco，几秒钟出结果，提 PR 前先跑这个）----
node scripts/check-deps.mjs                 # 模块依赖图
bash scripts/check-banned-api.sh            # 禁用 API
node scripts/check-route-map.mjs            # 路由表
SKIP_BUILD=1 bash scripts/ci.sh             # 上面三个一起跑

# ---- 构建（需要 hvigorw，即 DevEco 环境）----
./hvigorw clean --no-daemon                 # 清理增量缓存
./hvigorw --sync --no-daemon                # 解析模块图与依赖
./hvigorw assembleHap --mode module -p product=default -p buildMode=debug
./hvigorw assembleApp -p product=default -p buildMode=release -p signingConfig=default
bash scripts/ci.sh                          # 完整流水线（检查 + debug 包 + 归档）
bash scripts/ci.sh --release                # 额外产出 release 包（需签名环境变量）

# ---- 辅助 ----
bash scripts/check-banned-api.sh --list-patterns   # 查看启用中的规则
node scripts/inject-version.mjs --help             # 版本注入用法
bash scripts/setup-signing.sh --help               # 签名配置用法

产物位置：entry/build/.../outputs/default/*.hap（debug）、 build/outputs/default/*.app（release）；scripts/ci.sh 会把它们统一归档到 build-artifacts/。

---

5. 签名说明

签名材料（.cer / .p7b / .p12）必须由开发者自行申请， 且已被 .gitignore 忽略。口令（keyPwd / storePassword）只应存在于两个地方： 开发者的 DevEco 配置、CI 的 Secret 存储。

• 完整说明：signature/README.md —— 三种配置方式、签名失败的排查顺序；
• 构建流水线与环境变量：docs/11/08-build-ci.md；
• 生成不含口令的配置片段：bash scripts/setup-signing.sh。

工程的 build-profile.json5 刻意留了 "signingConfigs": []， 就是为了让"谁在本地填了签名配置"这件事显式地体现为一次文件改动，从而不会误提交。

---

6. 构建脚本与 CI 门禁

scripts/ 下的六个脚本按"守什么"分类：

脚本	守住的规则	为什么需要它
check-deps.mjs	模块依赖方向、无依赖环、lib_base 零依赖、依赖已注册	模块化规则写在文档里没有约束力；一次赶进度的横向 import 就能把两个 feature 焊死，而编译、打包、运行都不报错
check-banned-api.sh	无 @ohos.* 分命名空间导入、无 @ohos.router/@ohos.net.http、无 PersistentStorage、无 V1 状态装饰器	混用 V1/V2 状态机制是"莫名其妙不刷新"的最大来源；V1 装饰器与 V2 只差一个字符，人眼在 Review 里抓不住
check-route-map.mjs	pageSourceFile 文件真实存在、buildFunction 以 RouteBuilder 结尾、路由名不重复	路由表全是字符串，没有任何编译期保护；拼错的现象是白屏（无异常、无日志、无堆栈）
inject-version.mjs	版本号与 EnvConfig.IS_RELEASE 由构建流程写入	IS_RELEASE 是编译期常量，控制日志级别与 Mock 的编译期剪裁。靠"开发者记得改"必然出现 release 包残留 debug 分支
setup-signing.sh	签名配置生成，口令绝不落盘	手改 build-profile.json5 补签名，是"密钥被提交"的最短路径
ci.sh	把上面五件事按固定顺序串起来	顺序本身有价值，见下文

ci.sh 的阶段顺序（顺序本身就是设计）

[1] hvigorw clean        ← 清掉增量缓存，让"构建成功"只反映当前源码
[2] hvigorw sync         ← 解析模块图与依赖，配置错误在这一步先暴露
[3] check-deps.mjs       ┐
[4] check-banned-api.sh  ├ 三项静态检查，几秒钟，全部在编译之前
[5] check-route-map.mjs  ┘
[6] assembleHap (debug)  ← 不需要签名，QA 与自测的日常产物
[7] inject-version.mjs   ← 仅 release：注入版本号与 IS_RELEASE
[8] assembleApp (release)← 仅 release：签名从环境变量注入，缺任一直接失败
[9] 归档到 build-artifacts/

两条关键理由：

1. 静态检查全部前置。它们加起来几秒钟，而一次 assembleHap 要几十秒到几分钟。 把便宜且"必然确定"的检查放前面，反馈时间从分钟级压到秒级， 而且失败原因更精确（"依赖违规"和"编译错误"的排查路径完全不同）。
2. debug 包在前、release 包在后。debug 不需要签名、更快、失败率更低； release 需要签名材料与版本注入，证书匹配、Profile 有效期都可能出问题。 把高失败率的步骤放后面，让大部分错误在便宜阶段被拦掉。

ci.sh 用 set -e + ERR trap，任一阶段失败即中断并打印阶段名与耗时 —— set -e 只会静默退出，日志里看到的是"最后一条正常输出之后什么都没了"， 那是最难用的失败信息。

---

7. 关于 rcp 适配点（重要）

整个工程只有 lib_network/src/main/ets/rcp/RcpClient.ets 中的 RcpTransport 直接调用 rcp API。

这一点可以用一行命令验证：

grep -rln "@kit.RemoteCommunicationKit" --include=*.ets .
# → ./lib_network/src/main/ets/rcp/RcpClient.ets

所以：如果 SDK 版本导致 rcp 的签名差异，只需要改这一个类。

设计上是刻意这么做的：

• rcp 的接口在不同 SDK 版本之间有过微调（方法名、参数形状、异常类型）；
• 业务层与上层拦截器只面对 lib_network/src/main/ets/model/HttpTypes.ets 里定义的 自有契约（RequestOptions / NetResponse / RetryPolicy / CancelToken）， 完全看不到 rcp 的类型；
• 于是升级 SDK 时，改动面被限制在一个文件里，而不是散落在所有发请求的地方。

RcpTransport 里还写明了两个最容易踩的坑：

1. headers 必须每次请求传入，不能写进 Session 配置。 Session 复用时 SessionConfiguration 的 headers 会被固化， token 刷新之后仍会发送旧头 —— 这是 rcp 最隐蔽的坑；
2. 异常归一化。rcp 抛出的错误要在这里一次性翻译成 AppError， 否则 ErrorCode 体系会被击穿，UI 层拿不到稳定的错误码。

---

8. 与教程章节的对照

教程章节	对应工程内容	关键文件
00-before-you-start.md	环境准备与工程定位	本 README、scripts/check-deps.mjs 的前置说明
01-environment-toolchain.md	工具链、build-profile.json5、oh-package.json5、依赖形态（HAR/HSP）	根 build-profile.json5、各模块五件套
02-arkts-core.md	严格模式、类型系统、错误模型、显式契约	lib_base：Result / AppError / JsonReader
03-arkui-layout.md	布局、组件封装、主题与断点	lib_ui；feature_message/view/MessageListPage.ets
04-routing-lifecycle.md	Navigation、NavPathStack、route_map.json、深链、onNewWant	entry/pages/Index.ets、lib_router、feature_*/router/*.ets
05-state-management.md	V2 状态管理：@ObservedV2/@Trace/@Computed/@Monitor、LazyForEach 数据源	feature_message/viewmodel/、feature_collab/viewmodel/、entry/state/WindowState.ets
06-persistence-network.md	存储选型（Preferences/RDB/KVStore/文件）、rcp、拦截器链、重试与取消、Mock	lib_storage、lib_network、feature_message/repo/、feature_collab/repo/
07-distributed.md	设备发现、分布式同步、逐字段合并与冲突处理、应用级订阅	lib_distributed、feature_collab/（尤其 service/DraftSyncService.ets 的类注释）
08-performance.md	列表性能、冷启动分段、打点、埋点缓冲	lib_log：Trace / Analytics；entry/init/AppInitializer.ets 的同步段/延迟段切分
09-modularization.md	模块划分、依赖规则、稳定依赖原则、依赖门禁	scripts/check-deps.mjs、lib_base/Index.ets 的导出纪律
10-testing-release.md	单元测试、签名、打包	signature/README.md、scripts/setup-signing.sh、scripts/inject-version.mjs
11/08-build-ci.md	CI 流水线与产物流转	scripts/ci.sh
appendix/A-v1-v2-cheatsheet.md	V1 → V2 装饰器对照	scripts/check-banned-api.sh 的 v1-state-decorator 规则
appendix/B-deprecated-and-gates.md	废弃 API 与版本门槛	lib_base/gate/CapabilityGate.ets、scripts/check-banned-api.sh
appendix/C-glossary.md	术语表（HAR/HSP/HAP、软总线、KVStore、rcp…）	—
appendix/D-mock-server.md	Mock 的三种方案对比与规则表设计	lib_network/mock/MockRegistry.ets、feature_*/mock/*MockRules.ets

四个 feature 模块的实现位置

模块	内容	入口文件
feature_login	登录、会话建立、令牌刷新触发	Index.ets → src/main/ets/view/
feature_approval	审批列表 / 详情 / 发起提交（幂等键）	Index.ets → src/main/ets/view/
feature_message	消息列表、已读状态、本地轻量缓存、通知发布与点击跳转	src/main/ets/view/MessageListPage.ets
feature_collab	设备发现、草稿同步、冲突裁决	src/main/ets/view/CollabDevicePage.ets

---

9. 工程约定（提交前自查）

必须

• 4 空格缩进；公开签名显式类型标注；公开 API 禁止 any；
• 资源走 $r()，尺寸用 vp / fp；
• 状态管理一律 V2；跨模块跳转一律走 lib_router 的路由名常量；
• 模块五件套与 lib_base / lib_network 保持一致： harTasks / module.json5 里 "type": "har" / 无 abilities 段；
• 需要权限的模块在 requestPermissions 里声明并给 reason（资源引用，不是裸字符串）；
• Index.ets 禁止 export * —— 只导出稳定契约（页面 / 路由构建函数 / Mock 规则）。

禁止

• @ohos.* 分命名空间导入（一律 @kit.*）；
• @ohos.router（用 lib_router）、@ohos.net.http（用 lib_network 的 rcp 封装）；
• FA 模型；
• V1 状态装饰器（@State / @Prop / @Link / @Observed / @ObjectLink / @Provide / @Consume / @Watch / @StorageLink / @StorageProp / @LocalStorageLink / @LocalStorageProp / @Track）；
• PersistentStorage（用 lib_storage）；
• 手改 AppScope/app.json5 的版本号或 AppConst.ets 的 IS_RELEASE（用 scripts/inject-version.mjs）；
• 提交 signature/ 下的任何签名材料或口令。

前四项、以及最后两项都有脚本兜底（见第 6 节）。

关于根 oh-package.json5 的 devDependencies

根 oh-package.json5 只声明了 @ohos/hypium 与 @ohos/hamock（单元测试用），本工程刻意未改动它：

scripts/ 下的全部脚本零 npm 依赖，只使用 Node 内置模块 （node:fs / node:path / node:process / node:url）与 bash 内置能力。

为什么坚持零依赖：

1. 这些脚本要在 CI 的最小镜像里跑。每多一个依赖，就要多一步 npm install， 而"构建前的检查"卡在装依赖上是很难接受的成本；
2. 校验脚本本身如果依赖了一个被校验的工程才能提供的包，就会形成循环依赖；
3. 读 build-profile.json5 / oh-package.json5 需要处理注释与尾逗号（JSON5）， 为此引入 json5 包是最常见的诱惑 —— 但代价是脚本生命周期绑定了第三方包的版本。 本工程自己实现了位置保持的注释剥离（见 check-deps.mjs 的 stripComments）， 注释与尾逗号处理在 30 行内完成，且能顺便保护字符串里的 //（如 https://）。

因此：不需要给根 oh-package.json5 添加任何 devDependencies。

---

10. 已知限制与后续方向

限制	现状	后续
单元测试	工程已声明 hypium，示例测试待补	见 docs/10-testing-release.md
埋点上报	ConsoleUploader 只打印日志	换成真实通道实现 EventUploader 接口即可，调用点不动
草稿远端同步	本工程走服务端中转（见 feature_collab/repo/DraftRepository.ets 的说明）	纯软总线方案（KVStore + DataObject）见 docs/07-distributed.md
协同的设备筛选	DeviceHub 返回同账号全部在线设备	可加"按能力筛选"（是否有输入法、屏幕尺寸）
服务端	server/ 是可选假后端	仅用于脱离 Mock 时联调

---

11. 快速上手（TL;DR）

# 只想跑静态检查（不需要 DevEco）
SKIP_BUILD=1 bash scripts/ci.sh

# 想看依赖图长什么样
node scripts/check-deps.mjs

# 想配签名
cat signature/README.md

用 DevEco Studio 打开工程 → Sync → 运行 entry。默认 Mock 模式，无需后端。

📖 signature/ —— 签名材料目录 README.md✓ 标记已学

本目录下的 .cer / .p7b / .p12（含 .p12.bak）一律不进版本库。 根目录的 .gitignore 已经忽略它们，请不要用 git add -f 强行加入。

为什么这些文件必须"开发者各自申请"

HarmonyOS 应用要装到真机（或用 release 模式出包）就必须签名。签名的三个输入 不是可以随代码一起分发的东西：

文件	是什么	从哪来	泄漏的后果
*.cer	应用证书	AppGallery Connect → 证书、App ID 和 Profile → 申请证书	配合私钥可伪造应用签名
*.p7b	签名 Profile（含包名、证书指纹、ACL 权限）	AppGallery Connect → Profile 管理 → 申请调试/发布 Profile	可被用来给同名包签名并安装
*.p12	密钥库（含私钥）	DevEco Studio 首次申请证书时生成并保存	私钥一旦泄漏等同于应用身份被接管
*.p12.bak	密钥库备份	自行备份	同上

私钥丢失不可找回。 丢了只能重新申请证书，并存量用户的覆盖升级会断链。 所以密钥库一定要在安全的地方单独备份（本目录里的 .bak 只是为了方便本地开发， 它同样被 gitignore 忽略）。

本地开发怎么配签名（三种方式）

A. 用 DevEco Studio（推荐）

File > Project Structure > Signing Configs → 勾选自动签名或手工填写 → IDE 会把配置直接写进根 build-profile.json5。

注意：写完之后 build-profile.json5 会变成"已修改"状态。 不要提交这份改动 —— 提交上去等于把密钥库路径与加密口令一起入库。 （本工程的 build-profile.json5 刻意留了 "signingConfigs": []，就是为了让这一点显式。）

B. 用脚本生成片段（不含口令）

export APP_CERT_FILE=/abs/path/to/officeflow.cer
export PROFILE_FILE=/abs/path/to/officeflow.p7b
export KEYSTORE_FILE=/abs/path/to/officeflow.p12
export KEY_ALIAS=officeflow
bash scripts/setup-signing.sh

生成 build-profile.signing.local.json5（该文件也已被忽略）。 把它里面的 signingConfigs 数组合并进根 build-profile.json5， 口令字段需要你自己补 —— 脚本刻意不写口令，因为"写进去就会被提交"是个只差一次的赌注。

C. CI（口令完全不落盘）

口令从 CI 的 Secret 存储以环境变量注入，通过 hvigor 命令行参数传入：

./hvigorw assembleApp -p buildMode=release -p signingConfig=default \
  -p appCertFile="$APP_CERT_FILE" \
  -p profileFile="$PROFILE_FILE" \
  -p keystoreFile="$KEYSTORE_FILE" \
  -p keyAlias="$KEY_ALIAS" \
  -p keyPwd="$KEY_PWD" \
  -p keystorePwd="$KEYSTORE_PWD"

scripts/ci.sh --release 已经封装了这条命令，并在缺少任一环境变量时直接失败—— "构建成功但没有签名"的包比构建失败更危险，它会被误当成可用产物发出去。

排查签名失败

签名报错通常很含糊，按这个顺序查最快：

1. 路径：三个文件路径是不是相对路径 / 写错了。scripts/setup-signing.sh 会先帮你校验存在性；
2. Profile 有效期：调试 Profile 有有效期（通常 90 天），过期后必须重新申请；
3. 包名一致性：AppScope/app.json5 的 bundleName 必须与 Profile 里登记的包名一致；
4. 证书指纹：Profile 绑定的证书指纹必须与 .cer 匹配 —— 换了证书就要重新申请 Profile；
5. 签名算法：本工程使用 ECC 密钥（SHA256withECDSA）。若你用的是 RSA 证书，改成 SHA256withRSA。

更完整的环境搭建与流水线说明见 docs/11/08-build-ci.md。

📖 server — 本地假后端（可选） README.md✓ 标记已学

它解决什么问题

工程默认走拦截器级 Mock（lib_network 的 MockInterceptor + 各模块的 *MockRules）， 优点是快、不出网、不需要后端。但它有两件事验证不了：

1. 真实 HTTP 行为 —— 状态码、重定向、超时、大响应体分片、连接复用；
2. 两端契约一致性 —— 拦截器 Mock 的响应也是我们自己写的，写错了两边一起错。

mock-server.js 就是补这一课：它是一个零依赖的 Node HTTP 服务， 用与客户端同一份契约（统一响应包装 code/message/data/traceId）返回数据， 但走的是真实网络栈。

启动

node server/mock-server.js                  # 默认端口 3000
PORT=8080 node server/mock-server.js        # 端口被占用时换一个

3000 是很多本地服务（含 VS Code 插件、其它示例工程）的默认端口， 起不来时先换端口，而不是怀疑脚本。

怎么让应用连上它

1. 把 lib_base/src/main/ets/const/AppConst.ets 的 EnvConfig.CURRENT 改为 Env.DEV；
2. 把 EnvConfig.baseUrl() 中 Env.DEV 的地址改成 http://<你的电脑局域网IP>:3000；
3. 不要写 localhost / 127.0.0.1 —— 那是设备自己的回环地址，不是你的电脑。

如果确实想用回环地址（例如通过端口转发）：

hdc rport tcp:3000 tcp:3000
# 之后应用侧可以用 127.0.0.1:3000

演示数据

项	值
登录账号	demo
登录密码	demo1234
审批单总数	120 条（另含 5 条边界数据）
消息总数	57 条（未读混排）
待审批数	13

接口清单

方法	路径	说明
POST	/auth/login	密码错返回 HTTP 200 + 业务码 40000
POST	/auth/refresh	refreshToken 需以 rt_ 开头，否则 HTTP 401
POST	/auth/logout	总是成功
GET	/user/profile	用户信息
GET	/approval/list	分页 + status / keyword 过滤
GET	/approval/list/pending	更长前缀，用于演示「最长前缀优先」
GET	/approval/detail?id=	支持 __401__ / __500__ / __notfound__ / __drift__
POST	/approval/submit	读 Idempotency-Key 头；标题含「重复」或键含 dup 时返回 40901
POST	/approval/withdraw	回显撤回后快照
POST	/approval/decide	id=conflict 时返回 40901
GET	/approval/count	角标统计
GET	/message/list	分页
GET	/message/list/empty	空列表
GET	/message/unreadCount	未读数
POST	/message/read / /message/readAll	标记已读
GET	/collab/devices	2 台设备（1 在线 1 离线）
GET	/collab/devices/none	零设备（未组网/不同账号）
POST	/collab/draft/push	回显服务端归一化后的记录
GET	/collab/draft/pull	返回与本地时钟相同的字段 → 可触发冲突裁决

魔法 keyword（GET /approval/list）

keyword	效果
__empty__	空列表（total=0）
__overflow__	分页越界（items=[]、hasMore=false）
__edge__	仅返回 5 条边界数据

__edge__ 的 5 条数据是刻意构造的，用于验证客户端解析的健壮性：

id	构造的问题	期望的客户端行为
AP90001	缺 applicantDept / amount	用默认值渲染，不崩溃，记一条解析 WARN
AP90002	amount 是字符串 "1280.50"、urgent 是 1、时间是 ISO 字符串	JsonReader 兼容转换
AP90003	标题与正文超长	列表项截断；长文本不参与局部刷新
AP90004	status 是客户端未支持的枚举值	降级显示为「未知状态」而非空白
AP90005（id 为空）	主键缺失	整条丢弃，不渲染幽灵行

故障注入

任意接口追加 ?simulate=：

值	效果	用于验证
timeout	不响应，让客户端超时	NET_TIMEOUT、重试与退避
500	HTTP 500	服务端错误归一化、可重试判定
401	HTTP 401	单飞刷新 + 重放 + 强制登出
403	HTTP 403	无权限提示
404	HTTP 404	资源不存在
429	HTTP 429	限流 + 重试
slow	延迟 3 秒	骨架屏、加载态、慢请求告警
malformed	返回非法 JSON	PARSE_FAILED 分支
raw-array	data 段直接是数组	非统一包装响应的兼容

示例：

curl -s -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:3000/approval/list?simulate=500"   # 500
curl -s "http://127.0.0.1:3000/approval/list?keyword=__edge__" | head -c 200
curl -s -X POST http://127.0.0.1:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"account":"demo","password":"demo1234"}'

一个刻意的设计：业务失败用 HTTP 200

/auth/login 密码错误时返回的是 HTTP 200 + 业务码 40000，而不是 HTTP 400。 原因是客户端的 HttpStatusMapper 会先把非 2xx 状态归一化成通用错误， HTTP 400 会让业务码信息丢失，UI 只能给出「请求失败」这种无用提示。 所以业务失败走业务码，传输/鉴权失败才用 HTTP 状态码 —— 这条约定必须在前后端之间说清。

边界说明

• 数据全部在内存中，重启即复位（没有持久化，也没有并发保护）；
• 不校验 Authorization 头（真后端要校验，这里只用于跑通链路）；
• 不模拟网络抖动与连接中断，需要这些场景请用 ?simulate=timeout。

相关文档

• 拦截器级 Mock 的规则表设计 → ../../docs/appendix/D-mock-server.md
• 网络层与错误处理 → ../../docs/11/02-network-result-error.md
• 审批链路的数据流与缓存策略 → ../../docs/11/05-approval-flow.md

📄 第 0 章 学习准备 00-before-you-start.md✓ 标记已学

这一章不写代码，只解决三件事：把版本名词对齐、把全书术语统一、确认你的环境能跑起来。跳过它的人，通常会在第 1 章或第 6 章被版本问题绊住。

---

0.0 本章目标

1. 能准确说清 HarmonyOS 系统版本 / 开发套件版本 / API 版本 / SDK 版本 四者的关系，不再被 6.0.0(20) 和 26.0.0 两种写法绕晕。
2. 能独立判断"我手上的教程/博客内容能不能用"，依据是其编写时的 API 版本。
3. 能完成本机环境自检，产出一份可归档的版本清单。
4. 能说清本教程的三种标注（术语 / 版本门槛 / 误区）与统一的源码组织方式。
5. 能定位官方文档中真正权威的入口，而不是靠搜索博客。

---

0.1 版本体系：四个容易混淆的概念

0.1.1 它们分别是什么

概念	含义	谁决定	例子
系统版本	用户手机上跑的操作系统版本	华为发布节奏	HarmonyOS 7.0
开发套件版本	官方打包发布的一整套（IDE + SDK + 命令行工具）	与系统版本同期	26.0.0
API 版本	开发者可调用的接口集合版本	与开发套件同步	26.0.0
SDK	实现上述 API 的库与编译工具链，随 DevEco Studio 预置	与开发套件同步	HarmonyOS SDK 26.0.0

术语：API 版本 ≠ 系统版本。一个 API 版本对应一代系统能力，但同一代系统在不同机型上可能推送节奏不同。判断"某个 API 能不能用"，看 API 版本与设备实际系统，不看营销名称。

术语：开发套件（Developer Suite）是官方对"IDE + SDK + 命令行工具"这个整体的称呼。教程里说"升级到 26.0.0"，指的是把这三样一起升到 26.0.0，而不是只换 IDE。

0.1.2 版本号格式的断代（关键）

从 API 26.0.0 起，版本号格式发生了一次断代式变更：

时代	格式	例子	括号里的数字
API 26 之前	X.Y.Z(N)	6.0.0(20)	N 是 OpenHarmony 底座的 API Level
API 26 起	X.Y.Z	26.0.0	不再有括号

新格式的语义：

• X（主版本）：大量新功能与重要变更，可能包含 API 修改，需要适配。26.0.0 就是一次主版本。
• Y（次版本）：新增功能，原则上向后兼容。
• Z（修订版本）：修问题与小幅改进，向后兼容。

0.1.3 本教程的版本策略

采用主版本 = 26、兼容下限 = 20 的双轨策略：

编写基线（targetSdkVersion）: 26.0.0   ← 用得上新能力，且能对上官方最新文档
兼容下限（compatibleSdkVersion）: 6.0.0(20)  ← 覆盖 HarmonyOS 6.0 及以上主力设备

这意味着：全书主线写法都必须在 API 20 设备上能跑。凡是用到 API 21~26 新增能力的知识点，都会标 > 版本门槛：API 26 新增，并给出降级方案。

术语：兼容下限（compatibleSdkVersion）是应用声明"最低支持到哪个 SDK"。低于此版本的设备无法安装。它不决定编译期能否引用较新 API——引用超出下限的 API 是否报错，由 compileSdkVersion 与 IDE 检查决定；真正的失败发生在低版本设备的运行期。

0.1.4 如何判断一份外部资料是否可用

看三样，缺一不可：

1. API 版本（不是系统营销名，而是 API 号）。低于 API 12 的资料大概率是 FA 模型或过渡期写法，默认放弃。
2. 是否使用 @ohos.* 分命名空间导入。这是最有效的"年代指纹"——import http from '@ohos.net.http' 说明是老写法。
3. 是否出现 @State / @Prop / @Link。出现即为 V1 状态管理，可作参考但不要照抄到新项目。

---

0.2 全书术语统一

以下术语全书含义固定，不再重复解释（完整版见 附录 C）：

术语	一句话定义
ArkTS	HarmonyOS 应用开发语言，TypeScript 的静态化子集，去掉了动态特性以获得确定性与性能
ArkUI	声明式 UI 框架，UI 是状态的函数（UI = f(state)）
Stage 模型	当前应用模型。核心是 UIAbility + WindowStage，替代已废弃的 FA 模型
HAP	可安装的应用包，一个应用可有多个 HAP
HAR	静态共享库，随调用方一起打包，可独立发布到 ohpm
HSP	动态共享库，多 HAP 运行时共享一份代码与资源，可减小包体
Ability	应用对外能力的抽象单元；UIAbility 是带界面的那类
Context	应用/模块的上下文，是访问资源、沙箱、系统能力的入口；生命周期长于页面，慎持有
断点	窗口宽度的档位（xs/sm/md/lg/xl/xxl 六档），多端适配的判断依据
拦截器	在请求发出前/响应返回后插入的处理环节，用于注入鉴权、日志、错误映射、重试
Result	本教程的错误处理模型：用 Success / Failure 类判别替代异常穿越分层
Mock 模式	用本地假数据替换真实后端，使工程无后端也能跑通

---

0.3 环境自检清单

在进入第 1 章前，请确认：

• [ ] DevEco Studio 版本为 26.0.0 Release（Help > About DevEco Studio 可查）
• [ ] HarmonyOS SDK 版本与 IDE 匹配（Help > About HarmonyOS SDK）
• [ ] SDK Platforms 中已勾选 HarmonyOS SDK（API 26） 与至少一个设备类型（Phone）
• [ ] SDK Tools 中已安装 Command Line Tools、Toolchains、Emulator
• [ ] 本机 Node.js 版本满足 IDE 要求（DevEco 26 自带受管 Node，不要用系统 Node 覆盖）
• [ ] ohpm / hvigorw 可在终端执行（路径由 IDE 注入，或用 IDE 内置终端）
• [ ] 已注册并登录华为开发者账号（后续签名与上架必须，建议现在办）
• [ ] 本地具备可用的模拟器镜像或真机（hdc list targets 能看到设备）
• [ ] 工程所在路径不含中文与空格（这是新手最常踩的构建失败原因）

把自检结果记下来，后续章节遇到"本地能跑、别人跑不了"时，第一件事就是对比这份清单。

自检脚本

# 建议在 DevEco Studio 的内置终端执行，确保环境变量已注入
node -v
ohpm -v
hvigorw -v
hdc list targets

把输出贴到你的项目 README 里。CI 上跑出不一致结果时，这份记录能省下几个小时。

---

0.4 本教程的三种标注

> 术语

给出概念的一句话定义。只在首次出现时标注，完整定义收在附录 C。

> 版本门槛

形如：

版本门槛：API 26 新增。在兼容下限 20 上不可用，须用 deviceInfo.sdkApiVersion 分档或 CapabilityGate（1.5.3）判定后降级；canIUse 仅适用于 SystemCapability 维度的能力缺失场景。

看到这个标注，就意味着这段代码不能无条件写进业务逻辑。

> 误区

形如：

误区：错误写法 → 正确写法，外加一句"为什么错"。

每章至少 3 条，全部来自真实踩坑，不写凑数的常识。

---

0.5 源码组织约定

第 11 章工程 code/office-flow/ 内的模块命名与依赖方向，全书统一：

entry（HAP，唯一可安装入口）
  └── feature_*（HAR，业务特性）
        └── lib_*（HAR，能力库，不感知业务）
              └── lib_base（HAR，最底层契约与工具）
lib_ui（HSP，公共组件与主题，只依赖 lib_base）

命名约定：

对象	约定	例子
页面文件	XxxPage.ets	ApprovalListPage.ets
组件文件	名词，无后缀	ApprovalCard.ets
ViewModel	XxxViewModel	ApprovalListViewModel
仓储	XxxRepository	ApprovalRepository
数据源	XxxRemoteDs / XxxLocalDs	ApprovalRemoteDs
路由名常量	XxxRoute	ApprovalRoute.LIST
导出面	每个 HAR 只有根 Index.ets	feature_approval/Index.ets

代码风格：4 空格缩进、显式类型标注、const 优先、公开签名禁止 any、资源一律 $r() 引用。

---

0.6 权威文档入口

优先顺序如下，遇到分歧以第一项为准：

1. 官方文档（developer.huawei.com/consumer/cn/doc/） — 指南 + API 参考
2. 版本说明与升级适配指导 — "向 26.0.0 升级"这类文档，是判断行为变更的唯一权威
3. DevEco Studio 变更说明 — 工具链行为变化（构建、预览、检查项）
4. 社区文章 — 只用来找思路与踩坑经验，代码一律回官方文档核对

---

0.7 本章小结

记住三句话就够用：

1. API 版本决定能力边界，compatibleSdkVersion 决定你能不能编译通过，targetSdkVersion 决定系统按哪套行为对待你。
2. 代码特征比发布时间更可靠地指示新旧：@ohos.* 与 @State 是两个最灵敏的年代指纹。
3. 主线写法必须在 API 20 上能跑，新能力一律走标注 + 降级。

---

0.8 延伸阅读

• 官方文档 → 版本说明 → HarmonyOS 开发套件版本列表（确认当前最新版与配套 IDE）
• 官方文档 → 版本说明 → 应用升级适配指导（向 26.0.0 升级）（行为变更与适配清单）
• 官方文档 → 应用开发导读 → HarmonyOS 应用开发基础知识（Stage 模型整体视图）
• 本教程 README 的「版本基线」与「章节路线图」

---

0.9 常见误区

误区 1：以为版本号格式变更只是"改个写法"

错误写法

"compatibleSdkVersion": "26.0.0"   // 或手敲 "20"，追求"简洁"

正确写法

"compatibleSdkVersion": "6.0.0(20)"   // 让 DevEco Studio 生成后再改数值，不手敲字符串

为什么错：配置里同时存在两种格式的版本号，且它们不能互转。compatibleSdkVersion 指向 API 20 时就必须写 6.0.0(20)——"20" 或 "26.0.0" 都无法表达底座号，会导致安装下限解析失败。

误区 2：用"文章发布时间"判断资料新旧

错误写法

只看"发布于 2026 年"就照抄示例代码。

正确写法

看代码特征：@ohos.* 分命名空间导入、@State / @Prop / @Link 出现即为旧写法（见 0.1.4）。

为什么错：发布时间近但内容是旧代码转载的博客非常多。看代码特征，不看发布时间。

误区 3：用系统安装的 Node.js 去跑 hvigorw

错误写法

在系统终端直接执行 hvigorw / ohpm 命令做构建。

正确写法

项目命令一律在 IDE 内置终端执行；CI 里显式使用 Command Line Tools 附带的 Node。

为什么错：DevEco Studio 自带受管 Node，版本与构建工具链严格绑定；用系统 Node 常导致 EBADENGINE 或构建工具版本不匹配。

误区 4：用搜索引擎解决"API 是否存在"

错误写法

搜"xxx API 能不能用"并直接采信搜索结果。

正确写法

只查官方 API 参考与版本说明（见 0.6 的优先顺序）。

为什么错：搜索结果的时效性不可控，且常混合多个版本。判断 API 是否可用、在哪个版本可用、参数是什么，只看官方 API 参考。

---

0.10 实践任务

任务：完成环境自检并产出可归档的版本清单

任务描述

1. 按 0.3 的环境自检清单逐项检查本机环境（IDE / SDK / 设备类型 / 命令行工具 / Node / 开发者账号 / 模拟器或真机 / 工程路径）。
2. 在 DevEco Studio 内置终端执行 0.3 的自检脚本，完整留存四条命令的输出。
3. 把检查结果整理成一份环境版本清单，归档到你的项目 README（或团队知识库）。

验收 checklist

• [ ] 0.3 清单每一项都已勾选，或写明不满足的原因与补救计划
• [ ] node -v / ohpm -v / hvigorw -v / hdc list targets 的输出已原样留存
• [ ] 清单含 IDE / SDK / Node / ohpm / hvigor / 设备六项版本
• [ ] 工程所在路径不含中文与空格（截图或路径记录为证）
• [ ] 清单已提交到项目 README 或团队知识库

交付物清单

交付物	形式	验收点
环境版本清单	Markdown	六项版本齐全，与 0.3 清单一一对应
自检脚本输出	文本留存	四条命令原样输出，他人可复现比对

---

下一章：第 1 章 环境搭建与工具链

📄 第 11 章 项目总览 00-overview.md✓ 标记已学

前 10 章讲的是"每一块怎么做对"，这一章开始讲"把它们拼起来之后还会出什么问题"。工程 code/office-flow/ 是一个可直接打开、可直接跑的多模块项目，覆盖登录鉴权 / 审批流 / 消息通知 / 多端协同四条链路。本章先给出它的定位、范围与取舍记录，再给出可执行的验收方法——读完你应当能自己判断"这个工程能给我什么、不能给我什么"。

---

0.0 本章目标

1. 能说清 OfficeFlow 的功能范围边界：哪些是完整实现、哪些是骨架、哪些刻意留空，并能解释每一处"留空"的原因。
2. 能复述全部 14 条关键选型决策的「决策 / 备选 / 理由 / 代价」，知道每条决策换来的是什么、付出的是什么。
3. 能跑通工程：DevEco Studio 26.0.0 打开 → sync → 运行 entry，默认 Mock 模式下完成一次登录、看一次列表、触发一次错误分支。
4. 能切换运行环境：从拦截器级 Mock 切到 server/mock-server.js 提供的本地真实 HTTP 后端，并说清两种模式各自能验证什么。
5. 能验收：用本章的清单逐项打勾，把"看起来在跑"变成"有证据地能跑"。

---

0.1 项目定位与功能范围

0.1.1 它是什么

OfficeFlow 是一个带取舍说明的参考实现，不是一组 Hello World。它的价值在于三件事：

它提供	具体形态
一套无环的 13 模块骨架	12 个 HAR/HSP + 1 个 HAP，依赖方向由脚本强制（见 scripts/check-deps.mjs）
一套可复制的分层与错误模型	View → ViewModel → Repository → DataSource，全链路返回 Result<T>，异常不出数据层
一套可复现的错误与边界演练入口	Mock 规则支持按输入触发 401 / 40100 / 40901 / 503 / 字段缺失，无需改代码即可演练分支

术语：拦截器级 Mock ── 本工程默认的假数据方案。它挂在 lib_network 的拦截器链第 3 位，命中后连网络都不出，直接构造响应。与"起一个假后端"是两件不同的事，见 0.2 第 7 条。

0.1.2 四条主链路：诚实的实现程度标注

工程 README 声称覆盖四条链路，但覆盖度并不相同。下表是逐项核对代码后的结论，请以它为准：

链路	实现程度	依据（真实文件）	缺什么
登录鉴权	✅ 完整	lib_auth/repo/AuthRepository.ets（真实经 HttpApi 发请求）、token/TokenStore.ets（Preferences 落盘）、token/TokenRefresher.ets（单飞刷新）、session/SessionStore.ets + session/LogoutBus.ets、lib_router/interceptor/RouteInterceptor.ets（登录拦截）	无。仅账号体系是单一的"账号密码"，无验证码 / 三方登录
审批流	✅ 完整	feature_approval：列表（SWR + LazyForEach）、详情、发起（幂等键）、撤回、审批（通过 / 驳回）；datasource/ApprovalLocalDs.ets 走 RDB 缓存	无流程编排引擎（不支持多级会签 / 条件分支），状态机只有 5 个态
消息通知	⚠️ 链路完整，通道需真机确认	feature_message/view/MessageListPage.ets、repo/MessageRepository.ets、service/NotificationService.ets；已读状态本地维护	通知授权与横幅展示必须在真机/模拟器上人工确认；推送（远程推送）不在范围内
多端协同	⚠️ 完整但需两台真机	lib_distributed：device/DeviceHub.ets（设备发现）、sync/DraftSyncChannel.ets、merge/DraftMerge.ets（逐字段合并 + 冲突裁决）；feature_collab 的草稿协同 UI	模拟器上分布式能力不可靠；DraftRepository 的草稿远端同步走服务端中转，不是纯软总线（README「已知限制」已声明）

0.1.3 刻意留空的部分（不要误以为是漏写）

项	现状	为什么刻意这样
签名配置	根 build-profile.json5 里 "signingConfigs": []	让"谁在本地填了签名配置"显式体现为一次文件改动，避免误提交（见 signature/README.md）
单元测试	声明了 @ohos/hypium / @ohos/hamock，示例测试待补	测试的分层与写法在第 10 章；本工程聚焦架构，不重复堆测试样例
埋点上报通道	lib_log 的 Analytics 默认用 ConsoleUploader（只打印）	上报通道是业务相关实现；换掉 EventUploader 的实现即可，调用点一行不动
真实后端	server/mock-server.js 是零依赖假后端	本章要验证的是"契约与错误处理"，不是真实业务数据
混淆	根 build-profile.json5 中 obfuscation.enable = false，各模块 buildOptionSet.release 中为 true	两处口径不一致，属待收敛项：以模块级配置为准，见 0.6 误区 3
多语言	仅 base + en_US 两份 string.json	多语言产物会放大包体，示例不需要

误区：把"示例工程"当成"可直接上线的业务底座"。它解决的是结构问题（分层、依赖、错误、可观测），不解决业务完备性（流程引擎、权限模型、风控）。照搬结构可以，照搬功能范围会漏需求。

0.1.4 关键文件速查

排障时最常"想不起来在哪"的十几个位置，先抄在这里：

你想要的	去哪
环境与域名切换	lib_base/src/main/ets/const/AppConst.ets（EnvConfig.CURRENT / baseUrl() / IS_RELEASE）
错误码与用户文案	lib_base/src/main/ets/error/AppError.ets（ErrorCode / AppErrorKind / AppError）、AppConst.ets 的 UserMessages
Result 与组合子	lib_base/src/main/ets/result/Result.ets、result/ResultExt.ets
请求契约（不含 rcp 类型）	lib_network/src/main/ets/model/HttpTypes.ets（RequestOptions / NetResponse / RetryPolicy / CancelToken / BizCode）
唯一 rcp 适配点	lib_network/src/main/ets/rcp/RcpClient.ets（RcpTransport + RcpClient.execute）
拦截器与顺序	lib_network/src/main/ets/rcp/NetInterceptor.ets、rcp/interceptors/*.ets
Mock 规则表	lib_network/src/main/ets/mock/MockRegistry.ets + 各模块 mock/*MockRules.ets
日志 / 埋点 / 打点 / 脱敏	lib_log/src/main/ets/log/XLogger.ets、analytics/Analytics.ets、analytics/EventModel.ets、trace/Trace.ets、mask/Masker.ets
登录 / 令牌 / 会话 / 登出广播	lib_auth/src/main/ets/{repo, token, session}/（AuthRepository / TokenRefresher / TokenStore / SessionStore / LogoutBus）
路由名与参数契约	lib_router/src/main/ets/const/RouteNames.ets
唯一允许碰 NavPathStack 的地方	lib_router/src/main/ets/facade/Router.ets
断点状态（应用级唯一来源）	entry/src/main/ets/state/WindowState.ets
启动编排（同步段 / 延迟段）	entry/src/main/ets/init/AppInitializer.ets
路由表与分发	entry/src/main/resources/base/profile/route_map.json + entry/src/main/ets/pages/Index.ets 的 destBuilder
门禁脚本	scripts/check-deps.mjs、scripts/check-banned-api.sh、scripts/check-route-map.mjs、scripts/ci.sh
本地假后端	server/mock-server.js

---

0.2 技术选型决策记录（ADR）

格式：决策 / 备选 / 选择理由 / 代价。"代价"一栏是这份记录最重要的部分——没有代价的决策通常意味着还没想清楚。

#	决策	备选	选择理由	代价
1	状态管理全量 V2（@ComponentV2/@ObservedV2/@Trace/@Local/@Param/@Computed/@Monitor）	V1（@State/@Prop/@Link/@Watch）	V1 的 @Watch 只能挂在被装饰变量上、拿不到变化前后值；V2 的 @Monitor 能拿到 monitor.value()?.before/now，本工程的状态变迁埋点直接依赖它（ApprovalListViewModel.onStateChanged）。V2 还支持 @Computed 缓存派生值，列表页 pendingCount 靠它避免渲染期遍历	社区资料一半是 V1，必须靠 scripts/check-banned-api.sh 的 v1-state-decorator 规则兜住；团队成员要重新建立直觉
2	网络用 rcp（@kit.RemoteCommunicationKit）	@ohos.net.http	rcp 有 Session 概念（连接池与配置复用）、分阶段超时（connectMs/transferMs）、原生拦截器与 toJSON()/toString() 便捷方法；@ohos.net.http 每次请求独立、无会话与拦截器，鉴权注入与重试只能散落在调用处	rcp 在不同 SDK 版本间有过签名微调，必须设唯一适配点（本工程收敛到 RcpTransport，见第 2 条 ADR 与 2.1 节）
3	路由用 Navigation + NavPathStack + 系统路由表	@ohos.router	@ohos.router 已废弃；Navigation 支持系统路由表（route_map.json）、NavDestination 生命周期（onShown/onHidden，曝光与停留埋点的正确口径就挂在这里）、以及"页面栈由根容器唯一持有"的确定性	路由表是纯字符串配置，无编译期保护，必须补 scripts/check-route-map.mjs 门禁；页面必须显式承载 NavDestination
4	lib_ui 用 HSP，其余库用 HAR	全部 HAR；或全部 HSP	公共组件与主题存在跨 HAP 共享的全局单例语义（主题状态、AppStorageV2 实例）。HAR 在多 HAP 场景下会被复制成多份实例，"单例"会退化成"每份一个"，表现为状态时好时坏；HSP 在设备上只有一份	HSP 与依赖方必须同签名同 bundle，不能跨应用复用，也不便调试（改 HSP 要重装宿主）；首启有一次加载开销。因此只在"被 ≥2 个 HAP 引用"时才值得
5	全局态用 AppStorageV2 承载（SessionStore / LogoutBus / WindowState）	静态单例字段；V1 AppStorage；@Provider/@Consumer	断点、会话与登出广播是跨页面、随窗口的状态，而页面经路由动态挂载（NavDestination 不在同一棵组件树上），@Provider 覆盖不到。AppStorageV2.connect(类, key, creator) 按"类型 + key"返回同一实例，且只观测 @Trace 字段，正好是这种场景	必须把状态建模成类（原始值无法被观测）；key 手写会静默创建第二个实例，因此 key 一律走常量（SESSION_STORE_KEY / LOGOUT_BUS_KEY）；connect 的 creator 只在首次执行，构造函数里不能放"必须执行一次"的副作用
6	错误用 Result 类判别，不用异常穿越分层	抛异常 + 各层 try/catch；{ ok: boolean, data?, error? } 联合类型	异常在签名上看不出来，调用方不 catch 也能编过；Result<T> 把"可能失败"变成编译期类型信息。类继承判别让 instanceof Success 分支内 value 必然存在，避免布尔判别下"访问了不存在的 data"	每个调用点都要显式处理两个分支（本工程用 Results.fold/valueOrUndefined/errorOrUndefined 收敛写法）；异常只允许存在于 DataSource 内部并由拦截器翻译成 AppError
7	Mock 走拦截器链，不放假后端函数桩	直接替换 DataSource 实现；起一个本地 HTTP 假服务	拦截器级 Mock 在链的第 3 位（Auth → Logging → Mock → ErrorMap → Retry），它前面的鉴权注入与日志脱敏、它后面的错误映射与重试全部照常执行——即"开了 Mock 不会绕过整条链路"。直接替换 DataSource 会让拦截器逻辑完全不被覆盖	验证不了真实 HTTP 行为（状态码、重定向、超时、分片），也验证不了两端契约一致性。所以 server/mock-server.js 不是冗余，而是补这一课（见 0.3.5）
8	关闭 HAP 产品拆分，改用运行时断点	为手机 / 平板 / PC 各建一个 product（或各建一个 HAP）	形态差异（列数、分栏、字号）在本工程里都是能用运行时判定的东西：WindowState 监听窗口尺寸 → Breakpoints.ofWidth → bpOf() 取档位值。用 product 拆分会产出多份需要分别测试与上架的包，产物数量直接乘上测试成本	必须保证断点只有一个来源（EntryAbility.onWindowStageCreate 唯一注册 windowSizeChange），页面一律只读 WindowState；一旦有页面自己注册监听，就会出现"A 页分栏、B 页单栏"
9	登出广播用计数器，不用布尔	isLoggedOut: boolean	布尔是"电平信号"，同一状态重复置位不产生变化：登出 → 置 true → 用户重新登录（若某条路径忘了复位）→ 新令牌再失效时置 true 不触发，表现为"卡在主页、请求全 401、界面毫无反应"。计数器是"边沿信号"，每次登出都 +1，连续两次登出也一定触发，且不需要复位（复位本身就是漏 bug 的地方）	消费方必须监听具体属性路径（@Monitor('logoutBus.logoutEpoch')），V2 下路径上每一层都要可观测
10	签名材料绝不入库	把 .p12/.cer/.p7b 与口令一起提交，方便"开箱即用"	三者合起来就是完整的应用签名权：仓库可见者能签出与正式包签名一致的包用于分发或提审，且这类泄漏无法通过改密码挽回	每个开发者要自己申请证书（走 signature/README.md 与 scripts/setup-signing.sh）；CI 必须注入 6 个环境变量，缺任一直接失败
11	幂等键在"用户点击提交"时生成一次，重试复用	每次发请求时生成；只靠服务端防重	若每次请求都生成，则"提交超时（服务端其实已成功）→ 用户点重试 → 带新键 → 服务端认为是第二次提交 → 两张审批单"。在点击时生成、重试复用同一个键，才真正覆盖"网络层重发"与"用户重复点击"两种场景；且客户端生成能保证键在网络重试前后不变	页面必须自行管理键的生命周期：成功了要清、内容改了要重置（内容变了就是另一个业务动作，复用旧键会被服务端按 40901 直接拒掉）
12	rcp 适配点收敛到单一类	在业务与各拦截器里直接调用 rcp API	rcp 的接口在不同 SDK 版本间有过微调。收敛后，升级 SDK 的改动面是一个文件里的三个方法（见 2.1），而不是散落在所有发请求的地方；业务与拦截器只面对 lib_network/model/HttpTypes.ets 里的自有契约（RequestOptions/NetResponse/RetryPolicy/CancelToken），完全看不到 rcp 的类型	多一层间接（RcpTransport），排查"这个参数到底传给谁了"要多跳一次
13	重试策略分级下放，且默认不重试	全局统一重试；按 HTTP 方法判定	幂等性由业务语义决定而非 HTTP 方法：ApprovalRemoteDs 里 list/detail/count 显式声明 idempotent: true + defaultIdempotentRetry()，submit/withdraw/decide 显式声明 idempotent: false + noRetry()。RequestOptions.idempotent 默认 false，默认安全	每个新接口都要"选择"一次策略，忘记选等于不重试（安全但可能少一次自愈机会）
14	Index.ets 只导出稳定契约，禁止 export *	export * 图省事	export * 会把内部实现一次性变成公共契约，之后任何内部重构都是破坏性变更，且无法回答"这个模块对外提供了什么"。本工程还刻意不导出 ApprovalModule（DI 装配点）与 viewmodel/repo/datasource，防止使用方绕过页面直接调仓储	新增一个对外能力要手改 Index.ets；有时需要"再导出一层类型"（如 lib_network/Index.ets 里的 export type { ... }）

术语：ADR（Architecture Decision Record） ── 把"我们选了什么、为什么不选别的、为此付出什么"记成一条可检索的记录。它的价值在半年后：当时的代价开始显现时，你能分清"这是预期内的代价"还是"选错了"。

0.2.1 三条贯穿全工程的取舍主线

14 条决策不是并列的清单，它们收敛在三条主线上。读代码时如果只记住三件事，记这三条：

主线一：把"可能出错的地方"变成"类型上必须处理的地方"。 Result<T> 替代异常（第 6 条）、UiState 判别式替代 loading/error 两个布尔、RequestOptions.idempotent 显式声明代替默认重试（第 13 条）、Parser<T> 强制每个接口提供具名解析器。共同点是：不依赖开发者记得处理，而是让"忘记处理"在编译期就过不去。

主线二：把"变化的东西"从"固定的东西"里剥出来。 变量头（Authorization）从 Session 配置剥到每次 Request 的 headers；可变参数从 URL 常量剥到 RequestOptions；跨 feature 跳转从代码依赖剥成 RouteNames 字符串契约（第 14 条与第 2 章 1.6）；rcp 的版本差异剥到单一适配点（第 12 条）。共同点是：变化被限制在可枚举的少数位置。

主线三：把"约束"从文档搬进脚本。 依赖方向 → scripts/check-deps.mjs；范式（禁 V1 / 禁 @ohos.*） → scripts/check-banned-api.sh；路由表字符串 → scripts/check-route-map.mjs；版本号与 IS_RELEASE → scripts/inject-version.mjs。共同点是：写在文档里的规则没有约束力，一次赶进度的 import 就能把它破掉，而编译、打包、运行都不会报错。

误区：只抄第 1~14 条的具体选择，不抄这三条主线。具体选择会随 SDK 版本过时（比如 rcp 换成别的网络库），主线不会。

---

0.3 运行与验收

0.3.1 用 DevEco Studio 打开并运行（默认路径）

# 1) 用 DevEco Studio 26.0.0 打开工程根目录（不是某个模块目录）
#    D:/Documents/tencent/workbuddy/learning/HarmonyOS-doc/code/office-flow
# 2) 等待首次 Sync 完成（hvigor 与 ohpm 依赖需要联网下载）
# 3) 选择 entry 模块 → 选择模拟器或真机 → Run

工程的默认环境是 MOCK（lib_base/src/main/ets/const/AppConst.ets 的 EnvConfig.CURRENT 默认值为 Env.MOCK），此时所有请求都被 MockInterceptor 拦下，不出网、不需要后端。

0.3.2 默认 Mock 的演示账号（以 lib_auth 的 Mock 规则为准）

以 lib_auth/src/main/ets/mock/AuthMockRules.ets 为唯一依据（server/mock-server.js 的口径与之一致）：

/** 登录成功的固定账号（见 docs/appendix/D-mock-server.md 的演示账号表） */
const MOCK_ACCOUNT: string = 'demo@officeflow.com';
const MOCK_ACCOUNT_ALIASES: string[] = ['demo', 'demo@officeflow.com', '13800000000'];
const MOCK_PASSWORD: string = 'demo1234';

输入	结果
账号 demo / demo@officeflow.com / 13800000000，密码 demo1234	登录成功（HTTP 200 + code: 0）
密码随便填错	HTTP 200 + 业务码 40000 → ErrorCode.BIZ_FAILED，页面显示"账号或密码错误"
账号不在别名表里	同上（40000）

关键细节：密码错误的 Mock 返回的是 HTTP 200 + 业务码非 0，而不是 HTTP 400。原因写在规则注释里：ErrorMapInterceptor 先判 HTTP 状态码，HTTP 400 会被 HttpStatusMapper 归一化成 UNKNOWN，业务码 40000 就丢了，UI 也就无法区分"账号不存在"与"网关抽风"。

0.3.3 真机验证协同的条件

多端协同（lib_distributed + feature_collab）有硬性前置条件，缺一条就只能看到空设备列表：

• [ ] 两台真实设备，登录同一个华为账号，且在同一局域网 / 已建立可信连接
• [ ] 两台设备都已授予 ohos.permission.DISTRIBUTED_DATASYNC（entry/src/main/module.json5 已声明 reason 与 usedScene，运行时仍需用户同意）
• [ ] 两台设备都已开启蓝牙 / WLAN（软总线依赖其中之一）
• [ ] DeviceHub.start() 已被协同页面触发（本工程刻意不在启动时拉起设备发现，避免所有用户为不用的功能付出启动开销）

模拟器上分布式能力不可靠（见第 7 章误区 1），因此本章的协同验收一律以真机为准。

0.3.4 命令行构建与静态检查

# ---- 静态检查：不需要 DevEco，几秒钟出结果，提 PR 前先跑 ----
node scripts/check-deps.mjs                 # 模块依赖图（架构门禁）
bash scripts/check-banned-api.sh            # 禁用 API（范式门禁）
node scripts/check-route-map.mjs            # 路由表（字符串契约门禁）
SKIP_BUILD=1 bash scripts/ci.sh             # 上面三项一起跑

# ---- 构建：需要 hvigorw（即 DevEco 环境）----
./hvigorw clean --no-daemon                 # 清增量缓存，让"构建成功"只反映当前源码
./hvigorw --sync --no-daemon                # 解析模块图与依赖，配置错误在此先暴露
./hvigorw assembleHap --mode module -p product=default -p buildMode=debug
./hvigorw assembleApp -p product=default -p buildMode=release -p signingConfig=default
bash scripts/ci.sh                          # 完整流水线（检查 + debug 包 + 归档）
bash scripts/ci.sh --release                # 额外产出 release 包（需签名环境变量）

产物位置：entry/build/.../outputs/default/*.hap（debug）、build/outputs/default/*.app（release）；scripts/ci.sh 会把它们统一归档到 build-artifacts/。

版本门槛：API 26.0.0 起 compatibleSdkVersion 必须写成旧格式 6.0.0(20)，而 targetSdkVersion 写成新格式 26.0.0，两者格式不同且不可互转。手敲容易出错，先用 IDE 生成再改数值。

0.3.5 切到真实后端（本地假后端）

两步：改环境常量 + 起后端。

// lib_base/src/main/ets/const/AppConst.ets
static readonly CURRENT: Env = Env.DEV;   // 由 Env.MOCK 改为 Env.DEV / Env.STAGING / Env.PROD

static baseUrl(): string {
    switch (EnvConfig.CURRENT) {
        case Env.MOCK:
            return 'https://mock.officeflow.local';
        case Env.DEV:
            return 'https://dev-api.officeflow.example.com';   // ← 改成 http://<你的电脑IP>:3000
        // ...
    }
}

node server/mock-server.js              # 默认端口 3000
PORT=8080 node server/mock-server.js    # 3000 被占用时换端口（脚本读 process.env.PORT）

三个必须注意的点：

1. 不要用 localhost。模拟器/真机访问的是"设备自己的回环地址"，必须用宿主机的局域网 IP；或先做端口转发：hdc rport tcp:3000 tcp:3000，再用 127.0.0.1:3000。
2. 切到非 Mock 环境后，各模块的 *MockRules 一条都不会注册。AppInitializer.initMock() 里有 if (!EnvConfig.isMock()) { ... return; }，这条判断是刻意保留的——"生产包里带了一份能返回假数据的规则"是最难排查的一类事故。
3. EnvConfig.IS_RELEASE 由 scripts/inject-version.mjs 在构建前改写，不要手改（见第 4 章）。

0.3.6 错误分支与冲突的演练入口

这块是本章验收清单能打勾的前提。全部不需要改代码：

要演练的分支	触发方式	期望观测
密码错误（业务码 40000）	密码随便填错	页面提示"账号或密码错误"，日志里 biz error 40000
令牌过期（业务码 40100 → 单飞刷新 + 重放）	把 /user/profile 请求写成带 ?simulate=expired（Mock 规则认这个 query；也可把 PROFILE_TOKEN_EXPIRED_VARIANT 改为 true）	AuthInterceptor 识别 40100 → 置 retryPlan.requireRefresh → TokenRefresher.refreshToken() 只发一次 /auth/refresh → 重放成功
刷新彻底失败（HTTP 401 → 清会话 + 登出）	让 refreshToken 不是 rt_ 开头（Mock 规则据此返回 401）	清 TokenStore → SessionStore.reset() → LogoutBus.broadcast() → 根组件清栈并跳登录页
服务端错误（HTTP 5xx）	MockRegistry.setFailureRate(0.3)（或 Mock 规则注入 503）	幂等请求按 defaultIdempotentRetry() 重试最多 3 次；RetryInterceptor.backoff 有抖动
字段缺失（契约漂移）	把 LOGIN_MISSING_FIELD_VARIANT 改为 true	日志出现 parse issues WARN；AuthRepository.login 返回 PARSE_FAILED 而不是"密码错误"
重复提交（业务码 40901）	提交流程中重试（复用同一幂等键）	BizCode.DUPLICATE_SUBMIT → ErrorCode.BIZ_CONFLICT → 页面提示"该单据此前已提交成功，请到列表查看"
断网可用	关闭网络后进入审批列表	有本地缓存时正常展示并打降级 warn；无缓存才走错误页
窗口形态变化（断点）	在 PC / 折叠屏上拖动窗口	工作台卡片列数 1→2→3 变化；MainPage 底部断点行同步变化

0.3.7 第一次运行失败时的定位顺序

按这个顺序查，绝大多数问题在前三步就被拦住：

顺序	现象	先看哪里	判据
1	Sync 报红	oh-package.json5 的 file:../xxx 路径	路径必须指向真实存在的模块目录；node scripts/check-deps.mjs 能直接报出"依赖了未注册的模块"
2	编译过但"点了没反应"	route_map.json 的 name / buildFunction / pageSourceFile	三者与 Index.ets 的 destBuilder 分支、各模块 RouteBuilder 函数名必须逐字一致；node scripts/check-route-map.mjs 能报出
3	白屏且无日志	AppInitializer.runSync() 是否被调用、EnvConfig.CURRENT	首屏落地依赖 AppInitializer.sessionReady()；若 Promise reject，应用会永远停在启动占位页
4	所有请求 401 / 请求发出时没有 Authorization	AuthProviderInstaller.install() 是否在首个请求前执行	AuthInterceptor 用 AuthTokenRegistry.require()，未安装会抛异常（这是刻意的启动期配置错误）
5	Mock 不生效	EnvConfig.CURRENT 是否为 Env.MOCK、MockRegistry.enable(true) 是否被调用	MockInterceptor 的条件是 EnvConfig.isMock() && MockRegistry.isEnabled()，两个都真才命中
6	埋点/日志里没有断点档位	EntryAbility.attachWindowSizeListener 是否执行、WindowState.update 是否收到回调	PC 上拖动窗口时 MainPage 的断点行必须跟着变；不变说明监听没注册或没写进 WindowState
7	改了 HSP 里的组件但界面没变	是否重装了宿主 HAP	HSP 是随宿主安装的独立产物，产物更新后必须重装宿主；这是 HSP 相对 HAR 最容易被忽略的调试成本

---

0.4 验收清单

• [ ] node scripts/check-deps.mjs 退出码为 0，输出 13 个模块且无违规、无依赖环
• [ ] bash scripts/check-banned-api.sh 退出码为 0，输出中"白名单豁免次数"为 0（当前豁免清单为空）
• [ ] node scripts/check-route-map.mjs --require-file 通过，route_map.json 的 8 条路由与 Index.ets 的 destBuilder 分支一一对应
• [ ] ./hvigorw assembleHap --mode module -p product=default -p buildMode=debug 能产出 .hap
• [ ] DevEco Studio 26.0.0 打开工程后 Sync 无红字，entry 可运行到设备
• [ ] 用 demo / demo1234 能登录成功并落到主框架（RouteNames.MAIN）
• [ ] 用错误密码登录，页面显示"账号或密码错误"，且不是"网络异常"
• [ ] 登录后能进入审批列表并看到数据；下拉刷新后列表状态从 REFRESHING 回到 SUCCESS
• [ ] 触底加载更多可用；加载更多失败时保留已有数据且只在 footer 报错
• [ ] 断开网络后重进审批列表：有缓存时正常展示并出现降级提示，日志有 warn 级别的降级记录
• [ ] 断开网络后提交审批：界面明确失败，且本地数据未被标记为已提交（不做乐观更新）
• [ ] 在提交页连续两次点击提交：日志里 Idempotency-Key 相同，服务端只建一张单
• [ ] 触发 40100 分支：日志中 /auth/refresh 只出现 1 次（单飞生效），随后原请求被重放成功
• [ ] 触发 HTTP 401 刷新失败分支：应用清栈并回到登录页，重新登录后仍可正常使用
• [ ] 日志中搜索不到 Bearer、完整手机号 13800000000、password= 明文（脱敏的两个出口都生效）
• [ ] 在 PC / 折叠屏上拖动窗口：工作台卡片列数随断点变化，且只有一处注册了 windowSizeChange
• [ ] 两台同账号真机：协同设备页能看到对端设备（模拟器不作为验收环境）
• [ ] 冷启动时不闪登录页：已登录用户的 SessionStore 由磁盘快照回填（AppInitializer.sessionReady()）
• [ ] 退出登录后再用另一个账号登录：列表里不出现上一个账号的数据（clearCache() 被调用）

---

0.5 与教程前面章节的对应关系

教程章节	在本工程里的落地物	关键文件
00-before-you-start.md	环境准备与版本基线	根 build-profile.json5、工程 README.md
01-environment-toolchain.md	工具链、模块五件套、HAR/HSP 形态	各模块 oh-package.json5 / hvigorfile.ts / module.json5
02-arkts-core.md	严格模式、显式类型、错误模型	lib_base：Result / ResultExt / AppError / JsonReader
03-arkui-layout.md	组件封装、主题与断点	lib_ui（AppButton / AppTag / Theme / Breakpoints）
04-routing-lifecycle.md	Navigation、NavPathStack、系统路由表、深链	entry/pages/Index.ets、lib_router、各 feature 的 router/*.ets
05-state-management.md	V2 装饰器、@Computed、@Monitor、LazyForEach 数据源	feature_approval/viewmodel/、entry/state/WindowState.ets
06-persistence-network.md	存储选型、rcp、拦截器链、重试与取消、Mock	lib_storage、lib_network
07-distributed.md	设备发现、分布式同步、逐字段合并与冲突	lib_distributed、feature_collab
08-performance.md	冷启动分段、打点、埋点缓冲	lib_log 的 Trace / Analytics、entry/init/AppInitializer.ets
09-modularization.md	模块划分、依赖方向、门禁脚本	scripts/check-deps.mjs、各模块根 Index.ets
10-testing-release.md	签名、打包、上架	signature/README.md、scripts/setup-signing.sh、scripts/inject-version.mjs
本章（11/00~11/08）	工程整体落地与验收	全部

---

0.6 常见误区

误区 1：以为开了 Mock 就绕过了整条网络链路

错误认知：Mock 模式验证不了鉴权、日志、错误映射，所以错误分支要等接上真后端才能测。 实际情况：本工程的 Mock 挂在链的第 3 位（Auth → Logging → Mock → ErrorMap → Retry），Mock 只短路"最靠近网络的传输"这一层。因此鉴权头一样会注入、日志一样会脱敏输出、Mock 返回的假错误照样会被 ErrorMapInterceptor 归一化、RetryInterceptor 照样会按 retryable 决定是否重看重试。 为什么重要：这决定了你可以在纯本地把 401、5xx、40901、字段缺失这些分支全部走一遍（见 0.3.6）。反过来，如果你的 Mock 是"直接替换 DataSource"，那确实绕过了一切——那是另一种方案，不是本工程的。

误区 2：把 EnvConfig.IS_RELEASE 当运行时开关手改

错误写法：为了看详细日志，手动把 EnvConfig.IS_RELEASE 改成 false 然后打 release 包。 正确写法：用 node scripts/inject-version.mjs --release，它同时改写 AppScope/app.json5 的版本号与该字面量。 为什么错：IS_RELEASE 是编译期常量，控制日志级别的编译期剪裁。它一旦变成"开发者记得改"的字面量，release 包里残留 debug 分支只是时间问题；而且手改没有任何审计痕迹，出问题只能翻提交历史。

误区 3：混淆配置两处不一致时不知道以谁为准

现象：根 build-profile.json5 的 products[0].buildOption.arkOptions.obfuscation.enable 是 false，而各模块 build-profile.json5 的 buildOptionSet.release.arkOptions.obfuscation.ruleOptions.enable 是 true。 正确做法：以模块级配置为准（release 构建逐个模块读自己的 buildOptionSet），并尽快把根级那一处删掉或对齐，避免下一个人照着根配置推断出错误结论。 为什么错：配置冲突本身不会报错，只会让人做出错误判断。同一份配置语义在两个层级都存在时，一定要指定唯一权威来源。

误区 4：以为默认 Mock 就是"假数据能跑通功能"

错误认知：Mock 能返回数据，所以功能就算通了。 实际情况：Mock 验证的是分支可达性，不是契约一致性——Mock 响应也是我们自己写的，写错了两边一起错。真实 HTTP 行为（状态码、重定向、超时、大响应体分片）只有 server/mock-server.js 或真后端能验证。 正确做法：日常开发用拦截器级 Mock（快、不出网）；联调自测与发布前，切到 server/mock-server.js 再跑一遍主链路。

误区 5：把"能构建"当成"能交付"

错误认知：assembleHap 成功 = 工程健康。 实际情况：构建成功只证明语法与依赖解析没问题。本工程的三项静态检查（依赖图、禁用 API、路由表）守的是编译期看不见的三类问题：模块间横向依赖、V1/V2 混用、路由名拼错导致的白屏。它们加起来几秒钟，比一次 assembleHap 便宜两个数量级。 正确做法：把 SKIP_BUILD=1 bash scripts/ci.sh 当成提交前的固定动作。

误区 6：在页面或 ViewModel 里自己 new 依赖

错误写法：页面里 private readonly repo = new ApprovalRepositoryImpl(new ApprovalRemoteDs(...), new ApprovalLocalDs())。 正确写法：仓库通过装配点获取——ApprovalModule.repository()；ViewModel 一律由 ApprovalModule.listViewModel() / detailViewModel() 工厂产出。 为什么错（原文就在 feature_approval/src/main/ets/di/ApprovalModule.ets 的类注释里）：依赖图会被复制 N 份、单测无法替换实现、冷启动被拖慢。更隐蔽的是 ViewModel 必须是"每次新实例"：它持有页面级取消令牌，若被复用，第二次进入页面时令牌已是 cancelled，所有请求结果都会被丢弃——表现为"第二次进列表永远空白"，且极难定位。

误区 7：以为启动初始化"顺序无所谓"

错误认知：初始化步骤反正在 onCreate 里都会执行，先后没差别。 实际情况：AppInitializer.runSync() 的顺序有明确依据（理由写在每个 initXxx 上）：

AppInitializer.initLogging();           // 1. 日志要最早可用
AppInitializer.initAnalytics();         // 2. 埋点要在网络之前：登录/刷新请求也要被观测
AppInitializer.initAuthProvider();      // 3. 令牌提供者必须先于任何请求安装
AppInitializer.initRouteInterceptor();  // 4. 登录拦截器必须先于第一次跳转注册
AppInitializer.initMock();              // 5. Mock 必须在首个请求之前注册完
AppInitializer.initSession(context);    // 6. 会话恢复：发起即返回（不 await）

为什么错：顺序错了不会报错，只会"偶发"。把 initMock() 放到某个请求之后，那个请求就真的出网了；把 initRouteInterceptor() 放到首次跳转之后，就会出现"未登录也能进业务页"。

---

0.7 实践任务

任务：把 OfficeFlow 跑起来并完成一次完整的验收

阶段一：跑起来

1. 用 DevEco Studio 26.0.0 打开工程根目录，等 Sync 完成。
2. 运行 entry 到模拟器或真机，确认首屏是登录页（未登录状态）。
3. 用 demo / demo1234 登录，确认落到主框架。
4. 从工作台进入审批列表 → 点进详情 → 发起一次审批 → 返回列表确认新单据在列表里。

阶段二：把错误分支走一遍

5. 用错误密码登录一次，记录页面提示与日志（应当是业务码 40000，不是"网络异常"）。
6. 触发 /user/profile?simulate=expired，在日志里数 /auth/refresh 的出现次数（应当是 1）。
7. 断网后重进审批列表，确认有缓存时正常展示并出现降级提示。
8. 断网后提交审批，确认本地数据未被标记为已提交。

阶段三：切换环境

9. 起 node server/mock-server.js（端口被占用时用 PORT=8080）。
10. 把 EnvConfig.CURRENT 改为 Env.DEV，并把 Env.DEV 的 baseUrl 改成 http://<你的电脑IP>:端口。
11. 重新运行，确认请求真的出网（服务端控制台有日志），并复现一次 ?simulate=500。

阶段四：收口

12. 跑完 0.4 的验收清单，把未通过项记成 issue；跑 SKIP_BUILD=1 bash scripts/ci.sh 确认三项门禁全绿。

验收 checklist

• [ ] 四条主链路各自走到过"成功"与"失败"两条分支
• [ ] 单飞刷新被证明过：并发 401 场景下 /auth/refresh 只出现 1 次
• [ ] 幂等键被证明过：连续两次提交的 Idempotency-Key 相同
• [ ] 断网可用被证明过：有缓存时列表可展示，且日志有降级 warn
• [ ] 冲突被证明过：40901 分支能复现并给出可读提示
• [ ] 环境切换被证明过：Mock 与本地真实后端两种模式都跑通过
• [ ] 静态检查三项全绿，且能说出每一项守住的是什么问题

交付物清单

交付物	形式	说明
验收记录	Markdown	逐条对照 0.4，附日志片段作为证据
环境清单	Markdown	DevEco / SDK / 设备 / 是否真机，以及 hdc list targets 输出
错误分支证据	日志片段	40100 单飞、40901 冲突、断网降级三条
门禁输出	终端输出	ci.sh 三项静态检查的完整输出
问题清单	Markdown	未通过项 + 初步定位（哪一层、哪个文件）

---

0.8 延伸阅读

• 官方文档 → 应用开发 → 应用框架 → 应用程序包结构（HAP / HAR / HSP 的产物与安装分发模型）
• 官方文档 → 应用开发 → 应用框架 → ArkUI → Navigation 组件与 NavPathStack
• 官方文档 → 应用开发 → 应用框架 → Remote Communication Kit → 使用 rcp 发起网络请求 与 拦截器
• 官方文档 → 应用开发 → 应用框架 → ArkData → Preferences / 关系型数据库（RDB）开发指导
• 官方文档 → 应用开发 → 应用框架 → ArkUI → 状态管理 V2（@ObservedV2 / @Trace / @Local / @Param / @Computed / @Monitor）
• 官方文档 → 工具 → 命令行工具（hvigorw / hdc / ohpm）
• 本教程 README 的「版本基线」与「第 11 章目录」
• 本工程 code/office-flow/README.md（模块地图、脚本说明、已知限制）
• 本教程 附录 D 本地 Mock 方案（三种 Mock 方案对比与规则表设计）

---

上一章：第 10 章 测试与上架发布 ｜ 下一章：11/01 架构与模块划分

📄 第 11 章 架构与模块划分 01-architecture-modules.md✓ 标记已学

第 9 章讲了"模块化应该怎么想"，这一章讲"OfficeFlow 实际怎么做的、脚本怎么把它钉住"。区别在于：第 9 章给的是原则与可配置的示例脚本，这一章给的是已落地的事实——真实的 13 个模块、真实的依赖输出、真实的目录，以及三处绕开循环依赖的具体手法。

---

1.0 本章目标

1. 能读懂 node scripts/check-deps.mjs 的输出，并能解释每一行的依赖为什么是这条而不是另一条。
2. 能说出 13 个模块各自的形态（HAP / HAR / HSP）、职责与"为什么是这个形态"。
3. 能背出依赖四条铁律，并指出每条铁律由哪个脚本、以什么规则拦住。
4. 能按目录约定在一个新 feature 里摆放代码：哪个文件进 model/、哪个进 datasource/、为什么 view/ 里不能 new 依赖。
5. 能画清 View → ViewModel → Repository → DataSource 的返回类型契约，并说明"哪一层的异常可以逃逸"。
6. 能复述三个跨模块解耦手法的真实代码，并说明它们各自切断了哪条依赖边。

---

1.1 依赖图（脚本的真实输出）

不要从文档里抄依赖图——从脚本里读。以下输出来自 node scripts/check-deps.mjs（13 个模块，无违规）：

lib_base          （无依赖）
lib_auth           --> lib_base, lib_log, lib_network
lib_distributed    --> lib_base, lib_log
lib_log            --> lib_base
lib_network        --> lib_base, lib_log
lib_router         --> lib_base, lib_log
lib_storage        --> lib_base, lib_log
lib_ui             --> lib_base
feature_approval   --> lib_base, lib_log, lib_network, lib_router, lib_storage, lib_ui
feature_collab     --> lib_base, lib_distributed, lib_log, lib_network, lib_router, lib_storage, lib_ui
feature_login      --> lib_auth, lib_base, lib_log, lib_network, lib_router, lib_ui
feature_message    --> lib_base, lib_log, lib_network, lib_router, lib_storage, lib_ui
entry              --> 全部 12 个模块

用 Mermaid 表达同一张图（方向 = 依赖方向，箭头指向被依赖方）：

graph TD
    entry --> feature_login
    entry --> feature_approval
    entry --> feature_message
    entry --> feature_collab
    entry --> lib_ui
    entry --> lib_auth
    entry --> lib_network
    entry --> lib_storage
    entry --> lib_log
    entry --> lib_router
    entry --> lib_distributed
    entry --> lib_base

    feature_login --> lib_auth
    feature_login --> lib_network
    feature_login --> lib_router
    feature_login --> lib_ui
    feature_login --> lib_log
    feature_login --> lib_base

    feature_approval --> lib_network
    feature_approval --> lib_storage
    feature_approval --> lib_router
    feature_approval --> lib_ui
    feature_approval --> lib_log
    feature_approval --> lib_base

    feature_message --> lib_network
    feature_message --> lib_storage
    feature_message --> lib_router
    feature_message --> lib_ui
    feature_message --> lib_log
    feature_message --> lib_base

    feature_collab --> lib_distributed
    feature_collab --> lib_network
    feature_collab --> lib_storage
    feature_collab --> lib_router
    feature_collab --> lib_ui
    feature_collab --> lib_log
    feature_collab --> lib_base

    lib_auth --> lib_network
    lib_auth --> lib_log
    lib_auth --> lib_base

    lib_network --> lib_log
    lib_network --> lib_base
    lib_storage --> lib_log
    lib_storage --> lib_base
    lib_router --> lib_log
    lib_router --> lib_base
    lib_log --> lib_base
    lib_distributed --> lib_log
    lib_distributed --> lib_base
    lib_ui --> lib_base

读这张图有三个要点：

1. 它是星形的，不是网状的。所有跨 feature 的"跳转"都走 lib_router，因此 feature_* 之间一条边都没有。
2. lib_base 是唯一的汇点（零出边）。它的 oh-package.json5 里 "dependencies": {} 是空的——这不是省事，而是"最底层契约"的定义。
3. lib_ui 是 HSP，在依赖图上与 HAR 看不出差别，差别在运行期（见 1.2 与 1.4）。

术语：稳定依赖原则（SDP） ── 模块只能依赖比自己更稳定的模块。"稳定"= 被更多模块依赖 + 变化频率更低。反过来（稳定的依赖不稳定的）会让稳定的那个被迫跟着变，稳定性被摧毁。这就是 lib_base 绝不能 import 任何 feature_* 的原因。

---

1.2 模块清单表（13 个）

#	模块	形态	职责	为什么是这个形态	对应章节
1	entry	HAP	唯一可安装入口：UIAbility、窗口尺寸监听（唯一一处）、根 NavPathStack、系统路由表分发、启动编排	一个应用必须有且只有一个可安装入口；Ability 与 @Entry 页面只能存在于 HAP	04、11/01、11/08
2	feature_login	HAR	登录页、本地校验、记住账号、登录成功后的回跳白名单	业务特性：变化频率最高，只被 entry 引用，HAR 约束最少、调试最简单	11/04
3	feature_approval	HAR	审批列表 / 详情 / 发起 / 撤回 / 审批；本工程的目录约定范例	同上	11/05
4	feature_message	HAR	消息列表、已读状态、本地轻量缓存、通知发布与点击跳转	同上	11/06
5	feature_collab	HAR	设备发现面板、草稿协同 UI、冲突展示	同上	07、11/07
6	lib_auth	HAR	令牌生命周期（TokenStore）、单飞刷新（TokenRefresher）、会话状态（SessionStore）、登出广播（LogoutBus）、与网络层的接驳（AuthProviderInstaller）	能力库：不感知业务，但也不是"最底层"——它依赖 lib_network，因此不能是 HSP 的候选（HSP 只允许依赖 lib_base）	11/04
7	lib_network	HAR	rcp 封装、拦截器链、Result/AppError 映射、重试与取消、Mock 基建	能力库；被 5 个模块引用，但没有多 HAP 场景，因此不需要 HSP	06、11/02
8	lib_storage	HAR	Preferences / RDB / 文件 / 分布式 KV 封装	能力库；刻意不依赖 lib_network（存储层不知道"网络"这件事存在）	06
9	lib_log	HAR	三级日志（XLogger）、打点（Trace）、埋点（Analytics）、脱敏（Masker）	能力库；被几乎所有模块引用，是最"公共"的 lib，但形态仍是 HAR（见下方说明）	11/03
10	lib_router	HAR	路由名常量（RouteNames）、参数契约、Router 门面（唯一允许碰 NavPathStack 的地方）、拦截器与路由埋点	能力库；不得依赖任何 feature，否则星形图退化成网状	04、11/01
11	lib_distributed	HAR	设备发现（DeviceHub）、同步通道（DraftSyncChannel）、逐字段合并与冲突裁决（DraftMerge）、权限（Permission）	能力库；刻意不依赖 lib_network——协同是"设备到设备"的本地能力，拖进网络栈会让协同逻辑在断网时无法单测	07、11/07
12	lib_ui	HSP	公共组件、设计 token、断点工具	唯一被建成 HSP 的库：它承载跨 HAP 共享的单例语义（主题状态、AppStorageV2 实例）。HAR 在多 HAP 下会被复制成多份实例，"单例"退化成"每份一个"	03、11/07
13	lib_base	HAR	契约（Result/AppError/Contracts）、工具（JsonReader）、能力门禁（CapabilityGate）、常量（EnvConfig/AppConst/UserMessages）	最底层；零依赖，被所有人依赖	02、11/02

1.2.1 三个"为什么"的补充说明

为什么 lib_log 不建 HSP？ 它被 12 个模块引用，看起来很"公共"。但本工程只有一个 HAP（entry），HSP 的收益只出现在"同一份库被 ≥2 个 HAP 引用"的场景。单 HAP 下 HSP 反而白搭上首启加载开销与"同签名同 bundle"约束。引用广度不是选择 HSP 的依据，多 HAP 才是。

为什么 HSP 只允许依赖 lib_base？ HSP 与引用它的 HAP 必须同签名同 bundle。若 lib_ui 依赖了 lib_network，而 lib_network 又依赖 lib_log……共享包会把整条依赖链拖进"必须同签名同 bundle"的约束里，任何一环被别的 HAP 用不同版本引用就会冲突。因此 lib_ui/oh-package.json5 里只有 lib_base，而 lib_ui/Index.ets 的注释写明了这条纪律。

为什么 lib_ui 组件"只认字符串"？ 见 1.6 手法②。这是"UI 库不反向依赖数据层"的落地方式；一旦 lib_ui import 了业务枚举，依赖方向就变成"UI 依赖数据层"，lib_ui 再也不可能被别的业务复用。

---

1.3 依赖四条铁律 + 脚本如何强制

四条铁律来自工程 README，落地形态在 scripts/check-deps.mjs（架构门禁）与 scripts/check-banned-api.sh（范式门禁）。

铁律	允许 / 禁止	违反后的症状	谁拦住它
① 单向：feature → lib → lib_base	lib → feature ❌	改一个 feature 导致多个 lib 重编译，且该 lib 无法单测	check-deps.mjs 规则 5「依赖方向倒置（低层依赖了高层）」——用 layerOf() 给模块分层（lib_base=0 / lib_*=1 / feature_*=2 / entry=3），toLayer > fromLayer 即违规
② 无横向：feature ↔ feature 禁止	横向 import ❌	两个 feature 互相 import，任一模块无法被删除或复用，规模一大必然成环	check-deps.mjs 规则 1「feature 之间禁止横向依赖」——mod.name.startsWith('feature_') && dep.startsWith('feature_')。这是脚本里第一条被拦下来的规则
③ 零依赖：lib_base 不依赖任何本地模块	❌	底层契约被业务污染，"公共库"再也不公共	check-deps.mjs 规则 3——只要 lib_base 的 oh-package.json5 里出现任何 file: 依赖即违规
④ 可解析且无环：依赖必须指向 build-profile.json5 已注册的模块，且图中无环	❌	构建期报错位置离原因很远；有环则无法独立编译与单测	check-deps.mjs 规则 4「依赖了未注册的模块」+ 规则 2「依赖环」（DFS 三色标记，打印完整环路径如 lib_a → lib_b → lib_a）

另外两条"软"约束：

• 同层 lib ↔ lib 只给警告。lib_network → lib_log、lib_auth → lib_network 都是合理的；但 a → b → a 是环的雏形。需要人判断的事不该做成硬门禁，否则门禁会被绕过。
• 依赖未注册但目录不存在 → 只警告（并行开发中"目录还没建"不等于"依赖错了"）；用 --strict 可以让它变成错误（CI 的最终分支上应开这个开关）。

范式的门禁交给 scripts/check-banned-api.sh，它守的是四类"看起来能编过、但属于上一代范式"的写法：

规则 id	拦什么	为什么
ohos-namespace-import	from '@ohos.xxx' 分命名空间导入	API 26 起统一走 @kit.*；混用会让"这个能力归哪个 Kit"不可知，升级时无法一次性盘点改动面
ohos-router	@ohos.router	已由 Navigation + 路由名常量取代
ohos-net-http	@ohos.net.http	已由 lib_network 的 rcp 封装取代
persistent-storage	PersistentStorage	应由 lib_storage 收口
v1-state-decorator	@State/@Prop/@Link/@Observed/@ObjectLink/@Provide/@Consume/@Watch/@StorageLink/@StorageProp/@LocalStorageLink/@LocalStorageProp/@Track	V1 与 V2 观察机制不能混用，是"莫名其妙不刷新"的最大来源；两者只差一个字符，人眼在 Review 里抓不住

版本门槛：check-banned-api.sh 用一次 awk 完成"剥注释 + 全规则匹配"。这不是写法偏好——若"每个文件 × 每条规则"各起一次进程，60 个文件就是 900 次进程创建，在 Windows/Git Bash 上会把一条 3 秒的检查变成 90 秒，门禁一慢，人就会想办法跳过它。

1.3.1 怎么验证门禁真的在工作

# 1) 三项静态检查一起跑（不需要 DevEco，几秒钟）
SKIP_BUILD=1 bash scripts/ci.sh

# 2) 故意造一条横向依赖，确认脚本拦下
#    在 feature_message/oh-package.json5 的 dependencies 里加：
#    "feature_approval": "file:../feature_approval"
node scripts/check-deps.mjs        # 应退出码 1，并打印 [feature 横向依赖]

# 3) 故意写一个 V1 装饰器，确认脚本拦下
#    在任意 .ets 里写 @State count: number = 0;
bash scripts/check-banned-api.sh   # 应退出码 1，并打印 v1-state-decorator

把这两次"故意违规"做完，你才会相信门禁真的在跑——没有验证过的门禁等于没有门禁。

---

1.4 目录约定（以 feature_approval 为范例）

feature_approval/
├── Index.ets                          ← 唯一导出面：页面 / RouteBuilder / Mock 规则
├── oh-package.json5                   ← 依赖声明（feature → lib_*，无 feature 横向）
├── build-profile.json5                ← 模块构建配置（release 开混淆）
├── hvigorfile.ts                      ← harTasks
└── src/main/
    ├── module.json5                   ← "type": "har"，不声明任何权限
    └── ets/
        ├── model/                     ← 领域模型 + 状态机 + DTO 解析
        ├── datasource/                ← IO 边界：远端 / 本地 / 缓存策略
        ├── repo/                      ← 仓储：接口 + 实现 + 单例
        ├── viewmodel/                 ← 页面状态与命令（@ObservedV2 + @Trace）
        ├── view/                      ← 页面（XxxPage.ets）
        │   └── components/            ← 该 feature 私有组件
        ├── router/                    ← RouteBuilder + 本模块路由名清单
        ├── mock/                      ← Mock 规则表
        └── di/                        ← 装配点（唯一的 factory）

逐目录说明「放什么 / 不放什么」：

目录	放什么	不放什么	依据
model/	领域模型（Approval）、状态机与流转规则（ApprovalStatus + ApprovalStatusRules）、命令对象（ApprovalQuery 里的 SubmitApprovalCmd/WithdrawCmd/DecideApprovalCmd）、DTO 与手写解析（ApprovalDto 里的 ApprovalMapper）	任何 IO、任何 UI 依赖、任何文案资源	model/ 是最内层，能被 UI（决定按钮显隐）、仓储（决定能否撤回）、测试（穷举状态组合）三处共用，因此必须是纯函数
datasource/	远端 IO（ApprovalRemoteDs：拼路径/参数/body、具名 parser、声明幂等性与重试策略）、本地 IO（ApprovalLocalDs：RDB 读写）、缓存新鲜度策略（ApprovalCachePolicy）	缓存降级决策、状态管理、面向用户的文案	ApprovalRemoteDs 的类注释明确列出"只做四件事"，并声明"不做：缓存、降级、状态管理、文案"
repo/	ApprovalRepository（接口，定义契约与返回类型）、ApprovalRepositoryImpl（编排远端/本地/内存三层与降级）、ApprovalRepoSingleton（进程级单例）	UI 决策（跳转/弹窗）、直接构造 ViewModel	ApprovalRepository 注释："全部分层约定：只返回 Result，不抛异常"
viewmodel/	@ObservedV2 类，@Trace 字段承载 UI 状态，@Computed 派生值，@Monitor 状态变迁埋点，命令方法（loadFirstPage/refresh/loadMore/submit/withdraw）	new 依赖（走 DI）、拼 UI 资源引用、写 SQL/发请求的细节	ApprovalListViewModel 类注释的"状态更新两条铁律"
view/	XxxPage.ets（承载 NavDestination 与可见性回调）、components/ 下的私有组件（ApprovalCard、ApprovalDataSource）	new 仓储/数据源、await、JSON 解析、定时器	见下方 1.4.1
router/	@Builder export function XxxRouteBuilder、本模块路由名清单（APPROVAL_ROUTE_NAMES）	裸字符串路由名、参数断言、NavDestination 包装	ApprovalRoute.ets 注释：页面自己承载 NavDestination，这样 onShown/onHidden 才能直接驱动 ViewModel
mock/	规则表（ApprovalMockRules），规则是纯函数：入参 MockRequest、出参 MockResponse	依赖外部可变状态、随机数触发分支	AuthMockRules 注释："Mock 里故意不做令牌黑名单这类状态，否则测试之间会互相污染"
di/	唯一的装配点（ApprovalModule）：仓储单例、ViewModel 工厂、跨页面脏标记、Mock 安装、清缓存	业务逻辑	ApprovalModule 注释：依赖图只应存在于本文件与 ApprovalRepoSingleton

1.4.1 为什么 View 里不允许 new 依赖

ApprovalModule.ets 的类注释把理由写全了，这里提炼成三条可检验的后果：

1. 依赖图被复制 N 份。每个页面各 new 一次数据源，就多一份 HTTP 客户端配置、多一套缓存句柄。想统一改超时或换实现时，你得先在全局搜 new ApprovalRemoteDs。
2. 单测无法替换实现。ApprovalRepository 之所以是接口，就是为了让假实现能塞进 ViewModel（"单测可以把假实现塞进 ViewModel，不需要起网络与 RDB"）。页面直接 new 实现类，这个能力立刻消失。
3. 冷启动被拖慢。new 的时机变成了"页面被构建时"，而页面是运行时按需挂载的；依赖构造里只要有一点同步开销，就会落在用户可见的路径上。

与之配套的第二条纪律：仓储是单例，ViewModel 每次新建。这个区别不是随意定的——它决定了"第二次进入页面还能不能用"：

// feature_approval/src/main/ets/di/ApprovalModule.ets
static repository(): ApprovalRepository {
    return ApprovalRepoSingleton.get();      // 单例：无状态服务对象，持有连接/句柄
}

/** 列表页 ViewModel（**每次新实例**，理由见类注释） */
static listViewModel(): ApprovalListViewModel {
    return new ApprovalListViewModel(ApprovalModule.repository());
}

ViewModel 一旦被复用，它持有的 cancelToken 已经是 cancelled，第二次进页面时所有请求结果都会被 isStale() 丢弃——表现为"第二次进列表永远空白"。

术语：装配点（composite root） ── 应用里唯一允许把具体实现拼接起来的位置。依赖注入的"注入"通常发生在两个地方：一处是进程级的组合根（AppInitializer），一处是模块级的装配点（ApprovalModule）。除此之外，任何地方 new 实现类都是违规。

---

1.5 分层数据流与返回类型契约

1.5.1 完整流转

        用户点击
           │
           ▼
┌─────────────────────┐   绑定 @Trace 字段（只读）
│  View（XxxPage）     │◄──────────────────────────────┐
│  NavDestination      │                               │
│  onShown / onHidden  │  调用命令方法（不 await 结果） │
└──────────┬──────────┘                               │
           │ vm.loadFirstPage() / vm.submit(cmd)      │
           ▼                                          │
┌─────────────────────┐   写 @Trace 字段（唯一写状态入口）│
│ ViewModel            │───────────────────────────────┘
│ @ObservedV2 + @Trace │
│ @Computed（派生）     │
│ @Monitor（变迁埋点）  │
└──────────┬──────────┘
           │ 返回 Result<ApprovalListResult>
           ▼
┌─────────────────────┐   编排三层数据来源 + 降级 + 缓存策略
│ Repository（接口）    │   返回 Result<T>，绝不抛异常
│ ApprovalRepositoryImpl│
└──────────┬──────────┘
           │ 返回 Result<Paged<Approval>>
           ▼
┌─────────────────────┐   拼路径/参数/body、具名 parser、
│ DataSource           │   声明幂等性与重试策略
│ RemoteDs / LocalDs   │   内部可 try/catch，出口仍是 Result
└──────────┬──────────┘
           │
           ▼
   HttpApi → RcpClient → 拦截器链 → RcpTransport → rcp
   （lib_network）

1.5.2 每层的返回类型契约

层	返回类型	硬约束	依据
View	无返回（void）	只做"发起命令 + 绑定字段"。没有 await、没有 JSON、没有定时器、没有 try/catch	ApprovalListViewModel 类注释铁律 1
ViewModel	命令方法返回 Promise<void> 或 Promise<Result<T>>；状态通过写 @Trace 字段表达	只能在某个方法内部 await 仓储后写 @Trace 字段；数组整体替换而不是逐项就地改	同上铁律 1、2
Repository	Result<T>（Promise<Result<T>>）	绝不抛异常。远端失败且有本地数据时降级为成功，而不是把错误甩给 UI	ApprovalRepository 接口注释
DataSource	Result<T>（远端）；本地层返回 Result<T> 或裸值 + 由 repo 包装	内部可以 try/catch，但出口必须是 Result。远端的 catch 里 e as AppError 之所以成立，是因为拦截器链保证了"抛出的都是 AppError"	ApprovalRemoteDs 的 HttpApi 调用 + 第 2 章的拦截器顺序论证
HttpApi	Result<T>	解包 data 段 + 调 parser；解析失败归一为 PARSE_FAILED；issues 只记 WARN 不上报错误	lib_network/api/HttpApi.ets 的 unwrap

四类"谁负责什么"的边界（一句话版）：

• View 不知道 HTTP、SQL、缓存策略；
• ViewModel 不知道 数据从哪来（远端还是缓存），只知道"要点亮哪个状态"；
• Repository 不知道 UI 结构、路由、组件；
• DataSource 不知道 业务规则（能不能审批由服务端定），只负责数据搬运。

1.5.3 为什么"编排信息"要跟着数据一起上来

ApprovalRepository.list() 返回的不是 Paged<Approval>，而是 ApprovalListResult：

export class ApprovalListResult {
    readonly page: Paged<Approval>;
    /** 数据来自本地缓存（可能是新鲜的，也可能是降级兜底） */
    readonly fromCache: boolean;
    /** 远端请求失败，用陈旧缓存兜底 —— UI 应给出"重试"入口 */
    readonly degraded: boolean;
    /** 缓存命中且正在后台刷新 —— UI 保留旧数据，不要清屏 */
    readonly refreshing: boolean;
    // ...
}

理由写在 ApprovalRepository.ets 的注释里：fromCache/degraded/refreshing 是 UI 必须知道的信息。把它们藏在 repo 内部只返回数据，UI 就只能靠猜，最后演变成"错误页和内容页互相覆盖"的闪烁。让信息随数据一起上来，是这一层存在的理由。

误区：让 Repository 返回裸数据，把"是否降级"做成 Repository 的内部日志。日志只有开发者看得到，UI 看不到——用户会以为自己看到的待审批列表是最新的。

---

1.6 跨模块协作的三个解耦手法

这三处都是"本来会产生一条不该有的依赖边，用别的方式切断了它"。每处都对应真实文件。

手法① AuthTokenProvider 接口 + AuthTokenRegistry 反向注入：切断 lib_network ↔ lib_auth 的环

问题：lib_auth 需要 lib_network 发登录/刷新请求；而 lib_network 的 AuthInterceptor 需要 lib_auth 提供 token。直接互相 import 就是环。

解法：lib_network 只定义接口，不认识实现；lib_auth 在启动时把实现注册进来。依赖方向仍然是 lib_auth → lib_network → lib_base，单向无环。

// lib_network/src/main/ets/rcp/interceptors/AuthInterceptor.ets
/**
 * 存在的意义是**切断 lib_network 与 lib_auth 的循环依赖**：
 *   lib_auth 需要 lib_network 发登录/刷新请求；
 *   lib_network 需要 lib_auth 提供 token。
 * 解法：lib_network 只依赖这个接口，lib_auth 在应用启动时注册实现。
 */
export interface AuthTokenProvider {
    currentToken(): string;
    shouldRefresh(): boolean;
    refreshToken(): Promise<boolean>;
    onUnauthorized(reason: string): void;
}

export class AuthTokenRegistry {
    private static provider: AuthTokenProvider | undefined = undefined;

    static install(provider: AuthTokenProvider): void {
        AuthTokenRegistry.provider = provider;
    }

    /** 获取实现；未安装时抛错（属配置错误，应在启动阶段暴露而非静默降级） */
    static require(): AuthTokenProvider {
        const p: AuthTokenProvider | undefined = AuthTokenRegistry.provider;
        if (p === undefined) {
            throw new Error('AuthTokenProvider 未安装：请在应用启动时调用 AuthTokenRegistry.install()');
        }
        return p;
    }
}

实现侧则是 TokenRefresher（lib_auth，同时是单飞刷新的实现），安装动作被收敛到 AuthProviderInstaller.install(clientVersion)，由 entry 在 AppInitializer.initAuthProvider() 调一次。

三个刻意的设计决定：

1. require() 抛异常而不是返回 undefined。缺鉴权配置属于启动期配置错误，必须在第一个请求就炸出来，而不是静默地把所有请求发成"匿名请求"，几天后表现为"线上 30% 的用户看不到数据"。
2. 安装动作显式化，不靠模块副作用。HAR 的模块级代码在"谁最先被 import"上是不确定的，靠模块副作用做初始化会踩坑。
3. entry 只说"安装鉴权"，不知道装的是什么。AppInitializer.initAuthProvider() 调 AuthProviderInstaller.install(version)，而不是手写 AuthTokenRegistry.install(TokenRefresher.shared())——后者会把"装什么"的知识复制到 entry，lib_auth 换实现时 entry 得跟着改。

手法② lib_ui 的 ApprovalStatusView 只认字符串：切断"UI 库 → 数据层"的反向依赖

问题：审批状态标签放在 lib_ui 里最合理（列表页、详情页、消息卡片都要用）。但 lib_ui 一旦 import 业务枚举（feature_approval 的 ApprovalStatus），依赖方向就变成"UI 依赖业务"，lib_ui 再也不可能被别的业务复用。

解法：把契约放在字符串上（后端本来就是字符串），由状态枚举保证它只可能是那几个值之一。

// lib_ui/src/main/ets/components/AppTag.ets
/**
 * 为什么这里只认**字符串**、不 import 业务枚举：
 * lib_ui 是公共 UI 层，一旦 import 了数据层的 ApprovalStatus，
 * 依赖方向就变成"UI 依赖数据层"，lib_ui 再也不可能被别的业务复用。
 * 契约放在字符串上（后端本来就是字符串），由状态枚举保证它只可能是这四个值之一。
 */
export class ApprovalStatusView {
    static readonly PENDING: string = 'pending';
    static readonly APPROVED: string = 'approved';
    static readonly REJECTED: string = 'rejected';
    static readonly WITHDRAWN: string = 'withdrawn';

    static toneOf(status: string): AppTagTone {
        switch (status) {
            case ApprovalStatusView.PENDING:
                // 待审批用 warning 而不是 info：它表示"需要有人做事"，是可以推动的状态
                return AppTagTone.WARNING;
            case ApprovalStatusView.APPROVED:
                return AppTagTone.SUCCESS;
            // ...
            default:
                // 未知状态落到中性色但文案明确写"未知状态"，
                // 不做静默兜底 —— 静默兜底会让契约漂移永远不被发现
                return AppTagTone.NEUTRAL;
        }
    }
}

两层语义隔离也是这条手法的一部分：

• 标签的"语义 tone"（AppTagTone.INFO/SUCCESS/WARNING/DANGER/NEUTRAL）与"色值"分离。语义到色值的映射只在资源文件（app.color.tag_*）里发生，换主题/换品牌色时组件代码一行不改。反例：一旦出现 AppTagTone.BLUE，就等于把色值决策泄漏进了业务代码。
• 业务侧只负责"状态 → tone 名"的映射（feature_approval/src/main/ets/view/components/ApprovalCard.ets 的 toneNameOf），lib_ui 只负责"tone → 外观"。

版本门槛：这套写法在 API 20 上即可用，不涉及新 API。

手法③ feature 之间只走 lib_router 的 RouteNames 常量

问题：feature_message 想跳到审批详情。最直觉的写法是 import { ApprovalDetailPage } from 'feature_approval'——这一行立刻产生横向依赖，两个模块从此刻起无法独立删除、独立编译、独立测试。

解法：只依赖 lib_router 的路由名常量与参数契约，运行时由路由表解析到具体页面。

// feature_message/src/main/ets/view/MessageListPage.ets
// 跨 feature 跳转只依赖 lib_router 的路由名常量，**不 import feature_approval**。
// 直接 import 目标页面会立刻产生 feature 之间的横向依赖，两个模块从此无法独立删除。
Router.push(RouteNames.APPROVAL_DETAIL, param);

RouteNames 同时是全局路由表——"谁跳向谁"在一处就能看全：

// lib_router/src/main/ets/const/RouteNames.ets
export class RouteNames {
    static readonly LOGIN: string = 'Login';
    static readonly MAIN: string = 'Main';
    static readonly APPROVAL_LIST: string = 'ApprovalList';
    static readonly APPROVAL_DETAIL: string = 'ApprovalDetail';
    static readonly APPROVAL_CREATE: string = 'ApprovalCreate';
    static readonly MESSAGE_LIST: string = 'MessageList';
    static readonly COLLAB_DEVICES: string = 'CollabDevices';
    static readonly SETTINGS: string = 'Settings';

    static readonly ALL: string[] = [ /* ... */ ];
    static readonly PUBLIC: string[] = [ RouteNames.LOGIN ];
}

这套方案自身也有代价，必须知道：

1. 路由名是字符串，没有编译期保护。拼错的现象是"点进去白屏"（无异常、无日志、无堆栈）。因此需要 scripts/check-route-map.mjs 守住 pageSourceFile 存在、buildFunction 命名、路由名不重复。
2. 参数类型也无法强校验。RouteNames.ets 的注释里写明了原因：static readonly LOGIN: string = 'Login' 在 ArkTS 里的类型是 string 而不是字面量 'Login'，因此写不出 RouteParamsMap[RouteNames.LOGIN] 这种索引访问。补偿手段是"参数接口 + 调用处对象字面量的类型标注"：

const param: ApprovalDetailParam = { id: id, from: 'approval_list' };
Router.push(RouteNames.APPROVAL_DETAIL, param);

3. 参数必须可序列化，且只放"标识 + 来源"。把整个对象塞进参数会造成"详情页显示的是旧数据"（用户返回列表再进来时尤其明显）。

误区：以为"用了 RouteNames 常量就万事大吉"。常量只解决了名字的一致性，解决不了参数的一致性。真实反例见 1.8 误区 4。

---

1.7 常见误区

误区 1：把所有公共代码塞进一个 common HAR

错误做法：新建 common 模块，把工具函数、DTO、常量、UI 组件、甚至一部分业务逻辑全放进去，所有模块都依赖它。 正确做法：按"变化频率 + 复用度 + 团队边界"拆成 lib_base（契约与工具，最稳定）/ lib_network / lib_storage / lib_log / lib_router / lib_ui，各自只被真正需要它的模块依赖。 为什么错：common 会变成"人人都依赖、人人不敢改"的上帝模块——改一行工具函数就触发全量重编，且它必然违反对稳定依赖原则（common 依赖了业务，就再也稳不了）。本工程把这条约束做成硬门禁：lib_base 出现任何 file: 依赖即 check-deps.mjs 违规。

误区 2：feature 互相 import 形成环

错误写法：

// feature_message 里
import { ApprovalDetailPage } from 'feature_approval';

正确写法：

import { RouteNames, Router } from 'lib_router';
const param: ApprovalDetailParam = { id: message.relatedId, from: RouteNames.MESSAGE_LIST };
Router.push(RouteNames.APPROVAL_DETAIL, param);

为什么错：横向依赖让两个模块绑死——无法单独删除、无法单独编译、无法单独测试，而且规模一大必然成环。更隐蔽的是双向依赖：feature_approval 也想跳 feature_message 时，环就形成了，编译期可能能过，运行期可能拿到未初始化的模块。本条是 check-deps.mjs 里第一个被拦下来的规则。

误区 3：HAR 用 export *

错误写法：Index.ets 里写 export * from './src/main/ets/index-all'。 正确写法：逐个 export { 具体符号 }，类型用 export type { ... }。 为什么错：export * 把内部实现一次性暴露为公共契约，之后任何内部重构都成为破坏性变更，下游随时可能编译失败；同时你无法回答"这个模块对外提供了什么"。本工程连"该导出什么"都做了取舍——feature_approval/Index.ets 刻意不导出 model/datasource/repo/viewmodel，也不导出 ApprovalModule；lib_network/Index.ets 甚至为此写了注释："内部实现（RcpTransport、各拦截器）虽然导出，但调用方应把它们视为'可替换实现'，而不是稳定契约"。

误区 4：以为"路由名对了"就够了，忽略参数契约

现象（曾是本工程的真实缺陷，已修复）：feature_message/src/main/ets/view/MessageListPage.ets 曾在跳转时传 { 'approvalId': message.relatedId }，而 ApprovalDetailParam 的契约是 { id: string; from: string }，详情页读的是 param.id。结果是：从消息列表点进详情，缺 id，详情页会立刻 pop 回上一页——用户看到的是"点了没反应"。 收敛后的写法（本工程的落地范例）：

// feature_message/src/main/ets/view/MessageListPage.ets:319-323
// 参数键名必须逐字匹配 ApprovalDetailParam（id + from，两者都必填）：
const param: ApprovalDetailParam = {
    id: message.relatedId,
    from: RouteNames.MESSAGE_LIST
};
Router.push(RouteNames.APPROVAL_DETAIL, param);

为什么必须这样：Router.push<P extends object>(name: string, param?: P) 的形参类型不携带路由名信息（见 1.6 手法③ 的成因），所以编译期不会拦。补偿手段只有一个：调用处显式标注参数类型（const param: ApprovalDetailParam = {...}），让编译器替你检查字段名。不写这行标注，就等于放弃了唯一的保护。

误区 5：把 UIAbility 和路由注册放进 HSP

错误做法：为了"统一管理"，把 Ability、@Entry 页面、路由表注册都放进一个 HSP。 正确做法：UIAbility 与 @Entry 页面只能存在于 HAP（entry）；HSP 只放公共组件与主题（lib_ui）。 为什么错：HSP 是随宿主 HAP 一起安装的共享库，自身不是可安装单元，不能承载应用的拉起入口；同时 HSP 受"同签名同 bundle"约束，把它做成"应用骨架"会让任何想复用的模块都被拖进这个约束。形态选择的正解是：可安装/需要独立分发 → HAP；被 ≥2 个 HAP 引用且体积大 → HSP；其余 → HAR（默认选择）。

误区 6：依赖图不校验，靠人肉 review

错误做法：把依赖规则写进团队文档，靠 CodeReview 抓。 正确做法：把规则编码进 scripts/check-deps.mjs 与 scripts/check-banned-api.sh，接进 CI 的静态检查阶段，失败即阻断。 为什么错：一次为了赶进度写的横向 import 就能把两个 feature 焊死，而编译、打包、运行都不报错——它只会在"某天想删掉一个模块"时集中爆发。规则写在文档里没有约束力；能被绕过的门禁等于没有门禁。同理，V1 装饰器与 V2 装饰器只差一个字符，人眼在 Review 里抓不住。

误区 7：同层 lib 互相依赖不当回事

现象：lib_auth → lib_network、lib_network → lib_log 都是真实存在的同层依赖，脚本只给警告。 正确做法：逐个判断方向是否合理——lib_auth 依赖 lib_network 合理（它要发请求），lib_network 依赖 lib_log 合理（它要打日志）；但一旦出现 lib_a → lib_b → lib_a，就是环的雏形，必须立刻拆掉。 为什么错：同层依赖本身不是错，成环才是。脚本把它做成警告而不是硬门禁，是因为"需要人判断的事不该做成硬门禁"——否则大家会习惯性地加白名单，门禁整体失效。

---

1.8 实践任务

任务：给 OfficeFlow 加一个新 feature 模块，并让门禁保持全绿

阶段一：建图

1. 跑 node scripts/check-deps.mjs，把当前依赖图抄进自己的笔记，并在图上标出你打算挂新模块的位置。
2. 决定新模块的形态（HAR 还是 HSP），写出理由（被打几个 HAP 引用？有没有跨 HAP 的全局单例语义？）。
3. 在 build-profile.json5 的 modules 里注册新模块，并同步更新 1.2 的模块清单表。

阶段二：落地

4. 建目录骨架，按 1.4 的九个目录（model/datasource/repo/viewmodel/view/components/router/mock/di）逐个填空，没有内容的目录不要建。
5. 写 Index.ets，逐个 export 稳定契约，禁止 export *；刻意想清楚"哪些不导出"。
6. 在新模块里实现一条最小链路：View → ViewModel → Repository → DataSource → HttpApi，全程返回 Result<T>，View 里不出现 try/catch 与 await。
7. 在 di/ 里写装配点（仓储单例 + ViewModel 工厂），页面只从装配点取依赖。

阶段三：接路由

8. 在 lib_router/const/RouteNames.ets 里加路由名与参数接口（改的是 lib_router，不是别的 feature）。
9. 在 entry/pages/Index.ets 里加一个 @Builder export function xxxRouteBuilder，并同步 route_map.json 与 destBuilder 分支（三处必须一次改完）。
10. 从另一个 feature 用 Router.push(RouteNames.XXX, param) 跳过来，调用处显式标注参数类型。

阶段四：让门禁说话

11. 跑 SKIP_BUILD=1 bash scripts/ci.sh，三项检查必须全绿。
12. 故意在新模块的 oh-package.json5 里加一条对别的 feature 的依赖，确认 check-deps.mjs 拦下；确认后删掉。
13. 故意在某处写 @State，确认 check-banned-api.sh 拦下；确认后删掉。

验收 checklist

• [ ] 新模块已注册进 build-profile.json5 的 modules，check-deps.mjs 输出中出现它且无违规
• [ ] 新模块的 oh-package.json5 里没有任何 file:../feature_*
• [ ] Index.ets 里逐个 export，全文件搜不到 export *
• [ ] di/ 之外的地方搜不到 new XxxRepository / new XxxRemoteDs
• [ ] view/ 目录里搜不到 try、catch、await、JSON.parse
• [ ] 全链路返回 Result<T>：DataSource 与 Repository 的公开方法签名都能看到 Result
• [ ] route_map.json 的 name/buildFunction/pageSourceFile 三处与 Index.ets 的 destBuilder 一一对应，check-route-map.mjs 通过
• [ ] 跨模块跳转走 RouteNames 常量，且调用处有显式参数类型标注
• [ ] 故意制造的横向依赖与 V1 装饰器都被脚本拦下（有终端输出为证）
• [ ] 更新了 1.2 的模块清单表与 README.md 的模块地图

交付物清单

交付物	形式	说明
新 feature 模块	源码	九个目录中真正用到的那些，加 Index.ets
模块清单表更新	Markdown	模块 / 形态 / 职责 / 为什么是这个形态 / 对应章节
依赖图截图	终端输出或 Mermaid	来自 node scripts/check-deps.mjs 的真实输出
门禁输出	终端输出	三项静态检查全绿的完整输出
形态选择说明	Markdown 半页	为什么这个模块用 HAR / HSP，附量化依据（被几个 HAP 引用）
违规验证记录	终端输出	两次"故意违规被拦下"的证据

---

1.9 常见问题排查表

现象	优先怀疑	验证方式
改了 lib_ui 里的组件，界面没变	HSP 产物未随宿主重装	重新运行 entry（HSP 是独立产物，必须重装宿主）
某个页面"点了没反应"	路由名拼错 / buildFunction 名字不一致 / destBuilder 少一个分支	跑 node scripts/check-route-map.mjs；再逐个比对三处
两个页面看到的断点档位不一致	有页面自己注册了 windowSizeChange	全工程搜索 'windowSizeChange'，应当只有 EntryAbility 一处
第二次进列表永远空白	ViewModel 被复用，cancelToken 已是 cancelled	检查取 VM 的地方是不是工厂（ApprovalModule.listViewModel()）而不是缓存字段
单测里无法替换数据源	页面/VM 里直接 new 了实现类	检查是否通过 ApprovalModule.repository() 取接口
check-deps.mjs 报了"依赖了未注册的模块"	新模块忘了写进 build-profile.json5 的 modules	打开根 build-profile.json5 对照 modules 数组
新增 lib_* 后脚本报"未登记模块"	RULES 白名单没有覆盖它	本工程的 check-deps.mjs 用层级判定（layerOf）而非名字白名单，因此正常不会出现；若出现说明模块命名不符合 lib_ / feature_ 前缀约定

---

1.10 已知缺陷与待收敛项（对表记录）

以下几处是文档与代码对表的产物：前两条曾是真实缺陷，现已按工单收敛（改写为"收敛手法已落地的范例"留档）；ApprovalStatus 的双定义经核实为有意设计；只有最后一条（配置口径）仍是待收敛项：

1. 跨 feature 跳转的参数名不一致（已修复，收敛范例）：feature_message/view/MessageListPage.ets 曾传 { 'approvalId': ... }，而契约 ApprovalDetailParam 与 ApprovalDetailPage 用的是 id，现象（详情页立刻 pop）很隐蔽。现已按契约收敛：MessageListPage.ets:319-323 构造 ApprovalDetailParam { id, from: RouteNames.MESSAGE_LIST } 并显式标注参数类型——见 1.7 误区 4，该写法本身就是防复发的手段。
2. 契约重复定义：
   • ApprovalListParam / ApprovalCreateParam（已修复，收敛范例）：曾在 lib_router/src/main/ets/const/RouteNames.ets 与 feature_approval/src/main/ets/router/ApprovalRoute.ets 各定义一份且字段不同。现已收敛到 lib_router 单一权威；ApprovalRoute.ets:31-42 刻意只 re-export、不再定义，并把"两份同名但形状不同的接口"的危害写成注释——这是"参数契约唯一来源只能是 lib_router"这条纪律落地的范例。
   • ApprovalStatus 与 APPROVAL_STATUS_VALUES 同时出现在 feature_approval/src/main/ets/model/ApprovalStatus.ets（5 个状态，含 Draft，成员名 PascalCase）与 lib_storage/src/main/ets/rdb/ApprovalDao.ets（4 个状态，成员名 SCREAMING_CASE）——这是有意设计，不是待收敛项：业务枚举与持久化枚举刻意分离，两处均有警示注释，且两者之间的换算必须显式完成（见 ApprovalDao.ets:19-27 的文件头注释）。改一处漏一处时不会静默出错，换算层会在编译期逼你表态。
3. 配置两处口径不一致：根 build-profile.json5 的 obfuscation.enable = false 与各模块 buildOptionSet.release 的 enable = true 并存。建议以模块级为准并删除根级那一处（见 0.6 误区 3）。

---

1.11 延伸阅读

• 官方文档 → 应用开发 → 应用框架 → 应用程序包结构（HAP / HAR / HSP 的产物结构与安装分发模型）
• 官方文档 → 应用开发 → 应用框架 → 共享库开发（HAR）（打包方式、导出面、Index.ets 约定）
• 官方文档 → 应用开发 → 应用框架 → 动态共享库开发（HSP）（同签名同 bundle 约束、多 HAP 共享机制）
• 官方文档 → 应用开发 → 应用框架 → 多模块工程与模块间依赖（oh-package.json5、file: 依赖、overrides）
• 官方文档 → 应用开发 → 应用框架 → ArkUI → Navigation 组件与系统路由表（routerMap）
• 官方文档 → 工具 → 构建配置参考（build-profile.json5）（modules、products、buildOptionSet）
• 本教程 第 9 章 工程化与模块化架构（原则与演进路径）
• 本教程 11/02 网络层与统一错误处理（Result 与拦截器链的真实实现）
• 本工程 code/office-flow/README.md 的「模块依赖图」与「工程约定」

---

上一章：11/00 项目总览 ｜ 下一章：11/02 网络层与统一错误处理

📄 第 1 章 环境搭建与工具链 01-environment-toolchain.md✓ 标记已学

环境问题吃掉新手进度的一半以上：版本号该写哪种格式、SDK 到底要不要单独装、工程里每个文件负责什么、命令行怎么出一份能装到设备上的包。这一章把「装 IDE → 建工程 → 命令行构建 → 装到设备」一次走完，并给出可归档、可在 CI 复现的环境基线。

---

1.0 本章目标

1. 能解释 26.0.0 与 6.0.0(20) 两种格式的断代原因，并在工程里写对每一个版本字段。
2. 能完成 DevEco Studio 26.0.0 首次配置（SDK 勾选、受管 Node、模拟器含 Car、代理与 ohpm 源），产出可归档的环境清单。
3. 能逐字段说明 app.json5 / module.json5 / build-profile.json5 / oh-package.json5 / hvigorfile.ts 的职责，回答「改配置该改哪个文件」。
4. 能用 hvigorw 命令行完成 clean → sync → assembleHap → assembleApp，区分 signed 与 unsigned 产物，并用 hdc 完成安装与启动。
5. 能用「编译期 → 运行期 → 降级」三段式写出兼容代码，并用 CapabilityGate 把 canIUse 判定收口到一处。

---

1.1 版本名词与格式断代

1.1.1 三类版本号各管一件事

类别	典型值	出现在哪	变更后果
SDK / API 版本	26.0.0	build-profile.json5 的三个字段	决定能调用哪些 API、系统按哪套行为对待你
应用版本	versionCode: 1000000 / versionName: "1.0.0"	AppScope/app.json5	决定商店能否覆盖安装、用户看到什么
依赖版本	"@scope/pkg": "1.2.3"	oh-package.json5	决定三方库行为，与 SDK 版本无关

术语：编译期 SDK（compileSdkVersion）——编译器按哪个版本的 API 声明做类型检查，只影响「能否编译通过」，不影响运行行为。 术语：运行目标（targetSdkVersion）——系统按哪个版本的默认行为约束应用。它是行为开关：权限提示、动效、字体缩放、返回键语义都可能随之改变。 术语：兼容下限（compatibleSdkVersion）——低于此版本的设备无法安装。

1.1.2 格式断代与语义

时代	格式	例子	括号里的 N
API 26 之前	X.Y.Z(N)	6.0.0(20)	OpenHarmony 底座的 API Level
API 26 起	X.Y.Z	26.0.0	不再有括号

换格式的原因是旧写法把「底座 Level」硬编码在括号里，导致 HarmonyOS 与底座两条版本线纠缠——同一个 N 可能对应不同能力集合。新格式把语义固定下来：X 主版本可能含 API 修改与行为变更，必须适配；Y 次版本新增功能，向后兼容；Z 修订版本修问题，向后兼容。

但断代不等于替换：compatibleSdkVersion 指向 API 20，而 20 仍在旧体系内，必须写旧格式。三种格式在同一文件里共存不是笔误：

// build-profile.json5（工程根，节选）
{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "runtimeOS": "HarmonyOS",
        // 编译期用 26 的 API 声明 → 可引用 API 26 新增能力
        "compileSdkVersion": "26.0.0",
        // 系统按 26 的行为约束应用 → 需按「向 26.0.0 升级」清单自查
        "targetSdkVersion": "26.0.0",
        // 兼容下限仍是 20 → 必须留在旧格式
        "compatibleSdkVersion": "6.0.0(20)"
      }
    ]
  }
}

1.1.3 应用版本与 SDK 版本的隔离

// AppScope/app.json5
{
  "app": {
    "bundleName": "com.example.officeflow",
    "vendor": "example",
    "versionCode": 1000000,        // 正整数，仅用于商店比较大小，每次提审递增
    "versionName": "1.0.0",        // 字符串，仅用于展示
    "icon": "$media:app_icon",     // 必须是分层图标
    "label": "$string:app_name"    // 走资源引用才能多语言
  }
}

bundleName 上架后不可更改，换包名等于换一个应用。versionCode 与 compatibleSdkVersion 没有任何换算关系，写成 "26.0.0" 会被构建工具直接拒绝。

版本差异提示：全书 compileSdkVersion / targetSdkVersion 恒为 26.0.0，compatibleSdkVersion 恒为 6.0.0(20)。凡偏离处正文会显式说明。

误区：以为「兼容下限写旧格式」是工具还没跟上。真实原因是格式与语义绑定：6.0.0(20) 表达「版本 6.0.0，底座 Level 20」，而 6.0.0 无法表达底座号。稳妥做法是让 IDE 生成后再改数值，不要手敲字符串。

---

1.2 DevEco Studio 26.0.0 的安装与首次配置

1.2.1 SDK 从哪来（本节最关键）

版本门槛：自 DevEco Studio 5.0（5.0.0(12)）起，SDK 已随 IDE 预置；到 26.0.0 时代，单独下载安装 SDK 已成历史。

这条改动的实际影响：

• 不需要「先装 IDE、再去官网下 SDK、再指定路径」这套旧流程。
• SDK 与 IDE 版本严格绑定，不能跨版本混搭——用 26.0.0 的 IDE 配 24 的 SDK 会直接构建失败。
• IDE 升级 = SDK 升级。升级 IDE 后必须重新执行一次 sync，让工程重新解析 SDK。
• SDK 路径不要手动搬移或改名。IDE 记录了原路径，搬走后报的是「找不到 SDK」而不是「路径不对」，排查方向容易跑偏。

安装后先确认三处一致：

查看位置	应看到	不一致时的动作
Help > About DevEco Studio	26.0.0 Release	跨大版本升级先读版本说明、完整备份工程，升级后必须重新 sync
Help > About HarmonyOS SDK	HarmonyOS SDK 26.0.0	检查是否装了旧 SDK 目录并被优先选中
Settings > SDK 的安装路径	位于 IDE 安装目录下	恢复默认路径后重新 sync

1.2.2 SDK 勾选

分组	勾选项	用途	漏勾的后果
SDK Platforms	HarmonyOS SDK（API 26）	API 声明与运行时库	无法编译
SDK Platforms	Phone / Tablet / 2in1 / Wearable / Car	目标设备类型资源	对应形态无法构建
SDK Tools	Command Line Tools	提供 hvigorw / ohpm / codelinter	命令行构建与 CI 不可用
SDK Tools	Toolchains	编译工具链与 hdc	无法安装到设备
SDK Tools	Emulator	模拟器运行时	无设备可调试

版本门槛：API 26 起 SDK Platforms 新增 Car 设备类型。 需要车机形态的工程必须勾选，并在模块的 deviceTypes 中声明 car，否则构建期报设备类型不匹配。

1.2.3 受管 Node / ohpm / hvigor 的版本绑定

三者是一条链，不要拆开：

DevEco Studio 26.0.0
  ├── 受管 Node     ← IDE 内置，不读系统 PATH
  ├── ohpm          ← 包管理：装依赖、发库
  └── hvigor        ← 构建引擎，版本由「工程内配置」决定，随工程走

关键机制：hvigor 的版本由工程声明，不由 IDE 决定。所以同一 IDE 打开不同工程可能使用不同 hvigor——这是特性，它保证老工程升级 IDE 后仍能用原构建引擎跑通。

// hvigor/hvigor-config.json5
{
  "hvigorVersion": "26.0.0",                    // 与开发套件版本对齐
  "dependencies": {
    "@ohos/hvigor-ohos-plugin": "26.0.0"        // 提供 appTasks / hapTasks / harTasks / hspTasks
  },
  "execution": {
    "daemon": true,        // 常驻进程，重复构建更快
    "incremental": true,   // 增量构建
    "parallel": true,      // 多模块并行
    "typeCheck": false     // 单模块快速构建可关；CI 上建议开
  },
  "nodeOptions": {
    "maxOldSpaceSize": 8192                     // 大型多模块工程易 OOM，8 GB 是常见起点
  }
}

验证版本：

# 在 DevEco Studio 内置终端执行（环境变量已注入）
node -v && ohpm -v && hvigorw -v

误区：用系统安装的 Node.js 跑 hvigorw。受管 Node 与构建工具链严格绑定，用系统 Node 常见后果是 EBADENGINE，或更隐蔽的「构建成功但产物异常」。项目命令一律在 IDE 内置终端执行，CI 上显式使用 Command Line Tools 附带的 Node。

1.2.4 模拟器（含 Car）

在 Device Manager 中：选择模板（Phone / Tablet / 2in1 / Wearable / Car）→ 下载系统镜像 → 启动并确认 hdc list targets 能看到设备。镜像体积大，先确认磁盘余量（建议 ≥ 30 GB）。

Windows 上模拟器依赖虚拟化，启动即失败时优先查：

现象	常见原因	处理
启动卡在 0%	Hyper-V / WHPX 未启用	在「启用或关闭 Windows 功能」中开启虚拟机平台
能看到设备但装不上	hdc 版本与设备不匹配	hdc kill -r 重启服务，或换用 IDE 附带的 hdc

1.2.5 代理与 ohpm 源

企业网络下这两处不配好，sync 必然失败：

# 1) 代理：Settings > HTTP Proxy 填地址与端口；内网直连选 No proxy
# 2) ohpm 源：
ohpm config get registry
ohpm config set registry https://your-company-mirror.example.com/ohpm/

配置项	位置	作用
HTTP Proxy	Settings > HTTP Proxy	IDE 与 hvigor 的下载流量
ohpm registry	ohpm config	oh-package.json5 中三方库依赖的解析源

误区：只想改 ohpm 源，却顺手改了系统 npm 源。hvigor 的依赖解析走 ohpm 与工程级配置，改系统 npm 源对构建无影响，反而污染其它项目。改动范围最小化，并写进团队文档。

---

1.3 工程解剖

1.3.1 顶层结构

OfficeFlow/
├── AppScope/                        # 应用级全局配置与资源（整个 App 唯一一份）
│   ├── app.json5                    # bundleName / versionCode / icon / label
│   └── resources/base/              # 应用级图标、名称字符串
├── entry/                           # 默认生成的 HAP 模块（唯一可安装入口）
│   ├── src/main/
│   │   ├── ets/
│   │   │   ├── entryability/EntryAbility.ets   # UIAbility 入口
│   │   │   ├── pages/Index.ets                 # 首页
│   │   │   └── common/                         # 模块内公共代码
│   │   ├── resources/                          # 模块级资源（限定词目录）
│   │   └── module.json5                        # 模块声明（能力 / 权限 / 页面）
│   ├── build-profile.json5          # 模块级构建配置
│   ├── hvigorfile.ts                # 模块级构建任务声明
│   ├── oh-package.json5             # 模块级依赖声明
│   └── obfuscation-rules.txt        # 混淆规则
├── hvigor/hvigor-config.json5       # 构建引擎版本与参数
├── hvigorfile.ts                    # 工程级构建任务声明
├── build-profile.json5              # 工程级构建配置（products / signingConfigs / modules）
├── oh-package.json5                 # 工程级依赖声明
├── oh-package-lock.json5            # 依赖锁（必须入库）
└── oh_modules/                      # 依赖实体（不入库，由 sync 生成）

一句话记住分层：AppScope 管「这个 App 是谁」，模块管「这个模块能做什么」，两个 build-profile 管「怎么构建」。

1.3.2 entry 与 module.json5

// entry/src/main/module.json5
{
  "module": {
    "name": "entry",                            // 模块名，工程内唯一
    "type": "entry",                            // entry / feature / shared
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",              // 启动时优先进这个 Ability
    "deviceTypes": ["phone", "tablet", "2in1"], // 声明支持的设备形态
    "deliveryWithInstall": true,                // 随应用一起安装
    "installationFree": false,                  // 是否支持免安装（元服务用）
    "pages": "$profile:main_pages",             // 页面路由表
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,                       // 是否允许外部应用拉起
        "skills": [
          // 桌面入口必须声明这两项，否则桌面无图标
          { "entities": ["entity.system.home"], "actions": ["action.system.home"] }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:reason_internet",
        "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
      }
    ]
  }
}

字段按「四个问题」归类：

问题	相关字段	说明
我是谁	name / type / description	type 决定产物形态：entry/feature 出 HAP，shared 出 HSP
装到哪些设备	deviceTypes	与 SDK 已勾选设备类型求交；交集为空则无法安装
入口在哪	mainElement / abilities[].srcEntry / skills	桌面点击 → 匹配 action.system.home → 拉起 mainElement
能用什么权限	requestPermissions	只声明，运行时仍需申请

术语：main_pages——resources/base/profile/main_pages.json 维护的页面路径清单，只服务传统页面路由。本教程主线路由走 Navigation + route_map.json 系统路由表（第 4 章），两者职责不同，不要混用。

1.3.3 resources 限定词目录

entry/src/main/resources/
├── base/                        # 默认资源，任何限定词目录缺失时回落到这里
│   ├── element/
│   │   ├── string.json          # 字符串：$r('app.string.xxx')
│   │   ├── color.json           # 颜色：  $r('app.color.xxx')
│   │   ├── float.json           # 尺寸：  $r('app.float.xxx')，值写 "16vp"
│   │   └── boolean.json         # 布尔开关
│   ├── media/                   # 图片、图标
│   └── profile/
│       ├── main_pages.json      # 页面清单
│       └── route_map.json       # Navigation 系统路由表
├── zh_CN/element/string.json    # 中文文案覆盖
├── en_US/element/string.json    # 英文文案覆盖
├── dark/element/color.json      # 深色模式颜色覆盖
└── rawfile/                     # 原样打包的资产（HTML / 字体 / 契约 JSON）

匹配规则是逐级回落：设备为中文深色模式时，zh_CN 命中文案、dark 命中颜色、其余回落到 base。因此 base 必须是完整可用的那一套，限定词目录只放差异项。

误区：在 base/element/color.json 里只放浅色值，dark/element/color.json 里只放一部分覆盖。深色模式下少数控件仍是浅色——因为缺失项回落到了 base。正确做法是两套 key 集合完全一致，用脚本或 Code Linter 校验。

1.3.4 oh-package.json5 / build-profile.json5 / hvigorfile.ts

// lib_ui/oh-package.json5
{
  "name": "lib_ui",
  "version": "1.0.0",
  "main": "Index.ets",                // 对外导出面只走这一个文件
  "dependencies": {
    "lib_base": "file:../lib_base",   // 本地模块依赖走相对路径，不写版本号
    "@scope/pkg": "1.2.3"             // 三方库写精确版本，禁用 ^ / ~
  }
}

HSP 的动态依赖在使用方模块声明，不写在 HSP 自己的 oh-package.json5 里。例如 entry 要动态加载 lib_ui 时，在 entry/oh-package.json5 中写：

// entry/oh-package.json5（节选）—— 使用方声明动态依赖
{
  "dynamicDependencies": {
    "lib_ui": "file:../lib_ui"
  }
}

工程级 build-profile.json5 的四个顶层块：

顶层块	职责	常见改动
app.signingConfigs	签名材料（证书 / Profile / 密钥库）	首次打开工程时由 IDE 生成
app.products	产品形态（版本三件套、runtimeOS）	改 targetSdkVersion、加渠道
app.buildModeSet	构建模式（debug / release）的编译参数	是否混淆、是否带符号表
modules	参与构建的模块清单与目标	新增模块后必须在此登记

模块级 build-profile.json5 只管本模块怎么编译。注意 apiType 只有 stageMode 一个有效值：

// entry/build-profile.json5
{
  "apiType": "stageMode",
  "buildOptionSet": [
    {
      "name": "release",
      "arkOptions": {
        "obfuscation": {
          "ruleOptions": { "enable": true, "files": ["./obfuscation-rules.txt"] }
        }
      }
    }
  ],
  "targets": [{ "name": "default" }, { "name": "ohosTest" }]
}

hvigorfile.ts 只做一件事：声明本层提供哪些内置构建任务。

// 工程根目录 hvigorfile.ts —— 应用级任务
export { appTasks } from '@ohos/hvigor-ohos-plugin';

// entry/hvigorfile.ts —— HAP 模块任务
export { hapTasks } from '@ohos/hvigor-ohos-plugin';

// lib_base/hvigorfile.ts —— HAR 模块任务
export { harTasks } from '@ohos/hvigor-ohos-plugin';

// lib_ui/hvigorfile.ts —— HSP 模块任务
export { hspTasks } from '@ohos/hvigor-ohos-plugin';

版本差异提示：如果配置里出现 faMode、或工程根目录存在 config.json，那是 FA 模型时代的工程。本教程不涉及，也不要把那套写法带进新工程。

---

1.4 构建链路

1.4.1 三个阶段

sync   →   build   →   package
依赖解析     编译 ArkTS     打包 + 签名
生成 oh_modules   生成中间产物    产出 HAP / APP

阶段	触发方式	产出	失败时的典型症状
sync	打开工程、改 oh-package.json5、hvigorw --sync	oh_modules/、资源索引	「找不到模块」
build	hvigorw assembleHap	build/ 下中间产物	类型报错、ArkTS 限制报错
package	含在 assemble 内	.hap / .app	签名失败、资源冲突

1.4.2 hvigorw 命令

命令一律在工程根目录、IDE 内置终端执行。

命令	作用	常用参数
hvigorw clean	清空构建产物	--no-daemon
hvigorw --sync	依赖同步与工程解析	--no-daemon
hvigorw assembleHap	构建 HAP	--mode module -p module=entry@default -p product=default -p buildMode=debug
hvigorw assembleHar / assembleHsp	构建 HAR / HSP	--mode module -p module=lib_base@default
hvigorw assembleApp	构建可上架 .app	--mode project -p product=default -p buildMode=release
hvigorw --stop-daemon	停掉常驻构建进程	排查「改了代码没生效」时先执行它

参数	取值	说明
--mode	module / project	单模块组装 vs 整包组装
-p module	entry@default	模块名@目标名，对应模块 build-profile 的 targets
-p product	default	对应工程 build-profile 的 products[].name
-p buildMode	debug / release	决定是否混淆、是否带调试符号
--no-daemon	无值	单次执行，不复用常驻进程；CI 上建议加

# 推荐的命令行出包序列（debug 包）
hvigorw --stop-daemon
hvigorw clean --no-daemon
hvigorw --sync --no-daemon
hvigorw assembleHap --mode module -p module=entry@default -p product=default -p buildMode=debug --no-daemon

1.4.3 产物目录与 signed / unsigned

entry/build/default/outputs/default/
├── entry-default-signed.hap      # 已签名 —— 可直接 hdc install
└── entry-default-unsigned.hap    # 未签名 —— 不能直接安装

build/outputs/default/
├── officeflow-default-signed.app
└── officeflow-default-unsigned.app

产物	能否直接装到设备	用途
*-signed.hap	能	本地调试、内部测试分发
*-unsigned.hap	不能	交给流水线统一签名，或上架前由 AGC 再签名
*-signed.app	能（走 AGC 通道）	上架提交
*-unsigned.app	不能	交由 AGC 完成最终签名

误区：拿到 unsigned.hap 直接安装报错后，去反复改 module.json5。unsigned 的定义就是不可安装，症状与配置无关。先确认产物名带不带 signed，再看签名材料。

1.4.4 hdc 安装与调试

命令	作用
hdc list targets	列出已连接设备 / 模拟器
hdc install <path>.hap / hdc uninstall <bundleName>	安装 / 卸载
hdc shell aa start -a EntryAbility -b com.example.officeflow	拉起指定 Ability
hdc shell aa force-stop com.example.officeflow	强杀应用进程
hdc shell bm dump -n com.example.officeflow	查看已安装包信息（版本、权限、模块）
hdc file recv <设备路径> <本地路径>	从设备取文件（导出日志、dump）
hdc hilog	查看设备日志，建议配合 grep
hdc kill -r	重启 hdc 服务，解决「设备突然不可见」

hdc list targets
hdc install entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.officeflow
hdc hilog | grep OfficeFlow

误区：设备不可见就先怀疑代码。hdc 是有状态的：USB 重插、模拟器重启后服务端常处于半失效状态。标准顺序是 hdc kill -r → hdc list targets → 重启设备，比翻构建日志快得多。

---

1.5 兼容策略三段式

compatibleSdkVersion = 6.0.0(20) 意味着编译期是 26、运行环境可能是 20。这个错配不会在编译期暴露，只在运行时崩。所以任何 API 21+ 的能力都走三段式。

第一段 编译期：声明目标与下限     → 决定「能不能编译过」
第二段 运行期：canIUse 判定能力    → 决定「这台上有没有这个能力」
第三段 降级  ：提供等价的旧实现     → 决定「没有能力时用户看到什么」

1.5.1 第一段：编译期声明

字段	值	作用
compileSdkVersion	26.0.0	能用 26 的 API 声明，不保证设备支持
targetSdkVersion	26.0.0	系统按 26 的行为约束应用
compatibleSdkVersion	6.0.0(20)	覆盖 API 20 及以上设备

误区：以为把 compatibleSdkVersion 调高到 26.0.0 就能规避兼容问题。结果是能安装的设备大幅减少，兼容问题从「运行时偶发」变成「装不上」，覆盖量损失远比 bug 严重。正确做法是保留下限，用第二、三段兜住。

1.5.2 第二段：运行期能力判定

canIUse 是 ArkTS 的全局内置函数，接收 SystemCapability 字符串、返回布尔值。

SystemCapability	覆盖能力
SystemCapability.Communication.NetStack	网络栈（HTTP / Socket）
SystemCapability.Multimedia.Camera.Core	相机核心能力
SystemCapability.DistributedHardware.DeviceManager	分布式设备管理
SystemCapability.Ability.AbilityRuntime.Core	应用模型运行时核心

术语：SystemCapability——系统能力的字符串标识，是「设备上有没有这个能力」的唯一权威判断依据。完整清单以官方「SystemCapability 清单」为准，不要凭字符串猜。

canIUse 只回答「能力是否存在」，不回答「版本是否够新」。需要按 API 版本精确分档时配合 deviceInfo.sdkApiVersion：

import { deviceInfo } from '@kit.BasicServicesKit';

const isApi26OrAbove: boolean = deviceInfo.sdkApiVersion >= 26;

1.5.3 第三段：降级实现 + 统一收口

真实工程里 canIUse 最怕散落在各处：今天业务里判一遍、明天工具类里再判一遍，判定口径迟早不一致。把它收口成一个类。

// lib_base/src/main/ets/gate/CapabilityGate.ets
import { hilog } from '@kit.PerformanceAnalysisKit';
import { deviceInfo } from '@kit.BasicServicesKit';

const DOMAIN: number = 0x0000;
const TAG: string = 'CapabilityGate';

/**
 * 运行期兼容策略的唯一下沉点。
 * 约定：全工程只有这里出现 canIUse，业务代码只调用 supported / pick。
 */
export class CapabilityGate {
    // 能力在进程生命周期内不会变化，判定结果缓存，避免重复探测
    private static readonly probeCache: Map<string, boolean> = new Map<string, boolean>();

    /** 判定设备是否具备某 SystemCapability。 */
    static supported(sysCap: string): boolean {
        const cached: boolean | undefined = CapabilityGate.probeCache.get(sysCap);
        if (cached !== undefined) {
            return cached;
        }
        let ok: boolean = false;
        try {
            ok = canIUse(sysCap);
        } catch (err) {
            // 防御性兜底：即便实现变化也不向上传播
            ok = false;
        }
        CapabilityGate.probeCache.set(sysCap, ok);
        hilog.info(DOMAIN, TAG, 'probe %{public}s -> %{public}s, sdkApi=%{public}d',
            sysCap, String(ok), deviceInfo.sdkApiVersion);
        return ok;
    }

    /** 有增强链路走增强，没有走降级；调用方不必关心判定细节。 */
    static pick<T>(sysCap: string, enhanced: () => T, fallback: () => T): T {
        return CapabilityGate.supported(sysCap) ? enhanced() : fallback();
    }
}

调用侧只关心两条链路，判定与日志都被吃掉（CapabilityGate 由 lib_base 根 Index.ets 统一导出）：

import { CapabilityGate } from 'lib_base';

const DISTRIBUTED: string = 'SystemCapability.DistributedHardware.DeviceManager';

export function listCollaborators(): Promise<string[]> {
    return CapabilityGate.pick<Promise<string[]>>(
        DISTRIBUTED,
        (): Promise<string[]> => discoverRemoteDevices(),   // 增强链路
        (): Promise<string[]> => Promise.resolve(['local']) // 降级链路：保证功能可用且不报错
    );
}

function discoverRemoteDevices(): Promise<string[]> {
    return Promise.resolve([]);
}

段位	判定依据	出现在哪	缺失时的失败表现
编译期	build-profile.json5 三个版本字段	配置，不在代码里	编译失败（明显、易发现）
运行期	canIUse + deviceInfo.sdkApiVersion	只在 CapabilityGate 内	崩溃（隐蔽）
降级	业务回调	业务调用点	功能空白但可用

版本门槛：本节代码不依赖 API 26 新增能力，在兼容下限 20 上可直接运行。后续章节凡出现 > 版本门槛：API 26 新增 的写法，都必须落在 CapabilityGate.pick 的增强分支里，不允许直接写在主流程上。

---

1.6 26.0.0 工具链增量

先建立一条认知：以下四项全部是 IDE（工具链）能力，不是运行时 API。它们不改变设备行为，因此不需要 canIUse 判定，也不需要写进业务代码的兼容分支。

能力	属于哪一层	解决什么问题	代码是否需要改动
8 档断点 UI 预览	IDE 预览器	一次看清多宽度档位下的布局	不需要；但布局本身要按断点写（第 3 章）
Code Scanner 资源泄漏检查	IDE 静态检查	静态发现未释放的监听、Context、媒体资源	不需要改 API，但需按检查结果修代码
dump 文件解析	IDE 分析器	直接打开堆 / 线程 dump 定位内存与卡顿	不需要，用于定位阶段
Car 模拟器	IDE 运行环境	车机形态的本地调试	需要：deviceTypes 加 car 并做适配

1.6.1 8 档断点 UI 预览

预览器支持一次性渲染 8 个宽度档位（在 xs / sm / md / lg / xl / xxl 六档基础上新增细分档位，合计 8 档；具体档位划分以 DevEco 26.0.0 实际为准），用于对照同一份布局在不同窗口宽度下的表现。

要点：断点在布局代码里定义，预览器只负责按宽度渲染。所以 GridRow 的断点阈值与各档位列数必须自己写全，预览才有意义（见 3.7）。键盘 / 鼠标与触摸的差异不在预览器覆盖范围内，2in1 / car 的交互仍需真机或模拟器验证。

// 用于预览对照的最小骨架：断点由代码声明，预览器按宽度渲染（ApprovalCard 组件见第 3 章）
GridRow({
    columns: { xs: 4, sm: 4, md: 8, lg: 12, xl: 12 },
    gutter: { x: 12, y: 12 }
}) {
    GridCol({ span: { xs: 4, sm: 2, md: 4, lg: 6, xl: 6 } }) {
        ApprovalCard()
    }
}

术语：断点——窗口宽度的档位，是「同一份代码适配多端」的判断依据。断点是布局层概念，与 SDK 版本无关；26.0.0 变的只是预览器能一次显示几档。

1.6.2 Code Scanner 资源泄漏检查

Code Scanner 在静态分析阶段扫描代码，重点覆盖资源泄漏模式：注册监听未注销、持有长生命周期 Context、媒体 / 文件句柄未关闭、定时器未清理。

时机	动作
提交前	对本次改动的目录跑一次扫描，数量应归零
合并前	对模块全量扫描，新增告警必须说明原因
发布前	全工程扫描作为门禁（第 10 章接进 CI）

它能识别的典型泄漏模式：

aboutToAppear(): void {
    this.ctx.on('change', this.onChanged);
}
aboutToDisappear(): void {
    // 错误：注册了监听却从不注销
}

1.6.3 dump 文件解析

应用异常退出或被判定卡顿后会产生 dump 文件（堆快照、线程栈）。26.0.0 的 IDE 可直接解析，用于找到内存占用最高的对象与引用链、找到主线程阻塞时的调用栈、并对照业务代码定位到具体组件。

# 从设备取出 dump 文件
hdc file recv /data/log/faultlog/faultlogger/ ./faultlog/
# 然后在 DevEco Studio 中直接打开该文件，用内置解析视图查看引用链与调用栈

误区：设备一崩就先翻业务日志。dump 回答的是「谁还持有这个对象」「主线程当时卡在哪个栈」，这是日志答不了的。先看 dump，再看日志。

1.6.4 Car 模拟器

Car 模拟器提供车机形态的运行环境，差异不只是屏幕尺寸：

维度	手机	车机
窗口宽度	常见 xs / sm	常见 lg / xl
输入方式	触摸	触摸 + 旋钮 / 方向盘按键 + 语音
代码侧动作	无	deviceTypes 声明 car；布局按大档位设计

// entry/src/main/module.json5（节选）—— 未声明 car 时包无法安装到车机
{ "module": { "name": "entry", "type": "entry", "deviceTypes": ["phone", "tablet", "2in1", "car"] } }

版本门槛：Car 设备类型在 API 26 起随 SDK 提供。下行兼容到 API 20 时，deviceTypes 多写 car 是安全的（手机设备会忽略不匹配形态），但不要把车机专属交互无条件写进主流程。

---

1.7 签名与设备调试闭环

类型	材料来源	用途	有效期
调试签名	IDE 自动生成（需登录华为开发者账号）	装到已注册的调试设备	有期限，过期需重新生成
发布签名	AGC 申请 .cer + .p7b	上架与正式分发	按 AGC 规则

签名材料共三件用于构建签名：.p12（密钥库，存私钥）、.cer（公钥证书）、.p7b（Profile，描述「哪个 bundle、哪台设备、能用哪些权限」）；申请期另需一件 .csr（证书请求，用于换发 .cer，用完归档）。

// build-profile.json5（节选）—— 密码严禁入库，走 CI 密钥注入
{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "HarmonyOS",
        "material": {
          "storeFile": "./signature/officeflow.p12",
          "storePassword": "<从环境变量注入>",
          "keyAlias": "debugKey",
          "keyPassword": "<从环境变量注入>",
          "certpath": "./signature/officeflow.cer",
          "profile": "./signature/officeflow.p7b",
          "signAlg": "SHA256withECDSA"
        }
      }
    ]
  }
}

误区：把签名材料与明文密码一起提交到仓库。后果不只是安全问题——Profile 过期后所有人构建同时失败，修复需要重新申请材料并回滚代码。签名目录必须在 .gitignore 中。

真机调试时设备需在 AGC 登记（UDID 白名单），否则 Profile 不覆盖该设备、安装必失败；模拟器通常不需要。推荐用 IDE 自动签名功能一键生成调试材料。

安装失败排查顺序：

报错方向	先查什么	再看什么
签名相关	产物是否带 signed	材料是否过期、Profile 是否覆盖该设备
设备类型不匹配	module.json5 的 deviceTypes	SDK 是否勾选对应设备类型
版本不兼容	设备系统版本 vs compatibleSdkVersion	是否需降低下限
安装被拒（已存在）	是否装了不同签名的同包名应用	先 hdc uninstall 再装
完全连不上设备	hdc list targets	hdc kill -r → 重插 → 重启设备

---

1.8 构建可复现性与 CI 前置

「我本地能构建，CI 不能」几乎总是三样东西没锁住。第 11 章展开流水线，这里先建立基线。

对象	文件	为什么
依赖树	oh-package-lock.json5	锁定每个依赖的实际解析版本，避免不同人装到不同版本
构建引擎	hvigor/hvigor-config.json5	锁定 hvigor 与插件版本，避免构建行为漂移
依赖声明	全部 oh-package.json5	声明依赖来源与版本

# .gitignore（节选）—— 这五类必须忽略
build/                 # 构建产物
oh_modules/            # 依赖实体，由 sync 生成
.hvigor/               # 构建缓存
signature/             # 签名材料，含私钥
local.properties       # 本机路径与代理，因人而异

命令行构建依赖 SDK 路径环境变量，CI 上显式设置，不要依赖 shell 隐式继承：DEVECO_SDK_HOME 指向 Command Line Tools 附带的 SDK；PATH 追加 <SDK>/toolchains 与 IDE 的 Node 目录。

# CI 最小流水线：固定序列 clean → sync → assemble，不要跳步
set -e
export DEVECO_SDK_HOME="$PWD/tools/sdk"

node -v && ohpm -v && hvigorw -v          # 打印版本，出问题时一眼定位
hvigorw --sync --no-daemon
hvigorw assembleHap --mode module \
  -p module=entry@default -p product=default -p buildMode=debug --no-daemon
hvigorw assembleApp --mode project \
  -p product=default -p buildMode=release --no-daemon

误区：CI 上跑完 clean 不跑 sync。clean 会删除构建目录，而 oh_modules 是否被清取决于清理范围；一旦被清掉，后续 assembleHap 会报「找不到模块」。

---

1.9 常见误区

误区 1：把 compatibleSdkVersion 写成新格式

错误写法

"compatibleSdkVersion": "26.0.0"

正确写法

"compileSdkVersion": "26.0.0",
"targetSdkVersion": "26.0.0",
"compatibleSdkVersion": "6.0.0(20)"

为什么错：compatibleSdkVersion 指向 API 20，而 20 仍在 X.Y.Z(N) 体系内。写成 26.0.0 会让工具按 API 26 解析安装下限，结果是绝大多数设备装不上。三个字段语义不同，不能一起改成新格式。

误区 2：以为要单独下载安装 SDK

错误写法

# 到官网单独下载 SDK 压缩包 → 解压到自定义目录 → 在 IDE 里指定路径

正确写法

# 只安装 DevEco Studio 26.0.0，SDK 已随 IDE 预置
# 在 Settings > SDK 确认路径位于 IDE 安装目录下即可

为什么错：自 DevEco Studio 5.0（5.0.0(12)）起 SDK 已随 IDE 预置，手动指定外部 SDK 目录会造成版本错配——典型症状是编译报找不到某 API 声明，而该 API 明明存在。

误区 3：把 IDE 能力当成 API 去做 canIUse 判定

错误写法

if (CapabilityGate.supported('SystemCapability.IDE.Previewer')) {
  this.enableMultiBreakpointPreview();
}

正确写法

// IDE 能力不需要运行期判定，只有设备能力才需要
const ok: boolean = CapabilityGate.supported('SystemCapability.Communication.NetStack');

为什么错：8 档断点预览、Code Scanner、dump 解析都是开发工具的能力，运行在 IDE 里而非设备上。canIUse 查询的是设备 SystemCapability，判定 IDE 能力必然恒为 false，写出永远走不到的分支。

误区 4：改了 module.json5 却不跑 sync

错误写法

hvigorw assembleHap --no-daemon

正确写法

hvigorw --sync --no-daemon && hvigorw assembleHap --no-daemon

为什么错：module.json5 的变更需要重新解析并生成中间产物（权限、页面清单、路由表索引）。跳过 sync 时会复用陈旧索引，表现为「权限声明了但运行时申请不到」「新页面找不到」这类与配置无关的诡异问题。

误区 5：新增模块只在 oh-package.json5 声明依赖

错误写法

// 顶层 oh-package.json5 加了依赖，但工程 build-profile.json5 的 modules 没登记
{ "dependencies": { "lib_ui": "file:../lib_ui" } }

正确写法

// 工程 build-profile.json5 必须同步登记，否则模块不参与构建
{ "modules": [{ "name": "lib_ui", "srcPath": "./lib_ui", "targets": [{ "name": "default" }] }] }

为什么错：oh-package.json5 描述的是「依赖了谁」，build-profile.json5 的 modules 描述的是「谁参与构建」。漏登记时依赖能解析、代码能 import，但产物里没有对应模块，表现为运行时报「模块不存在」或资源缺失。

误区 6：忽略设备形态与 Profile 的匹配

错误写法

"deviceTypes": ["phone"]      // 却想在平板上验证折叠屏布局

正确写法

"deviceTypes": ["phone", "tablet", "2in1", "car"]

为什么错：deviceTypes 与 SDK 已勾选设备类型求交，交集为空则无法安装；只声明 phone 的包装不上平板，于是「多端适配」这件事在验证环节就被跳过了，直到提审才发现问题。

---

1.10 实践任务

任务：搭出可命令行构建的 HelloOffice

任务描述

1. 安装并配置 DevEco Studio 26.0.0，按 1.2.2 勾选 SDK，创建 Phone 模拟器（Car 可后补）。
2. 新建 Stage 模型空工程，bundleName 设为 com.example.hellooffice，工程路径不含中文与空格。
3. 修正 build-profile.json5 三个版本字段为 26.0.0 / 26.0.0 / 6.0.0(20)。
4. 补全 AppScope 与 entry 的 string.json / color.json，新增 en_US 与 dark 限定词目录（key 集合与 base 完全一致）。
5. 把 deviceTypes 扩为 ["phone", "tablet", "2in1", "car"]，声明 ohos.permission.INTERNET。
6. 新建 lib_base/src/main/ets/gate/CapabilityGate.ets，实现 1.5.3 的完整代码，并从 lib_base 根 Index.ets 统一导出。
7. 用命令行完成 clean → sync → assembleHap，装到模拟器并拉起，用 hdc hilog 抓到自己打印的一行日志。

验收 checklist

• [ ] Help > About DevEco Studio 显示 26.0.0 Release，Help > About HarmonyOS SDK 显示 HarmonyOS SDK 26.0.0
• [ ] node -v / ohpm -v / hvigorw -v 在 IDE 内置终端均可执行且版本匹配
• [ ] build-profile.json5 中 compatibleSdkVersion 为字符串 "6.0.0(20)"（带括号）
• [ ] resources/base 与 resources/dark 的 color key 集合一致（脚本 diff 校验）
• [ ] resources/base 与 zh_CN / en_US 的 string key 集合一致
• [ ] hvigorw assembleHap 产出 entry-default-signed.hap，hdc install 成功
• [ ] hdc shell aa start 能拉起应用，hdc hilog 能看到 CapabilityGate 的探测日志
• [ ] 故意安装一次 unsigned 产物，记录报错原文用于后续对照
• [ ] .gitignore 已含 build/、oh_modules/、.hvigor/、signature/、local.properties
• [ ] oh-package-lock.json5 已入库

交付物清单

交付物	形式	验收点
环境清单	Markdown（贴到工程 README）	含 IDE / SDK / Node / ohpm / hvigor / 设备六项版本
HelloOffice 工程	可编译目录	命令行可出 signed HAP
CapabilityGate.ets	源码	只有此类出现 canIUse；supported / pick 齐备
资源一致性校验脚本	bash	能 diff 两个限定词目录的 key 集合
构建命令记录	Markdown	记录完整命令与产物路径，可被他人复现

---

1.11 延伸阅读

• 官方文档 → 版本说明 → HarmonyOS 开发套件版本列表（确认当前最新版与配套 IDE、SDK）
• 官方文档 → 版本说明 → 应用升级适配指导（向 26.0.0 升级）（行为变更清单，改 targetSdkVersion 前必读）
• 官方文档 → 应用开发导读 → DevEco Studio 使用指南 → 工程结构（AppScope / 模块 / 资源目录的权威说明）
• 官方文档 → 应用开发导读 → DevEco Studio 使用指南 → 编译构建（hvigor）（hvigorw 命令与参数全集）
• 官方文档 → API 参考 → SystemCapability 清单（canIUse 判定的权威依据）
• 官方文档 → 应用开发 → 应用签名与 Profile 申请（调试签名与发布签名的完整材料说明）

---

上一章：第 0 章 学习准备　|　下一章：第 2 章 ArkTS 语言核心

📄 附录 A 状态管理 V1 → V2 迁移速查 A-v1-v2-cheatsheet.md✓ 标记已学

本附录是全书唯一允许出现 V1 写法的地方，且全部以"迁移对照"的立场书写。V1 装饰器未被官方废弃、仍可编译运行，但新项目一律采用 V2；这里的内容只服务于两件事：读懂存量老代码，把在跑的老工程迁到 V2。

---

A.0 使用说明与立场

问题	结论
V1 还能用吗	能。官方未废弃 @State / @Link 等，编译与运行不受影响
要不要迁移	新项目不必考虑；存量工程按 A.4 清单渐进迁移，不建议大爆炸式重写
迁移的最大收益	观测粒度更细（深层属性级）、刷新可预测、@Computed / @Monitor 让派生逻辑与副作用显式化
迁移的最大成本	双向同步从 @Link 改为"@Param + @Event"回调模型，父子交互写法要改
能否局部迁移	可以，但同一组件内不能混用（见 A.3 第 1 条）。以"组件为最小迁移单元"逐层推进

误区：把 V2 理解成"V1 换了个名字"。V2 不是命名替换，而是观测模型的替换：V1 靠装饰器类型推断观测范围（数组/对象只观测一层），V2 靠 @ObservedV2 + @Trace 显式声明观测点，观测范围由数据类决定而非由使用方的装饰器决定。

版本门槛：状态管理 V2（@ComponentV2 / @ObservedV2 / @Trace / @Local / @Param / @Monitor / @Computed）自 API 12 起可用，其余装饰器随版本补齐。在兼容下限 API 20 上无门槛，可无条件使用。

---

A.1 装饰器与 API 映射总表

能力	V1 写法	V2 写法	迁移注意点
组件内可变状态	@State value: number = 0	@Local value: number = 0	@Local 必须在组件内初始化，不可由外部传入
父传子参数	@Prop title: string	@Param title: string = ''	@Param 在子组件内只读；父级更新会同步下来
父传子（一次性）	@Prop 语义模糊	@Once @Param title: string = ''	需要"只取初值、之后本地自管"时加 @Once
参数必填约束	无对应能力	@Require @Param id: string	忘记传参在编译期报错，替代了 V1 的运行时防御
子传父 / 双向	@Link value: number	@Param value: number + @Event onValueChange: (v: number) => void	双向同步改为父持有状态、子触发事件；见 A.2.3
跨层级下传	@Provide value: number	@Provider() value: number = 0	@Provider 由后代最近的 @Consumer 消费
跨层级上取	@Consume value: number	@Consumer() value: number = 0	必须提供默认值；找不到 @Provider 时用默认值
属性变更监听	@Watch('onChange')	@Monitor('count') onCountChange(m: IMonitor) {}	@Monitor 可一次监听多个成员，并给出 before / now
可观测类	@Observed class M {}	@ObservedV2 class M {}	V2 的可观测类必须用 @ObservedV2 声明
类内可观测属性	@Track prop: string	@Trace prop: string = ''	V2 是白名单：只有 @Trace 属性参与观测，未标者改了不刷新
对象引用观测	@ObjectLink item: M	直接把 M 实例作为 @Param 传入	V2 无需 @ObjectLink，观测能力内建在 @ObservedV2 类上
组件声明	@Component struct C {}	@ComponentV2 struct C {}	V2 组件内不能出现 V1 装饰器，反之亦然
派生值（计算属性）	无（写在 get 或 build 里）	@Computed get total(): number { … }	@Computed 会缓存，依赖变化才重算，替代 build 里的即时计算
应用级存储	AppStorage.setOrCreate('k', v) / @StorageLink	AppStorageV2.connect(T, 'k', () => new T())	V2 不能存原始值，必须由类承载，见 A.3 第 5 条
持久化存储	PersistentStorage.persistProp('k', v)	PersistenceV2.connect(T, 'k', () => new T())	嵌套类属性必须标 @Type，否则静默丢失，见 A.3 第 6 条
页面级存储	LocalStorage / @LocalStorageLink	AppStorageV2 或 @ObservedV2 单例	V2 无 LocalStorage 对应物，按作用域选型
环境变量	@Environment	@Consumer + 自定义 @Provider	由应用自行注入。官方 V1→V2 迁移指导同此口径：V2 也可直接调用 Ability 接口获取环境变量

术语：观测粒度指"数据变化到第几层才触发 UI 刷新"。V1 的 @State 观测对象的引用替换与数组增删，但不观测数组元素内部属性；V2 通过 @Trace 把观测点下沉到属性级，故称"更细"。

---

A.2 三组对照：V1 与 V2 的行为差异

A.2.1 深层嵌套对象属性更新是否触发刷新

// ── V1：@Observed + @ObjectLink 只观测一层，深层属性改了不刷新 ──
@Observed
class Address {
    city: string = ''
}

@Observed
class User {
    name: string = ''
    address: Address = new Address()
}

@Component
struct UserViewV1 {
    @ObjectLink user: User

    build() {
        Column() {
            Text(this.user.name)        // 改 name 会刷新（一层）
            Text(this.user.address.city) // 改 city 不刷新（两层）
        }
    }
}

// ── V2：@Trace 逐属性声明，跨层与嵌套均刷新 ──
@ObservedV2
class AddressV2 {
    @Trace city: string = ''
}

@ObservedV2
class UserV2 {
    @Trace name: string = ''
    @Trace address: AddressV2 = new AddressV2()
}

@ComponentV2
struct UserViewV2 {
    @Param user: UserV2 = new UserV2()

    build() {
        Column() {
            Text(this.user.name)         // 刷新
            Text(this.user.address.city) // 也刷新：address 与 city 都被 @Trace
        }
    }
}

维度	V1	V2
观测深度	一层（@ObjectLink 绑定的对象属性）	按 @Trace 标记，可达任意层
深层刷新条件	每层都要 @Observed + 每层都要 @ObjectLink 中转	链路属性全部标 @Trace 即可
未标属性的行为	改了不刷新	改了不刷新（同样静默）

误区：V2 不是"自动全量观测"。@ObservedV2 类里没标 @Trace 的属性依然是不可观测的，this.user.remark = 'x' 不触发刷新且不报错。迁移时最容易漏标。

A.2.2 数组元素修改是否触发刷新

// ── V1：整体替换数组会刷新，改元素属性不会 ──
@Observed
class Task {
    title: string = ''
    done: boolean = false
}

@Component
struct TaskListV1 {
    @State tasks: Task[] = []

    private toggleV1(index: number): void {
        this.tasks[index].done = !this.tasks[index].done // 不刷新
        this.tasks = [...this.tasks]                     // 手动换引用才刷新
    }
}

// ── V2：元素属性被 @Trace，直接改即刷新，无需换引用 ──
@ObservedV2
class TaskV2 {
    @Trace title: string = ''
    @Trace done: boolean = false
}

@ComponentV2
struct TaskListV2 {
    @Local tasks: TaskV2[] = []

    private toggleV2(index: number): void {
        this.tasks[index].done = !this.tasks[index].done // 直接刷新
    }
}

操作	V1（@State 数组）	V2（@Local 数组 + @Trace 元素类）
push / splice / 赋值新数组	刷新	刷新
arr[i].prop = x	不刷新（需 @Observed + 子组件 @ObjectLink，或整体换引用）	刷新
arr[i] = newObj	刷新	刷新
迁移要点	删掉 [...this.arr] 这类"手动换引用"技巧，避免无意义重渲染	—

误区：迁移时把 this.tasks = [...this.tasks] 一并保留，以为"保险"。这在 V2 里会造成一次多余的数组引用变更，触发不必要的 diff，长列表上放大成掉帧。

A.2.3 父子组件间双向同步的写法差异

// ── V1：@Link 直接双向绑定，子组件可改父状态 ──
@Component
struct StepperV1 {
    @Link value: number

    build() {
        Row() {
            Button('-').onClick(() => { this.value-- }) // 直接改父状态
            Text(`${this.value}`)
            Button('+').onClick(() => { this.value++ })
        }
    }
}

// ── V2：父持有状态，子用 @Param 读 + @Event 通知 ──
@ComponentV2
struct StepperV2 {
    @Param value: number = 0
    @Event onValueChange: (v: number) => void = (_v: number) => {}

    build() {
        Row() {
            Button('-').onClick(() => { this.onValueChange(this.value - 1) })
            Text(`${this.value}`)
            Button('+').onClick(() => { this.onValueChange(this.value + 1) })
        }
    }
}

@ComponentV2
struct CounterHost {
    @Local count: number = 0

    build() {
        StepperV2({
            value: this.count,
            onValueChange: (v: number) => { this.count = v } // 单向数据流闭环
        })
    }
}

维度	V1 @Link	V2 @Param + @Event
数据流向	双向，子可写	单向：父 → 子传值、子 → 父传事件
子组件能否改值	能	不能（@Param 只读）
数据归属	模糊，谁都能改	明确：状态归父组件所有
调试难度	难（改值点分散）	易（唯一写入点在 @Event 回调）
迁移要点	把"子改父"的每处赋值，改成一次 onXxx 事件调用	—

---

A.3 混用禁忌清单

#	禁忌	现象	正确做法
1	同一组件内混用 V1 与 V2 装饰器	编译报错，构建直接失败	以组件为单位整体切换：@Component ↔ @ComponentV2 二选一
2	把 @ObservedV2 实例传给 V1 组件观测	经 @ObjectLink 传入时可能直接编译报错；经 @Prop / @State 传入时编译通过但观测失效，UI 不刷新	V2 数据只交给 V2 组件；跨代传参需在边界处做快照或改造接收方
3	@Local 依赖外部初始化	编译报错：@Local 必须本地初始化	外部传入的值用 @Param；本地派生用 @Local + @Computed
4	在子组件里写 this.xxx = v 改 @Param	编译报错 / 运行期不生效	通过 @Event 回调把意图交回父组件，由父改 @Local
5	往 AppStorageV2 里存原始值（number/string）	类型不匹配，编译或运行期失败	用类承载：AppStorageV2.connect(SessionStore, 'session', () => new SessionStore())
6	PersistenceV2 嵌套类属性漏标 @Type	静默丢失：反序列化后该属性为默认值，不报错	嵌套的类属性一律标 @Type，见下方示例
7	用 @Trace 标在普通 class 上	不生效（@Trace 仅在 @ObservedV2 类内有效）	类必须先声明为 @ObservedV2
8	在 @Computed 里做副作用（写日志、发请求）	重算时机不可控，副作用重复触发	@Computed 只做纯计算；副作用放 @Monitor 或生命周期

// 禁忌 6 的正反例
@ObservedV2
class DraftMeta {
    @Trace title: string = ''
}

@ObservedV2
class Draft {
    @Trace id: string = ''
    @Type(DraftMeta)              // 必须：否则 meta 反序列化后丢失
    @Trace meta: DraftMeta = new DraftMeta()
    @Trace tags: string[] = []
}

误区：以为 PersistenceV2 丢了数据会报错。它是静默的——读出来是默认值，直到用户发现"上次填的没了"。凡涉及嵌套结构，迁移后必须做一次"写入 → 杀进程 → 重启 → 读回"的验证。

---

A.4 迁移操作清单

按组件为最小单元，逐项执行：

• [ ] 把所有 @Component 改成 @ComponentV2，@Observed 改成 @ObservedV2
• [ ] 数据类里把 @Track 改成 @Trace；逐属性检查是否需要观测，避免漏标
• [ ] @State → @Local；确认每个 @Local 都在组件内初始化
• [ ] @Prop → @Param；需要"只取初值"的补 @Once，必填的补 @Require
• [ ] @Link → @Param + @Event；把子组件的写操作改写成事件回调
• [ ] @Provide / @Consume → @Provider() / @Consumer()；确认 @Consumer 有默认值
• [ ] @Watch → @Monitor；把监听多个字段的 @Watch 合并为一个 @Monitor
• [ ] build() 里的即时计算抽成 @Computed getter
• [ ] AppStorage / @StorageLink → AppStorageV2，状态由类承载
• [ ] PersistentStorage → PersistenceV2，嵌套结构补 @Type
• [ ] 删除 this.arr = [...this.arr] 这类手动换引用技巧
• [ ] 全局搜索 @ObjectLink，全部移除并改为直接传 @ObservedV2 实例
• [ ] 跑一遍"数据写入 / 杀进程 / 重启 / 读回"的持久化验证
• [ ] 全量编译一次，确认无"V1/V2 混用"报错

验收：迁移完成的标志不是"能编译"，而是长列表滚动与详情页联动处不出现多余重渲染。用第 8 章的 Profiler 抓一次帧数据对比迁移前后。

---

A.5 延伸阅读

• 本教程 第 5 章 状态管理（V2 主线写法与刷新失败排查）
• 本教程 附录 B（V1 装饰器在弃用总表中的定位）
• 本教程 附录 C（状态管理 V1/V2、观测粒度、重渲染等术语）
• 官方文档 → ArkUI → 状态管理（含 V1 → V2 迁移指导与 @Type / @Once 的完整参数说明）
• 官方文档 → API 参考 → ArkTS 装饰器（每个装饰器的可用版本与约束）

📄 第 2 章 ArkTS 语言核心 02-arkts-core.md✓ 标记已学

ArkTS 不是「随便写的 TypeScript」。它砍掉了 TS 的动态特性，换来 AOT 确定性、可静态分析的状态追踪与跨线程安全。这一章讲清砍了什么、为什么砍、被砍掉的需求该怎么在限制内表达——并把领域模型 → DTO → 解析器这条数据入口链路写完整。

---

2.0 本章目标

1. 能解释 ArkTS 作为「TS 静态化子集」的三条设计动机（AOT 确定性 / 性能 / 可静态分析），据此判断一段 TS 代码能否直接使用，并写出通过 ArkTS 静态检查的代码：显式类型字面量、无动态增删属性、无重载。
2. 能划清领域模型 / DTO / UI 状态的边界，并写出手写 fromJson 解析器，正确处理字段缺失、类型不符与默认值。
3. 能用不可变更新替代深层原地修改，并解释它与 ArkUI V2 刷新机制的因果关系。
4. 能判断一段计算该留在主线程、下沉 taskpool 还是交给 worker，并说清 Sendable 与序列化的成本差异。
5. 能定位循环导入，并把模块导出面收敛到根 Index.ets。

---

2.1 心智模型：为什么要有这门「受限的 TS」

2.1.1 三条设计动机

动机	具体机制	被砍掉的语言特性
AOT 确定性	编译期必须能确定对象布局与分派目标，才能提前生成机器码	运行期动态增删属性、with、eval、改 prototype
性能	静态分派可内联、可去虚化；线程间共享对象需固定内存布局	any / unknown、结构化类型、apply / call / bind
可静态分析	状态管理 V2 的依赖追踪要精确知道「读了哪个字段」，动态属性会让追踪失效	任意索引签名、动态键访问、声明合并

术语：静态化子集——ArkTS 的语法是 TypeScript 的子集，类型规则更严。TS 里「能编译」不等于 ArkTS 里「能编译」；反过来，ArkTS 代码基本都能被 TS 理解。

2.1.2 限制不是能力缺失，而是换建模方式

遇到限制时，正确反应不是绕过编译器，而是把「动态需求」翻译成「显式建模」：

你想要的动态能力	ArkTS 里的替代建模
任意键值对	Map<string, string> 或 Record<string, string>
一个字段可能是多种类型	判别联合（枚举判别键 + 类层次）
参数组合多	静态工厂方法 + 可选参数
运行期决定对象形状	定义若干固定形状的类，用 switch 分派

判别联合是本教程出现频率最高的替代方案，先建立印象：

// 用「枚举判别键 + 类层次」替代 TS 的联合字面量类型
export enum FieldKind {
    TEXT = 'text',
    SELECT = 'select'
}

export class FieldBase {
    readonly key: string;
    readonly kind: FieldKind;
    readonly label: string;

    constructor(key: string, kind: FieldKind, label: string) {
        this.key = key;
        this.kind = kind;
        this.label = label;
    }
}

export class TextField extends FieldBase {
    readonly maxLength: number;

    constructor(key: string, label: string, maxLength: number) {
        super(key, FieldKind.TEXT, label);
        this.maxLength = maxLength;
    }
}

export class SelectField extends FieldBase {
    readonly options: string[];

    constructor(key: string, label: string, options: string[]) {
        super(key, FieldKind.SELECT, label);
        this.options = options;
    }
}

版本差异提示：本节不涉及版本差异。ArkTS 的类型规则稳定，与 API 20 / API 26 无关——语言限制不随 SDK 版本放宽，不要期望升级 SDK 后可以写 any。

---

2.2 高频语法限制

2.2.1 限制总表

#	限制项	允许的写法	不允许的写法	为什么要限
1	对象字面量类型	const p: Point = { x: 1, y: 2 }	const p = { x: 1, y: 2 }	无类型无法在编译期确定对象布局
2	属性增删	Map 或预声明可选字段	obj.newKey = 1、delete obj.key	布局必须编译期固定，才能按偏移访问
3	结构化类型	class A implements P 显式实现	「字段一样」就直接赋值	ArkTS 用名义类型，避免隐式耦合
4	with / eval	直接写逻辑	任何形式	破坏静态分析，无法 AOT
5	any / unknown	明确类型或判别联合	任何位置出现	等于关掉类型检查与优化
6	函数 / 构造函数重载	静态工厂 + 可选参数	同名多签名	运行期按参数分派，无法静态绑定
7	参数默认值	字面量常量	f(n: number = compute())（TS 语义允许，默认值运行期求值）	非语言限制；教程约定只用字面量常量以保持可预测
8	可选参数位置	可选参数写在末尾	f(a?: number, b: number)	TS 共有规则，非 ArkTS 差异，列出仅为提醒
9	动态调用	显式参数、箭头函数	arguments、fn.apply/call/bind	this 与参数个数不可静态分析
10	原型操作	类继承	__proto__、改 prototype	布局必须固定、可预生成
11	索引签名	Record<K, V>、Map	自定义任意索引签名	保证键空间可控、可分析
12	声明合并	显式 export	同名接口 / 命名空间合并	保证「一个名字一个定义」
13	类型断言	as 到明确的类 / 接口	as any	断言必须可验证

2.2.2 字面量必须有显式类型、属性不能增删

interface Point {
    x: number;
    y: number;
}

// 错误写法：裸字面量，编译器无法确定布局
// const p = { x: 1, y: 2 };

const p: Point = { x: 1, y: 2 };          // 正确一：先有类型

function moveTo(target: Point): void { }
moveTo({ x: 3, y: 4 });                    // 正确二：由形参类型推导

export class ApprovalRow {
    readonly id: string;
    // 需要「可能不存在」的字段就显式声明为可空，而不是事后动态挂
    readonly remark: string | undefined;

    constructor(id: string, remark?: string) {
        this.id = id;
        this.remark = remark;
    }
}

// row.extraFlag = true;    // 属性未声明，无法增加
// delete row.remark;       // 禁止删除

// 真正需要动态键空间时用 Map
const tags: Map<string, string> = new Map<string, string>();
tags.set('source', 'mobile');
tags.delete('source');

注意第一种：只有目标类型明确时字面量才合法。function f(v: Object): void 后面跟 f({ a: 1 }) 依然报错，因为 Object 无法确定布局。

2.2.3 用静态工厂替代重载

ArkTS 不支持函数与构造函数的重载签名。按「参数含义是否相同」二选一：

export class Money {
    readonly cents: number;

    private constructor(cents: number) {
        this.cents = cents;
    }

    /** 入口语义不同 → 静态工厂，方法名自带说明 */
    static fromCents(cents: number): Money {
        return new Money(Math.round(cents));
    }

    static fromYuanText(text: string): Money {
        const parsed: number = parseFloat(text);
        return new Money(isNaN(parsed) ? 0 : Math.round(parsed * 100));
    }

    /** 语义相同、只有可选性不同 → 一个方法 + 可选参数 */
    add(other: Money, scale: number = 1): Money {
        return new Money(this.cents + Math.round(other.cents * scale));
    }

    yuanText(): string {
        return (this.cents / 100).toFixed(2);
    }
}

2.2.4 null 安全、可选链与空值合并

严格空检查始终开启，无法关闭。

export class Department {
    readonly name: string;

    constructor(name: string) {
        this.name = name;
    }
}

export class Employee {
    readonly name: string;
    readonly department: Department | undefined;   // 显式可空

    constructor(name: string, department?: Department) {
        this.name = name;
        this.department = department;
    }

    /** 可选链：链上任意一环为空就短路为 undefined */
    departmentName(): string | undefined {
        return this.department?.name;
    }

    /** 空值合并：只处理 null / undefined，不误伤 0 与空串 */
    departmentNameOrDefault(): string {
        return this.department?.name ?? '未分配';
    }
}

场景	写法	不要用
读可能不存在的字段	obj?.field ?? fallback	obj.field || fallback（0 / '' 会被误判）
取默认值	value ?? fallback	value ? value : fallback
可选参数后有必填参数	拆成两个方法	可选参数写在前（编译不过）
有默认值的参数	用 =，不要同时标 ?	f(a?: number = 1)

注：上表后两行（可选参数位置、默认值参数）是 TypeScript 共有规则，并非 ArkTS 差异，列出仅为提醒。

术语：空值合并 vs 逻辑或——?? 只在左侧为 null / undefined 时取右侧；|| 在左侧是任何假值（含 0、''、NaN）时都取右侧。处理金额、计数时用错会丢数据。

版本差异提示：?. / ?? 在兼容下限 API 20 上完全可用。不要用非空断言 ! 绕过空检查——它不做运行期校验，只是让编译器闭嘴，是 undefined 崩溃的常见来源。

---

2.3 三层建模：领域模型 / DTO / UI 状态

2.3.1 为什么要分三层

不分层的典型后果是「一个类既当接口契约、又当业务对象、又是渲染状态」：后端改字段名要动 UI 代码，UI 加临时字段污染了领域模型，序列化细节泄漏到展示逻辑。

层	唯一职责	允许依赖	明确禁止
DTO	与线上 JSON 字段一一对应，字段名原样保留	无	业务逻辑、格式化、UI 文案
领域模型	承载业务不变量与规则，构造成功即合法	自身与基础类型	反序列化细节、网络、UI 类型
UI 状态	可观察、驱动渲染的最小集合	领域模型	直接持有 DTO

三条边界规则贯穿全书：

1. DTO 不允许离开数据层。进入业务逻辑前必须转成领域模型——转换点唯一，改动成本可控。
2. 领域模型的构造必须能失败。失败用返回值表达（本节 ParseOutcome，2.8 的 Result），不允许产出「半成品对象」。
3. UI 状态只存渲染需要的最小集合，派生值交给 @Computed（第 3、5 章）。

网络 JSON ──解析──> DTO ──映射+校验──> 领域模型 ──投影──> UI 状态 ──> 渲染
              ↑ 2.3.3   ↑ 2.3.4       ↑ 2.8 Result   ↑ 第 5 章 V2 装饰器

2.3.2 DTO 与领域模型

// entry/src/main/ets/data/dto/ApprovalDto.ets

/** DTO：字段名与线上 JSON 完全一致，不重命名、不校验、不含任何逻辑。 */
export interface ApprovalDto {
    id: string;
    title: string;
    amount: number;
    status: string;
    created_at: number;
    tags: string[];
}

// entry/src/main/ets/domain/Approval.ets

export enum ApprovalStatus {
    DRAFT = 'draft',
    PENDING = 'pending',
    APPROVED = 'approved',
    REJECTED = 'rejected'
}

/** 领域模型：构造完成即满足全部不变量，字段不可能缺失。 */
export class Approval {
    readonly id: string;
    readonly title: string;
    readonly amountCents: number;
    readonly status: ApprovalStatus;
    readonly createdAt: Date;
    readonly tags: string[];

    constructor(id: string, title: string, amountCents: number,
                status: ApprovalStatus, createdAt: Date, tags: string[]) {
        this.id = id;
        this.title = title;
        this.amountCents = amountCents;
        this.status = status;
        this.createdAt = createdAt;
        this.tags = tags;
    }

    /** 业务规则住在领域模型里，UI 不再自己判 */
    get isActionable(): boolean {
        return this.status === ApprovalStatus.PENDING;
    }

    get amountText(): string {
        return (this.amountCents / 100).toFixed(2);
    }

    /** 不可变更新：返回新实例而不是就地改（见 2.4） */
    withStatus(next: ApprovalStatus): Approval {
        return new Approval(this.id, this.title, this.amountCents, next, this.createdAt, this.tags);
    }
}

2.3.3 手写 JSON 读取器

不直接 JSON.parse(...) as ApprovalDto 的原因：类型断言不做任何运行期校验。后端少一个字段、多一个 null，断言全部照过，问题会在离现场很远的地方炸开。手写读取器把「字段缺失 / 类型不符 / 数组元素异常」变成可收集的问题列表 + 安全默认值。

// entry/src/main/ets/core/json/JsonReader.ets

export class ParseIssue {
    readonly path: string;
    readonly detail: string;

    constructor(path: string, detail: string) {
        this.path = path;
        this.detail = detail;
    }

    toString(): string {
        return `${this.path}: ${this.detail}`;
    }
}

type JsonObject = Record<string, Object>;

/**
 * 字段缺失与类型不符都记成 ParseIssue 并返回安全默认值；
 * 只有「整体不可解析」才返回 undefined。
 * 嵌套对象复用同一套方法：用 obj(key) 拿到子 reader 后继续按字段读。
 */
export class JsonReader {
    private readonly root: JsonObject;
    private readonly issues: ParseIssue[] = [];

    private constructor(root: JsonObject) {
        this.root = root;
    }

    /** 入口：非法 JSON 或根节点非对象时返回 undefined */
    static tryOpen(text: string): JsonReader | undefined {
        let parsed: Object;
        try {
            parsed = JSON.parse(text) as Object;
        } catch (err) {
            return undefined;
        }
        if (parsed === null || parsed === undefined || typeof parsed !== 'object') {
            return undefined;
        }
        return new JsonReader(parsed as JsonObject);
    }

    /** 子对象：缺失或类型不符 → undefined，并记问题 */
    obj(key: string): JsonReader | undefined {
        const v: Object | undefined = this.root[key];
        if (v === undefined || v === null || typeof v !== 'object' || Array.isArray(v)) {
            this.issues.push(new ParseIssue(key, 'not an object'));
            return undefined;
        }
        return new JsonReader(v as JsonObject);
    }

    /** 字符串：缺失或非字符串 → fallback 并记问题 */
    str(key: string, fallback: string): string {
        const v: Object | undefined = this.root[key];
        if (typeof v === 'string') {
            return v as string;
        }
        this.issues.push(new ParseIssue(key,
            v === undefined ? 'missing, fallback used' : 'not a string, fallback used'));
        return fallback;
    }

    /** 整数（分值、时间戳用）：缺失、非数字、非整数 → fallback 并记问题 */
    int(key: string, fallback: number): number {
        const v: Object | undefined = this.root[key];
        const n: number = v as number;
        if (typeof v === 'number' && isFinite(n) && Math.floor(n) === n) {
            return n;
        }
        this.issues.push(new ParseIssue(key,
            v === undefined ? 'missing, fallback used' : 'not an integer, fallback used'));
        return fallback;
    }

    /** 字符串数组：非数组 → 空数组；非字符串元素逐个丢弃并记录下标 */
    strArray(key: string): string[] {
        const v: Object | undefined = this.root[key];
        const out: string[] = [];
        if (v === undefined || !Array.isArray(v)) {
            this.issues.push(new ParseIssue(key, 'not an array, [] used'));
            return out;
        }
        const arr: Object[] = v as Object[];
        for (let i = 0; i < arr.length; i++) {
            const item: Object = arr[i];
            if (typeof item === 'string') {
                out.push(item as string);
            } else {
                this.issues.push(new ParseIssue(`${key}[${i}]`, 'not a string, dropped'));
            }
        }
        return out;
    }

    /** 取走累积的问题（拷贝，避免调用方二次修改内部状态） */
    drain(): ParseIssue[] {
        return this.issues.slice();
    }
}

2.3.4 映射器：DTO → 领域模型

映射器是唯一允许同时认识 DTO 与领域模型的地方：把字符串状态转枚举、把分值转整数、把时间戳转 Date，并决定问题的严重级别。

// entry/src/main/ets/data/ApprovalMapper.ets
import { JsonReader, ParseIssue } from '../core/json/JsonReader';
import { Approval, ApprovalStatus } from '../domain/Approval';

/** 解析结果：永远有一个可用对象，另附非致命问题清单 */
export class ParseOutcome {
    readonly value: Approval;
    readonly issues: ParseIssue[];

    constructor(value: Approval, issues: ParseIssue[]) {
        this.value = value;
        this.issues = issues;
    }

    get clean(): boolean {
        return this.issues.length === 0;
    }
}

function toStatus(raw: string): ApprovalStatus {
    switch (raw) {
        case 'pending':
            return ApprovalStatus.PENDING;
        case 'approved':
            return ApprovalStatus.APPROVED;
        case 'rejected':
            return ApprovalStatus.REJECTED;
        default:
            return ApprovalStatus.DRAFT;   // 未知状态一律兜底为草稿，绝不抛错
    }
}

export class ApprovalMapper {
    /** undefined = 整条数据不可用；返回 ParseOutcome = 可用（可能带问题） */
    static fromJson(text: string): ParseOutcome | undefined {
        const reader: JsonReader | undefined = JsonReader.tryOpen(text);
        if (reader === undefined) {
            return undefined;
        }

        // 逐字段读取：缺失 / 类型不符都在 reader 内记问题并给出安全默认值
        const id: string = reader.str('id', '');
        const title: string = reader.str('title', '(未命名审批)');
        const amountCents: number = reader.int('amount', 0);
        const rawStatus: string = reader.str('status', 'draft');
        const createdMs: number = reader.int('created_at', 0);
        const tags: string[] = reader.strArray('tags');

        // 关键字段缺失时视为不可用，避免污染上层
        if (id.length === 0) {
            return undefined;
        }

        const approval: Approval = new Approval(
            id, title, amountCents, toStatus(rawStatus), new Date(createdMs), tags
        );
        return new ParseOutcome(approval, reader.drain());
    }

    /** 列表解析：逐条处理，坏数据被丢弃而不是让整页失败 */
    static fromJsonList(text: string): ParseOutcome[] {
        let parsed: Object;
        try {
            parsed = JSON.parse(text) as Object;
        } catch (err) {
            return [];
        }
        if (!Array.isArray(parsed)) {
            return [];
        }
        const rows: Object[] = parsed as Object[];
        const out: ParseOutcome[] = [];
        for (let i = 0; i < rows.length; i++) {
            // 教学简化：经 stringify 往返逐条复用 fromJson；生产应避免序列化往返，给 JsonReader 增加对象入口
            const one: ParseOutcome | undefined = ApprovalMapper.fromJson(JSON.stringify(rows[i]));
            if (one !== undefined) {
                out.push(one);
            }
        }
        return out;
    }
}

调用侧的模式固定为「先看有没有值、再看有没有问题」：

// 组件方法内片段，省略导入
const outcome: ParseOutcome | undefined = ApprovalMapper.fromJson(rawText);
if (outcome === undefined) {
    // 整条不可用 → 走错误态 UI（第 3 章）
} else {
    if (!outcome.clean) {
        // 非致命问题：上报埋点（第 11 章），但不打断用户
        hilog.warn(0x0000, 'Mapper', 'issues=%{public}d', outcome.issues.length);
    }
    const row: Approval = outcome.value;
}

版本差异提示：Record、Array.isArray、JSON.parse、模板字符串在兼容下限 API 20 上均可用，无需门槛标注。解析与校验在手写读取器里就能完成，不要为此引入额外 JSON 工具库。

---

2.4 不可变更新

2.4.1 先讲清观察边界

不可变更新的必要性来自观察边界。V2 的规则是：

装饰器	能观察到什么
@Local / @Param	仅变量自身的赋值（@Param 为父组件单向同步）；对象属性变化必须整链 @ObservedV2 + @Trace 才可观察，V2 没有隐式第一层观察（与 V1 @State 的关键差异，见附录 A）
@Trace	被装饰字段的变化；沿途每层都是 @ObservedV2 + @Trace 时才穿透到深层
@ObservedV2 类中被 @Trace 的 Array / Map / Set / Date	其 API 调用（push / splice / set / delete…）触发刷新

两条硬结论：

1. 未被 @Trace 装饰的属性——包括第一层——改了不会刷新——最典型的静默失败。
2. 数组用 push / splice 是合法且可观察的，不必为了刷新而刻意写不可变。

2.4.2 不可变更新的三条工程理由

理由	说明
通知范围确定	引用变化一定通知，不依赖「深层是否都被 @Trace 装饰」这一脆弱前提
支持比较与回滚	引用相等即可做脏检查、撤销栈、@Computed 缓存命中判断
消除共享可变状态	同一对象被多处持有时，隐蔽耦合被消灭

2.4.3 反面案例：深层原地修改不刷新

// 错误：Attachment 没有 @ObservedV2，size 也没有 @Trace
export class Attachment {
    size: number = 0;

    withSize(next: number): Attachment {
        const copy: Attachment = new Attachment();
        copy.size = next;
        return copy;
    }
}

@ObservedV2
export class ApprovalRow {
    readonly id: string;
    @Trace attachment: Attachment = new Attachment();
    @Trace status: ApprovalStatus = ApprovalStatus.DRAFT;

    constructor(id: string) {
        this.id = id;
    }

    // 错误示范：改成功了，但 UI 不会刷新
    // this.attachment.size = 1024;

    // 正确：整体替换引用，一定触发刷新
    withAttachmentSize(next: number): void {
        this.attachment = this.attachment.withSize(next);
    }

    withStatus(next: ApprovalStatus): void {
        this.status = next;
    }
}

attachment 的引用没变、size 又不在观察范围内，于是「数据是新的、界面是旧的」。另一条路是把整链都标成 @ObservedV2 + @Trace，但要求沿途每一层都记得加，漏一层就退化成同样的 bug——所以推荐整体替换。

2.4.4 数组的不可变工具

export class RowStore {
    /** 按 id 局部更新：找不到就原样返回（引用不变，避免无谓刷新） */
    static replaceById(rows: Approval[], id: string, next: Approval): Approval[] {
        let hit: boolean = false;
        const mapped: Approval[] = rows.map((r: Approval): Approval => {
            if (r.id === id) {
                hit = true;
                return next;
            }
            return r;
        });
        return hit ? mapped : rows;
    }

    /** 按 id 删除 */
    static removeById(rows: Approval[], id: string): Approval[] {
        const kept: Approval[] = rows.filter((r: Approval): boolean => r.id !== id);
        return kept.length === rows.length ? rows : kept;
    }

    /** 排序：先拷贝再排，绝不对入参调用 sort */
    static sortedByCreatedDesc(rows: Approval[]): Approval[] {
        const copy: Approval[] = rows.slice();
        copy.sort((a: Approval, b: Approval): number => b.createdAt.getTime() - a.createdAt.getTime());
        return copy;
    }
}

误区：直接对 @Trace 的数组调用 sort()。sort 会就地重排，虽然 V2 能观察到这次调用从而刷新，但同一个数组对象可能被多处引用，其它视图拿到的是被打乱后的顺序，问题极难定位。先 slice() 再 sort()，成本只有一次浅拷贝。

版本差异提示：@ObservedV2 / @Trace 自状态管理 V2（API 12 起）提供，在兼容下限 API 20 上完全可用，无需门槛标注。本教程全程使用 V2 装饰器，V1 迁移对照收在附录 A。

---

2.5 并发：主线程职责边界

2.5.1 边界怎么划

工作类型	归属	例子
UI 渲染	主线程	声明式 build、布局、绘制
UI 状态更新	只能主线程	给 @Local / @Trace 赋值
轻量逻辑	主线程	格式化、简单校验、状态机跳转
重计算	taskpool	大 JSON 解析、加解密、图片处理、批量统计
长生命周期独立上下文	worker	需要常驻并保留自身状态的任务

判定标准很直接：这段代码会不会阻塞主线程超过一帧（约 16 ms）？会，就下沉。

2.5.2 taskpool

// entry/src/main/ets/workers/ApprovalParseTask.ets
import { taskpool } from '@kit.ArkTS';

/**
 * @Concurrent 函数必须是顶层函数：
 * 不能是类的实例方法，也不能是捕获了外部变量的闭包。
 */
@Concurrent
function countRows(payload: string): number {
    // 纯计算：不访问 UI、不访问 Context、不做 I/O
    const rows: Object[] = JSON.parse(payload) as Object[];
    return rows.length;
}

export async function countRowsInPool(text: string): Promise<number> {
    const task: taskpool.Task = new taskpool.Task(countRows, text);
    try {
        const result: Object = await taskpool.execute(task);
        return result as number;
    } catch (err) {
        return 0;
    }
}

能力	用法	说明
单任务	new taskpool.Task(fn, args) + execute	参数建议用单个对象承载，便于后续扩展
任务组	taskpool.TaskGroup	一组任务统一等待，适合并行切片
延迟执行	taskpool.executeDelayed(delay, task)	API 18+；task 须为 GenericsTask。定时 / 防抖型计算
优先级	taskpool.execute(task, taskpool.Priority.HIGH)	影响排队顺序，不抢占正在运行的任务
取消	taskpool.cancel(task)	任务未开始才能可靠取消

2.5.3 worker

// 片段示意：宿主为组件实例，this 指向当前组件（回调在主线程执行）
import { worker } from '@kit.ArkTS';

const parseWorker: worker.ThreadWorker =
    new worker.ThreadWorker('entry/ets/workers/ParseWorker.ets');

// 回调在主线程执行，因此可以在这里安全地改 UI 状态
parseWorker.onmessage = (e: worker.MessageEvents): void => {
    this.rowCount = e.data as number;
};

parseWorker.onerror = (e: Object): void => {
    // e 是错误事件对象，字段以所用 SDK 为准；此处取 message 仅为示意
    const msg: string = (e as Error).message;
    hilog.error(0x0000, 'Worker', 'failed: %{public}s', msg);
};

parseWorker.postMessage(largePayload);
parseWorker.terminate();   // 页面退出必须终止，否则线程常驻（Code Scanner 会报泄漏）

维度	taskpool	worker
线程模型	系统管理的线程池	每个 worker 一个常驻线程
生命周期	任务结束即释放	自己 terminate，否则常驻
状态保持	无（函数式）	有（可维护内部状态）
适用	一次性并行计算	长期保活、频繁交互
数量约束	池化，可放心提交多个	数量有限，不要为每次任务新建 worker

2.5.4 Sendable 与序列化成本

路径	条件	成本
共享传递	对象标注 @Sendable	无序列化，线程间引用同一份内存
结构化克隆	普通可序列化对象	深拷贝，成本随体积与嵌套深度线性增长

// 共享传递：跨线程不拷贝
@Sendable
export class ParseStat {
    total: number = 0;
    dropped: number = 0;
    costMs: number = 0;
}

@Sendable 的约束决定了它什么时候不能用：@Sendable 类的成员类型必须本身可共享，不要在其中持有 UI 类型、Context 或普通类实例；「不能捕获闭包」是 @Concurrent 函数的约束——@Concurrent 函数必须是顶层函数，不能是捕获了外部变量的闭包（见 2.5.2）。

误区：把几 MB 的列表直接 postMessage 给 worker「让它处理」。结构化克隆会深拷贝整棵树，序列化耗时往往超过处理耗时本身。要么只传必要字段（如 id 列表），要么改用 @Sendable 共享对象。

2.5.5 UI 状态只能在主线程改

// 错误：在 @Concurrent 函数或 worker 文件里直接改 UI 状态
// @Concurrent
// function bad(): void { this.loading = false; }   // 线程错误 + 作用域错误

// 正确：工作线程算结果，主线程负责赋值（组件方法内片段，省略类声明与导入）
async refresh(): Promise<void> {
    this.loading = true;                                        // 主线程
    const count: number = await countRowsInPool(this.rawText);  // 工作线程
    this.rowCount = count;                                      // 回到主线程
    this.loading = false;
}

版本差异提示：taskpool、worker、@Concurrent、@Sendable 在兼容下限 API 20 上均可使用。注意 @Concurrent 与 @Sendable 必须写在 .ets 文件中，放到 .ts 文件里会编译失败。

---

2.6 模块与导入

2.6.1 @kit.* 是唯一入口

ArkTS 能力按「能力域」分组成 Kit，每个 Kit 是统一入口，一条 import 可同时取到该域多个对象。全工程只允许从 Kit 导入系统能力。

能力域	Kit	典型导入
应用模型与上下文	@kit.AbilityKit	import { UIAbility, Want, common, abilityAccessCtrl } from '@kit.AbilityKit';
ArkUI 能力	@kit.ArkUI	import { window, promptAction, mediaquery } from '@kit.ArkUI';
日志与性能	@kit.PerformanceAnalysisKit	import { hilog } from '@kit.PerformanceAnalysisKit';
数据存储	@kit.ArkData	import { preferences, relationalStore } from '@kit.ArkData';
网络	@kit.RemoteCommunicationKit	import { rcp } from '@kit.RemoteCommunicationKit';
基础服务	@kit.BasicServicesKit	import { BusinessError, deviceInfo } from '@kit.BasicServicesKit';
文件	@kit.CoreFileKit	import { fileIo } from '@kit.CoreFileKit';
并发与工具	@kit.ArkTS	import { taskpool, worker, util } from '@kit.ArkTS';
分布式	@kit.DistributedServiceKit	import { distributedDeviceManager } from '@kit.DistributedServiceKit';
媒体与图像	@kit.MediaKit / @kit.ImageKit	import { media } from '@kit.MediaKit';

SDK 抛出的错误统一按 BusinessError 处理，它携带 code 与 message：

import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

try {
    // 调用系统能力
} catch (err) {
    const be: BusinessError = err as BusinessError;
    hilog.error(0x0000, 'Net', 'failed: code=%{public}d msg=%{public}s', be.code, be.message);
}

版本差异提示：Kit 化入口自 API 12 起成为统一规范，在兼容下限 API 20 上可用。看到「按子系统拆分的分命名空间导入」就是老写法——它是判断外部资料年代的指纹之一，不要照抄进新工程。

2.6.2 导出面收敛

每个 HAR 只有根 Index.ets 是对外导出面，内部文件路径不允许被跨模块导入。

// lib_base/Index.ets —— 唯一导出面
export { Result, Success, Failure } from './src/core/Result';
export { AppError, ErrorCode } from './src/core/AppError';
export { CapabilityGate } from './src/common/CapabilityGate';
export { ParseIssue, JsonReader } from './src/core/json/JsonReader';

// 错误写法：深路径导入，等于把内部实现变成公共契约
// import { parseMoney } from 'lib_base/src/internal/moneyHelper';

// 正确写法：只从导出面取
import { AppError, ErrorCode } from 'lib_base';

术语：导出面（public surface）——一个模块对外承诺的 API 集合。收敛到一个文件的价值在于：重命名内部文件、重构内部结构时只有 Index.ets 会变，调用方不受影响。

2.6.3 循环导入的识别与消除

循环导入（A 依赖 B、B 依赖 A）在 ArkTS 里通常不报编译错误，而是表现为运行期诡异现象：

现象	说明
导入的对象是 undefined	初始化顺序被打乱，取到尚未完成初始化的绑定
instanceof 判定恒为 false	两侧拿到的是不同初始化阶段的同一个类
静态常量读到默认值	模块体执行顺序不同

# hvigor 构建时若检测到循环依赖，会在日志里给出依赖环路径
hvigorw assembleHap --no-daemon 2>&1 | grep -i "circular\|cycle"

手法	做法	适用
下沉契约	把共用的接口 / 常量 / 枚举移到 lib_base	首选，最彻底
依赖倒置	上层定义接口，下层实现，下层只依赖接口文件	业务层互相调用时
提取第三方模块	共同依赖抽成新的小模块	环较长、节点较多时
延迟引用	用回调或工厂函数代替直接导入类型	无法下沉时的兜底

依赖方向必须单向：entry → feature_* → lib_* → lib_base。出现反向依赖即为环的起点。

误区：用「合并两个模块」来消环。合并会让模块职责膨胀并破坏分层，短期消除、长期更痛。先尝试把契约下沉到 lib_base，只有契约本身确实不属于底座时才考虑其它手法。

---

2.7 编码规范与静态检查基线

项	规定	理由
缩进	4 空格	与官方示例、IDE 默认一致
引号 / 分号	单引号、语句末尾分号	统一 diff，减少无意义冲突
变量	const 优先，需要重赋值才用 let	缩小可变范围
类型标注	变量、参数、返回值显式标注	ArkTS 的静态优势依赖显式类型
any	公开签名中禁止	语言层面已全面禁止（见 2.2.1 第 5 条），此为工程纪律再强调
资源引用	一律 $r('app.string.xxx')	多语言与深色模式的前提
尺寸单位	vp / fp	px 不随密度与字体缩放

对象	命名约定	例子
类 / 接口 / 枚举	PascalCase	ApprovalMapper
方法 / 变量	camelCase	withStatus
常量	UPPER_SNAKE_CASE	STATE_KEY
页面文件	XxxPage.ets	ApprovalListPage.ets
组件文件	名词，无后缀	ApprovalCard.ets
ViewModel / 仓储 / 数据源	XxxViewModel / XxxRepository / XxxRemoteDs	ApprovalRemoteDs
布尔字段	is / has / can 前缀	isActionable

ArkTS 的原生规则集（arkts-* 系列）在编译期强制，报错无法通过配置绕过——这是好事，意味着类型与语法类问题不会流到运行期。Code Linter 负责其上的风格与质量规则：

// .codelinter.json
{
  "files": ["**/*.ets", "**/*.ts"],
  "ignore": ["**/oh_modules/**", "**/build/**", "**/.hvigor/**"],
  "rules": {
    "arkts-no-any-unknown": "error",
    "arkts-no-untyped-obj-literals": "error",
    "@typescript-eslint/no-unused-vars": "warn"
  }
}

# 本地门禁：改动目录跑一次，数量归零再提交
codelinter -c .codelinter.json .

版本差异提示：规则集随工具链版本演进，具体规则名以官方「Code Linter 规则」文档为准。不要为了让告警消失而关闭规则；要么改代码，要么在配置里写清豁免理由与负责人。

---

2.8 错误处理：Result 模型

2.8.1 为什么不让异常穿越分层

做法	问题
底层抛、顶层 catch	中间层无法在类型上表达「可能失败」，调用方只能靠文档知道要 catch
每层 catch 再重抛	上下文丢失、栈被打断、日志重复
catch 里只打日志继续执行	吞掉错误，最难排查的一类 bug

本教程统一用判别式 Success / Failure：失败是类型的一部分，编译器帮你检查有没有处理。

// lib_base/src/core/AppError.ets
export enum ErrorCode {
    UNKNOWN = 9999,
    NETWORK_OFFLINE = 1001,
    NETWORK_TIMEOUT = 1002,
    AUTH_EXPIRED = 2001,
    PERMISSION_DENIED = 2002,
    PARSE_FAILED = 9001,
    NOT_FOUND = 4004
}

export class AppError {
    readonly code: ErrorCode;
    readonly message: string;
    readonly cause: string | undefined;

    constructor(code: ErrorCode, message: string, cause?: string) {
        this.code = code;
        this.message = message;
        this.cause = cause;
    }
}

// lib_base/src/core/Result.ets
import { AppError } from './AppError';

export class Success<T> {
    readonly value: T;

    constructor(value: T) {
        this.value = value;
    }
}

export class Failure {
    readonly error: AppError;

    constructor(error: AppError) {
        this.error = error;
    }
}

/** 失败分支不带类型参数：失败没有值，这能省掉大量无意义的类型噪音 */
export type Result<T> = Success<T> | Failure;

2.8.2 失败在哪一层产生、哪一层消费

层	对错误的态度	手段
系统边界（网络 / 文件 / SDK）	必须捕获	try/catch → BusinessError → AppError → Failure
解析层（2.3）	不抛错	收集问题 + 安全默认值，整体不可用才返回 undefined
领域层	用 Failure 表达业务规则失败	只返回 Result，不抛异常
UI 层	只消费，不判定	拿到 Failure 展示文案，不做 code 分支（除 401）

分工要分清：ParseOutcome 处理「数据不完整但仍可用」，Result<T> 处理「要么成功要么失败」。 字段缺一个用默认值就够了，不要升级成 Failure；网络断了则必然是 Failure。

// 数据层：把系统异常立即转成 Result，异常不再向上传播
import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AppError, ErrorCode, Result, Success, Failure } from 'lib_base';

export async function fetchApprovalText(id: string): Promise<Result<string>> {
    try {
        const response: rcp.Response = await rcp.get(`https://api.example.com/approvals/${id}`);
        if (response.statusCode !== 200) {
            return new Failure(new AppError(ErrorCode.UNKNOWN, `HTTP ${response.statusCode}`));
        }
        return new Success(response.toString());
    } catch (err) {
        const be: BusinessError = err as BusinessError;
        return new Failure(new AppError(ErrorCode.NETWORK_OFFLINE, '网络不可用', `code=${be.code}`));
    }
}

// UI 层：用 instanceof 做类型收窄，失败分支由编译器强制处理（组件方法内，省略导入）
const result: Result<string> = await fetchApprovalText(id);
if (result instanceof Failure) {
    this.banner = result.error.message;      // 自动收窄到 Failure
    return;
}
const outcome: ParseOutcome | undefined = ApprovalMapper.fromJson(result.value);
if (outcome === undefined) {
    this.banner = getContext().resourceManager.getStringSync($r('app.string.parse_failed'));
    return;
}
this.detail = outcome.value;

误区：用 $r('app.string.parse_failed').toString() 取文案。$r() 返回的是资源对象，toString() 拿到的不是文案本身；取解析后的字符串要用 getContext().resourceManager.getStringSync($r(...))。

版本差异提示：Result / Success / Failure / AppError 是本教程在 lib_base 中的自定义类型，不随 SDK 版本变化。不要把它们与 SDK 的 BusinessError 混用：BusinessError 只允许出现在系统边界，一旦越过边界就必须转成 AppError。

---

2.9 常见误区

误区 1：对象字面量省略显式类型

错误写法

const config = { retry: 3, timeout: 5000 };

正确写法

interface RetryConfig {
    retry: number;
    timeout: number;
}
const config: RetryConfig = { retry: 3, timeout: 5000 };

为什么错：ArkTS 无法为无类型字面量确定对象布局，编译期直接报错。这不是风格偏好，而是 AOT 的前提。只有目标类型明确时字面量才合法，所以正确做法是先声明接口或让形参类型提供目标类型。

误区 2：用动态属性代替显式字段

错误写法

const row = new ApprovalRow('a1');
row[`extra_${index}`] = value;      // 运行期造键
delete row.remark;

正确写法

const bag: Map<string, string> = new Map<string, string>();
bag.set(`extra_${index}`, value);
bag.delete('remark');

为什么错：对象布局必须编译期固定才能按偏移访问。需要真正动态的键空间时，用 Map 表达「这是一个键值集合」这一事实，而不是让本应固定的对象长出随机字段。

误区 3：用重载表达不同入口

错误写法

class Money {
    constructor(cents: number);
    constructor(yuan: string);
    constructor(arg: number | string) { /* ... */ }
}

正确写法

class Money {
    readonly cents: number;
    private constructor(cents: number) { this.cents = cents; }
    static fromCents(cents: number): Money { return new Money(cents); }
    static fromYuanText(text: string): Money { return new Money(Math.round(parseFloat(text) * 100)); }
}

为什么错：ArkTS 不支持重载签名，运行期按参数分派无法静态绑定。静态工厂还有额外好处：方法名自带语义，Money.fromYuanText('12.5') 比 new Money(12.5) 难错得多。

误区 4：公开签名里写 any 图省事

错误写法

export function handle(payload: any): any {
    return payload.data;
}

正确写法

export interface PromptPayload {
    data: string;
    requestId: string;
}
export function handle(payload: PromptPayload): string {
    return payload.data;
}

为什么错：any 等于关掉类型检查，同时关闭了内联与去虚化等优化机会。如果一段数据「结构未知」，正确做法是先用 JsonReader（2.3.3）把它变成有类型的值，再进入业务代码。

误区 5：依赖「结构相同即可赋值」

错误写法

class PointA { x: number = 0; y: number = 0; }
class PointB { x: number = 0; y: number = 0; }
const a: PointA = new PointB();     // 期望靠字段一致混过去

正确写法

interface HasPosition { x: number; y: number; }
class PointB implements HasPosition { x: number = 0; y: number = 0; }
const a: HasPosition = new PointB();     // 显式实现接口

为什么错：ArkTS 使用名义类型，两个字段相同的类依然互不相容。这看起来更麻烦，实际是把隐式耦合变成显式契约——重命名字段时会立刻编译失败，而不是在运行期悄悄错位。

误区 6：跨模块深路径导入

错误写法

import { parseMoney } from 'lib_base/src/internal/moneyHelper';

正确写法

// 先在 lib_base/Index.ets 中导出，再从模块名导入
import { AppError, ErrorCode } from 'lib_base';

为什么错：深路径导入把内部实现变成了公共契约，内部重构会连锁破坏所有调用方；它还极易造成循环导入——模块内部文件被外部直接引用后，依赖图不再是单向的。

误区 7：把大对象直接丢给工作线程

错误写法

parseWorker.postMessage(this.allRows);      // 几 MB 的数组

正确写法

// 只传必要数据；需要共享大对象时用 @Sendable
parseWorker.postMessage(idsForSync);

为什么错：跨线程序列化是深拷贝，几 MB 的结构在传输上耗掉的时间常超过处理本身。更糟的是这个开销不在业务代码里，性能分析时极易被误判成「渲染慢」。要么只传必要字段，要么用 @Sendable 共享内存。

---

2.10 实践任务

任务：搭出类型安全的领域模型与数据入口

任务描述

1. 新建 HAR 模块 lib_base，根 Index.ets 导出 Result / Success / Failure / AppError / ErrorCode / ParseIssue / JsonReader，内部实现文件一律不导出。
2. 实现 Approval 领域模型（含 ApprovalStatus、amountText / isActionable / withStatus），构造函数完成后不存在「字段缺失」状态。
3. 实现 JsonReader 与 ApprovalMapper.fromJson / fromJsonList，处理四类输入：正常数据、字段缺失、类型不符（amount 是字符串）、tags 内含非字符串元素。
4. 用不可变更新方法（replaceById / removeById / sortedByCreatedDesc）实现列表操作，禁止对入参调用 sort。
5. 写一个 taskpool 任务，把「大批量 JSON 计数」下沉到工作线程，主线程只负责赋值。
6. 配置 .codelinter.json 并跑全量检查，告警数降到 0 或逐条写明豁免理由。

验收 checklist

• [ ] lib_base/Index.ets 是唯一导出面，全工程无深路径导入
• [ ] 全工程搜索 any / unknown，公开签名中为 0 处
• [ ] 全工程搜索 delete 与「给未声明字段赋值」，为 0 处
• [ ] ApprovalMapper.fromJson 对四类输入均有确定行为，且不抛异常
• [ ] 类型不符与字段缺失都会产生 ParseIssue，且 value 仍可用
• [ ] 非法 JSON 时 fromJson 返回 undefined（而不是抛错或返回半成品）
• [ ] RowStore.sortedByCreatedDesc 调用后原数组顺序不变
• [ ] @Concurrent 函数为顶层函数，且所在文件为 .ets
• [ ] 给 UI 状态赋值的代码全部位于主线程侧
• [ ] codelinter -c .codelinter.json . 无 error 级告警

交付物清单

交付物	形式	验收点
lib_base HAR	模块目录	Index.ets 导出面完整，含 Result / AppError
领域模型三件套	源码	Approval / ApprovalStatus / 金额字段
JsonReader.ets + ApprovalMapper.ets	源码	四类异常输入有确定行为
边界用例集	测试代码或用例表	每类输入一条，含期望输出
.codelinter.json	配置	检查可复现执行
检查结果记录	Markdown	告警数 + 每条豁免的理由与负责人

---

2.11 延伸阅读

• 官方文档 → 应用开发 → ArkTS 语言 → 从 TypeScript 到 ArkTS 的适配规则（逐条限制的权威说明）
• 官方文档 → 应用开发 → ArkTS 语言 → ArkTS 语法约束（禁止项总览，遇到编译报错先查这里）
• 官方文档 → 应用开发 → ArkTS 语言 → 并发编程（taskpool / worker / Sendable）
• 官方文档 → 应用开发 → ArkTS 语言 → 模块化与 Kit 化导入说明（各能力域与 Kit 的对应关系）
• 官方文档 → 应用开发 → ArkUI → 状态管理 V2（@ObservedV2 / @Trace 的观察边界）
• 官方文档 → 工具 → Code Linter 静态检查（规则集与配置文件格式）

---

上一章：第 1 章 环境搭建与工具链　|　下一章：第 3 章 ArkUI 组件与布局

📄 第 11 章 网络层与统一错误处理 02-network-result-error.md✓ 标记已学

术语：适配点（adaptation point）—— 一处刻意收窄的边界，把所有易变的第三方 API 调用关在同一个文件里，让外部只面对稳定的自有契约。

前置：本章默认你已经读过 docs/06-persistence-network.md 的 6.3~6.6 节，那里讲清了 rcp 的基础用法、拦截器的概念模型、Result / AppError 的设计动机。本篇不再重复概念，只做一件事：把这套模型在真实工程里的落地逐行对上。

版本门槛：网络能力基于 HarmonyOS 6.0.0(20) 起可用的 @kit.RemoteCommunicationKit。本工程开发套件基线为 26.0.0，compatibleSdkVersion 下限 6.0.0(20)。

---

2.0 本章目标

读完本篇，你应当能回答：

1. 为什么整个工程里 @kit.RemoteCommunicationKit 只出现在一个文件里，以及要换网络库时该改哪几个方法；
2. 为什么 Session 必须全局单例，而鉴权头绝对不能写进 SessionConfiguration.headers；
3. Auth → Logging → Mock → ErrorMap → Retry 这条链为什么是这个顺序，Mock 为什么必须夹在正中间；
4. 重试的三条原则在代码里分别由哪一行保证，抖动（jitter）解决的是什么问题；
5. Result<T> / AppError 的每个字段是谁在写、谁在读；
6. 401 为什么要"单飞刷新"，pending 的清理时机为什么不能用 finally；
7. 幂等键为什么必须"在用户点击提交时生成一次"，以及"改了内容"为什么反而要重置它；
8. 响应字段缺失为什么不算错误，但必须上报。

---

2.1 目录结构与唯一适配点

2.1.1 真实目录树

lib_network/src/main/ets/
├── model/
│   └── HttpTypes.ets          # 对外数据契约：RequestOptions / NetResponse /
│                              #   CancelToken / RetryPolicy / ApiEnvelope / BizCode / NetErrors
├── api/
│   └── HttpApi.ets            # 门面：解包 data 段 + 调用具名 parser + IdempotencyKeys
├── rcp/
│   ├── RcpClient.ets          # ★ 唯一适配点（RcpTransport）+ 执行循环（RcpClient）
│   ├── NetInterceptor.ets     # NetContext / RetryPlan / LoggingSession / 基类 / InterceptorChain
│   └── interceptors/
│       ├── AuthInterceptor.ets        # + AuthTokenProvider / AuthTokenRegistry
│       ├── LoggingInterceptor.ets     # + LoggingInterceptorSession
│       ├── MockInterceptor.ets
│       ├── ErrorMapInterceptor.ets    # + HttpStatusMapper / BizCodeMapper
│       └── RetryInterceptor.ets
└── mock/
    └── MockRegistry.ets       # 规则注册表 + MockBody 构造器

对照 lib_network/Index.ets：业务模块只应从这里 import，内部实现虽然导出，但注释明确写了"应视为可替换实现，而不是稳定契约"。这条纪律是后面所有"改一处"讨论的前提。

2.1.2 为什么 rcp 只能出现在一个类里

lib_network/src/main/ets/rcp/RcpClient.ets:12-22 的文件头注释就是答案：

本文件中的 RcpTransport 是整个工程唯一直接调用 rcp API 的地方。这样设计的原因很实际：rcp 的接口在不同 SDK 版本间有过微调，如果把它散落在业务与各拦截器里，一次 SDK 升级就要改十几处。

可以用一条命令验证这个约束确实成立：

cd code/office-flow
grep -rl "@kit.RemoteCommunicationKit" --include=*.ets .
# 期望输出只有一行：lib_network/src/main/ets/rcp/RcpClient.ets

这是"约束靠检查而不是靠自觉"的一个正面例子。如果没有这条 grep，RcpTransport 会在半年内被后来者绕开——因为直接 rcp.createSession() 看起来总是"更快一点"。

2.1.3 RcpTransport 的五个方法

方法	真实签名	职责
ensureSession	private ensureSession(): rcp.Session	懒创建进程级 Session；只配置进程级不变的策略
send	async send(ctx: NetContext): Promise<NetResponse>	发一次请求，把 rcp 的响应规整成 NetResponse。不做重试、不做错误映射
toAppError	toAppError(e: Error, ctx: NetContext): AppError	把 rcp 抛出的原生异常归一化为 AppError
close	close(): void	进程退出前释放 Session
headersOf / bodyTextOf	private static	把 rcp 的响应头 / 响应体结构规整成稳定的 Record<string, string> / string

headersOf 与 bodyTextOf 是 private static，因为它们纯粹是"把 SDK 的形状差异吃掉"，不暴露给上层。bodyTextOf 里那段 typeof body === 'string' 的分支，就是为不同版本 rcp 取值方式略有差异准备的。

对表记录（已修复）：本篇早期版本曾记录 RcpClient.ets:20 的注释写作"只需要改 RcpTransport 的 3 个方法（createSession / send / mapError）"，与实际方法名不一致。现已改为 ensureSession / send / toAppError，与类中实际签名一致。

2.1.4 要换网络库时改哪里

因为 RequestOptions（model/HttpTypes.ets:169）刻意不暴露任何 rcp 类型，替换网络库的改动面被限制在 RcpClient.ets 一个文件：

1. 重写 RcpTransport 的 ensureSession / send / toAppError / close；
2. 保持 send 的入参 NetContext 与出参 NetResponse 不变；
3. 保持 toAppError 的三层判断顺序（取消 → 超时 → 其他）不变。

HttpApi、五个拦截器、所有 feature 的数据源与仓储一行都不用改。这就是收敛适配点的全部收益。

---

2.2 Session 生命周期

2.2.1 为什么必须全局单例

RcpClient.get(baseUrl) 是进程级单例（RcpClient.ets:161），内部持有一个 RcpTransport，RcpTransport 持有一个 rcp.Session。

Session 的价值在于连接池与 TLS 会话复用。如果每个页面各建一个 Session：

• 每个 Session 一份连接池，连接数随页面数线性增长；
• HTTPS 的 TLS 握手（含证书校验）会被重复执行，冷启动首个请求的耗时会成倍增加；
• 超时、重定向等策略会在多处配置，autoRedirect 在 A 处是 true、B 处忘了设，表现为"某些接口不跟随跳转"。

因此：Session 是进程级资源，不是请求级资源。它随进程创建、随进程退出释放，绝不随页面创建销毁。

// RcpClient.ets:161-166
static get(baseUrl: string): RcpClient {
    if (RcpClient.instance === undefined) {
        RcpClient.instance = new RcpClient(baseUrl);
    }
    return RcpClient.instance;
}

RcpClient.reset() 存在，但只有一个用途：测试（更换 baseUrl 或清空拦截器状态）。业务代码不应调用它。

2.2.2 绝不能把 token 写进 SessionConfiguration.headers

这是 rcp 最容易被踩、后果最严重的一个坑。RcpClient.ets:30-39 的注释写得很直接：

不要在这里配置任何"会变化"的头（token、用户标识、租户）。Session 复用会把 SessionConfiguration 的头固化下来，令牌刷新后旧值仍会被发送。所有变化参数一律走每次请求的 Request。

故障表现是这样的：

1. 用户登录，token = T1；
2. 你把它写进 SessionConfiguration.headers['Authorization']，Session 创建完成；
3. 半小时后 token 过期，单飞刷新拿到 T2，TokenStore 已更新；
4. 下一个请求复用同一个 Session —— 发出的仍然是 Authorization: Bearer T1；
5. 服务端返回 401 → 触发刷新 → 拿到 T3 → 再发仍是 T1 → 无限 401 循环，最终被判为"刷新失败"而登出。

排查时最迷惑的地方是：TokenStore 里明明是 T2，日志里却没打出 T2。因为你打印的是存储值，而网络上跑的是 Session 里被固化住的那个旧值。

正确的做法：Session 配置里只放进程级不变的策略。

// RcpClient.ets:40-57
private ensureSession(): rcp.Session {
    if (this.session === undefined) {
        this.session = rcp.createSession({
            baseAddress: this.baseUrl,
            requestConfiguration: {
                transfer: {
                    autoRedirect: true,
                    timeout: {
                        connectMs: 10000,   // 连接超时：进程级不变
                        transferMs: 15000   // 传输超时：进程级不变
                    }
                }
            }
        });
        XLogger.i(this.tag, () => `session created, baseUrl=${this.baseUrl}`);
    }
    return this.session;
}

baseAddress 也是进程级不变的——换环境靠切换 EnvConfig.CURRENT 后重启，而不是运行时改 Session。

2.2.3 正确做法：每次请求从零构造 headers

AuthInterceptor.before 注入 Authorization，但注入了不代表发得出去。真正保证"这次发的是这次的 token"的，是 RcpClient.buildHeaders 每次从零构造一个对象：

// RcpClient.ets:306-328
/**
 * 每次请求都构造新的 headers 对象。
 * 这是"可变头必须走 Request 而不是 Session 配置"的落地方式：
 * 从零构造，杜绝上个请求的残留头被带过来。
 */
private static buildHeaders(options: RequestOptions): Record<string, string> {
    const headers: Record<string, string> = {
        'Content-Type': 'application/json; charset=utf-8',
        'Accept': 'application/json'
    };
    // 幂等键：非幂等写操作由客户端生成，服务端据此去重
    if (options.idempotencyKey !== undefined && options.idempotencyKey.length > 0) {
        headers['Idempotency-Key'] = options.idempotencyKey;
    }
    const custom: Record<string, string> | undefined = options.headers;
    if (custom !== undefined) {
        const keys: string[] = Object.keys(custom);
        for (let i = 0; i < keys.length; i++) {
            headers[keys[i]] = custom[keys[i]];
        }
    }
    return headers;
}

三个细节值得单独指出：

1. 从零构造，而不是"复制一份默认头再改"。复制会留下"上一轮的键"这种隐蔽残留。
2. Idempotency-Key 在这里落地，而不是在 AuthInterceptor 里——因为它是 RequestOptions 的一等字段，属于请求契约，不属于鉴权。
3. options.headers 最后合并，让业务传入的同名头可以覆盖默认值（例如某接口需要 Content-Type: text/plain）。

误区：以为"我在 AuthInterceptor 里 ctx.headers['Authorization'] = ... 就够了"。够，但前提是 ctx.headers 是全新的。一旦有人图省事把 NetContext 的 headers 改成一个模块级常量对象，这条链立刻退化成 2.2.2 描述的故障。

2.2.4 关闭时机

RcpTransport.close 的注释写明「Session 是进程级的，不在每次请求后关闭」。调用链是：

app 退出 / 测试清理 → RcpClient.close() → RcpTransport.close() → session.close()

业务代码不需要关心关闭。唯一会碰到它的是 RcpClient.reset()（测试用）。

---

2.3 拦截器链

2.3.1 三个挂载点与统一返回约定

NetInterceptor.ets:109-123 定义了基类：

export abstract class NetInterceptor {
    abstract readonly name: string;

    before(ctx: NetContext): Promise<AppError | undefined> { return Promise.resolve(undefined); }
    after(ctx: NetContext): Promise<AppError | undefined> { return Promise.resolve(undefined); }
    onError(ctx: NetContext, error: AppError): AppError { return error; }
}

挂载点	时机	返回值语义
before	请求发出前	undefined = 继续；AppError = 短路，不发请求
after	拿到响应后（含 Mock 响应）	undefined = 继续；AppError = 短路进入错误处理
onError	发生错误时	必须返回 AppError（可以是原对象），链上每一环都可替换它

三个设计决策：

1. 用返回值而不是抛异常。注释写明：让控制流在 ArkTS 下保持可静态分析，也避免"异常穿越拦截器链"带来的语义歧义。ArkTS 的类型收窄对 try/catch 的支持不如对返回值判别友好。
2. onError 不短路，而是链式替换。InterceptorChain.runOnError 的注释：采用"链式替换"而非"首个生效"，让错误能层层补充上下文（如先归一化为 HTTP_5XX，再由 Retry 环节追加"已重试 2 次"）。这一点在 2.3.7 的"已达上限"分支里被真实用到。
3. LoggingSession 接口定义在 NetInterceptor.ets 而不是 LoggingInterceptor.ets。注释说明：避免两个文件互相 import 形成类型环——方向始终是拦截器 → 上下文。这是一个小但真实的工程决策：ArkTS 的循环 import 在某些场景下会静默产生 undefined。

对表记录（已修复）：本篇早期版本曾记录 NetInterceptor.ets:2 有一行自引用导入（import { NetContext, RetryPlan, NetInterceptor } from '../NetInterceptor';，三个符号全部定义在本文件内）。该行现已删除，文件头只保留对 lib_base 与 ../model/HttpTypes 的合法导入。

2.3.2 链上顺序与理由

注册顺序（RcpClient.ets:151-156）：

this.chain = new InterceptorChain()
    .add(new AuthInterceptor())
    .add(new LoggingInterceptor())
    .add(new MockInterceptor())
    .add(new ErrorMapInterceptor())
    .add(new RetryInterceptor());

InterceptorChain 的注释（NetInterceptor.ets:125-137）给出了逐条理由：

序	环节	为什么在这个位置
1	Auth	后续所有环节都应在"已带鉴权头"的前提下工作
2	Logging	能记录到最终发出的头（含鉴权、已脱敏），且能覆盖 Mock 命中的请求
3	Mock	命中即短路不走真实网络，但依旧被 Logging 记录
4	ErrorMap	把 HTTP 状态码与业务码统一成 AppError
5	Retry	只有拿到归一化错误后才能判断"是否值得重试"

一句话记法：先给身份 → 再留证据 → 再决定真假 → 再翻译错误 → 最后决定要不要再来一次。

注册顺序不等于执行顺序。三个挂载点的执行语义（NetInterceptor.ets:146-191）：

• before 按注册正序执行（Auth 最先注入头，Logging 第二个记录）；
• after 按注册逆序执行（洋葱模型，runAfter 从链尾往回走）：ErrorMap 先把状态码/业务码归一成 AppError，Logging 最后收尾。因此 Logging.after 只会在"确认成功"时执行 finish(true)；失败请求在 ErrorMap 处被短路，改由 onError 阶段的 finish(false, code) 记账——失败请求不会被埋点记成成功（若 after 按正序执行，Logging 会在 ErrorMap 之前 finish(true)，而 finish 的幂等标志会吃掉 onError 里的失败记账）；
• onError 按注册正序、链式全员执行，每环都可替换错误对象，不短路。

2.3.3 AuthInterceptor：注入 + 401 判定

before 做四件事（AuthInterceptor.ets:79-121）：

1. 注入公共头：X-Trace-Id / X-Client / X-Client-Version / X-Platform。注释说明用途是"便于服务端做灰度与问题定位"。X-Client-Version 由 setClientVersion 在启动时注入，避免在 lib_network 里读 UI 层信息。
2. needAuth === false 时提前 return，公开接口（登录、刷新）到此为止。
3. 预刷新：仅当 provider.shouldRefresh() && ctx.options.idempotent === true 时先刷一次。为什么只对幂等请求做？因为预刷新会引入一次额外往返；对非幂等请求（提交），它与"401 后刷新再重放"的收益相同但风险更高（重放语义更敏感），所以索性只让 401 分支处理。
4. 取 token，为空则直接返回 401 错误（userMessage: '登录已过期，请重新登录'），并打上 Authorization: Bearer ${token}。

onError 是 401 单飞刷新的触发点，细节见 2.7。

AuthInterceptor 没有 after，用基类的 no-op——鉴权不需要处理"响应回来后"的任何事。

2.3.4 LoggingInterceptor：三种产出，两条纪律

三种产出（LoggingInterceptor.ets:8-11）：

1. 请求/响应摘要日志（排障）；
2. 耗时打点 Trace.count('net:duration', elapsed)（性能分析）；
3. 网络埋点 Analytics.network(tag, elapsed, success, errorCode)（服务端观测成功率与耗时分布）。

两条纪律：

• 请求体默认不打印。BODY_LOG_WHITELIST 当前是空数组，也就是全工程默认一个 body 都不打。要打必须显式把路径加进白名单，且只打白名单内的接口。
• 响应体只打长度与前 200 字符（BODY_PREVIEW_LIMIT = 200），且先过 Masker.text。

LoggingInterceptorSession 的存在理由很值得抄：注释说"把'开始 → 结束'的状态收在一个对象里，避免拦截器持有可变静态字段（并发请求下会被互相覆盖，这是很隐蔽的 bug 来源）"。finish() 里还有 finished 幂等标志，保证重复调用不会重复埋点。配合 2.3.2 说的 after 逆序执行：Logging.after 只在"确认成功"（ErrorMap 未报错）时才 finish(true)，失败请求走 onError 的 finish(false, code)——两处只会有其一生效，埋点的 success 字段因此可信。

onError 里第一件事是判断 error.isCancellation——取消不打错误日志。注释：否则用户每次返回上一页都会刷一条红色日志。

2.3.5 MockInterceptor：为什么必须夹在正中间

MockInterceptor.ets:7-20 的注释把这个位置讲透了：

• 在 Logging 之后 → Mock 命中也会输出完整日志与耗时埋点，测试时看到的链路与真实请求一致，不会因为"换成了假数据"而丢失可观测性。
• 在 ErrorMap 之前 → Mock 返回的假错误（401/500/业务码）照样会被归一化，因此错误处理分支可以被真实地演练。

第二条是这条链最有价值的设计：Mock 不是"绕过系统的后门"，而是"注入到系统中间的一段可编程响应"。你可以用 MockRegistry.setFailureRate(0.3) 让 30% 的请求返回 503，从而在真机上验证重试、慢请求告警、降级返回缓存这些分支——这些分支用真实后端极难稳定复现。

实现方式（MockInterceptor.ets:17-19）：命中后不直接返回成功，而是把响应写进 ctx.mockedResponse，由 RcpClient 跳过真实网络、直接进入 after 阶段。这样"响应处理"这条路径只有一份实现。

// MockInterceptor.ets:68-75
const netResponse: NetResponse = new NetResponse(
    mockResponse.statusCode,
    { 'content-type': 'application/json' },
    mockResponse.body
);
ctx.mocked = true;
ctx.mockedResponse = netResponse;
ctx.response = netResponse;

注意 ctx.mocked = true 这个标记：它让 LoggingInterceptorSession.finish 在日志末尾打上 | MOCKED，让你在几百行日志里一眼分辨"这次是真请求还是假数据"。

还有一个细节：Mock 会在 before 阶段 await sleep(delay)（MockInterceptor.ets:63-66）。这是刻意的——让 Mock 也消耗真实的时间，从而让骨架屏、加载态、慢请求告警的表现在 Mock 模式下与真实一致。

2.3.6 ErrorMapInterceptor：三层归一化的第 1、3 层

after 的逻辑（ErrorMapInterceptor.ets:138-159）：

async after(ctx: NetContext): Promise<AppError | undefined> {
    const response: NetResponse | undefined = ctx.response;
    if (response === undefined) { return undefined; }
    // 第一层：HTTP 状态码
    if (!response.isHttpSuccess) {
        return HttpStatusMapper.toError(response, ctx.tag);
    }
    // 第三层：业务码（HTTP 200 但 code != 0）
    const envelope: ApiEnvelope | undefined = ErrorMapInterceptor.tryEnvelope(response.rawBody, ctx.tag);
    if (envelope === undefined) {
        // 响应体不是统一包装格式：不视为错误，交给上层 parser 处理
        return undefined;
    }
    if (envelope.traceId.length > 0) {
        response.traceId = envelope.traceId;   // 回填 traceId
    }
    return BizCodeMapper.toError(envelope, ctx.tag);
}

tryEnvelope 采用"宽松解析"（ErrorMapInterceptor.ets:161-187）：只要文本能解析为对象、且含数字型 code 字段，就认为是包装格式。注释说明不用严格校验是为了兼容"部分接口直接返回数组"的历史情况。

BizCodeMapper 的映射表：

业务码	BizCode 常量	归一化后的 ErrorCode	用户文案	retryable
40100	TOKEN_EXPIRED	BIZ_TOKEN_EXPIRED	登录已过期，请重新登录	false
40300	NO_PERMISSION	BIZ_NO_PERMISSION	你没有执行该操作的权限	false
40901	DUPLICATE_SUBMIT	BIZ_CONFLICT	该单据已提交，请勿重复操作	false
50000	SERVER_ERROR	HTTP_SERVER_ERROR	服务暂时不可用，请稍后重试	true
其他	—	BIZ_FAILED	优先用服务端 message	false

40901 这条映射是幂等键设计的另一半：服务端识别出"这是同一业务动作的重复请求"，返回 40901，客户端把它变成"该单据已提交，请勿重复操作"。用户看到的是一条明确提示，而不是"提交失败"这种含糊文案——因为对用户来说，"已经提交过了"和"提交失败"是完全不同的两件事。

2.3.7 RetryInterceptor：只做判定，不做重发

注释（RetryInterceptor.ets:17-19）说明了实现方式：本拦截器不做真正的重发，而是给 ctx 打上 retryPlan 标记，由 RcpClient 的执行循环读取该标记后决定是否再跑一轮。理由是避免拦截器内部递归调用 Session 带来栈与取消语义混乱。详见 2.4.3。

还有一个容易漏掉的细节：达到 maxAttempts 上限时，必须显式清空 ctx.retryPlan（RetryInterceptor.ets:43-48）。onError 链是"链式替换、全员过一遍"，在本环节之前 Auth 可能已经为 401 写入了 needRetry=true 的刷新计划——如果这里只给错误追加"(retried N times, giving up)"的 message 而不清计划，执行循环会看到 needRetry=true 继续重放，与本环节"已达上限"的判定互相矛盾，次数上限对 401 刷新路径形同虚设。

2.3.8 一个请求的完整时序

HttpApi.get / post / ...                     ← 合并默认值（idempotent / needAuth / tag）
  └─ RcpClient.execute(options)
       ├─ traceId = nextTraceId();  attempt = 1
       ├─ refreshedOnce = false          ← 循环级状态：本次请求是否已"刷新并重放"过一次
       └─ while (true)
            ├─ ① 取消检查（cancelToken.cancelled → 直接 Failure）
            ├─ ② 构造 NetContext（url / headers / body 全部从零构造）
            │     若 refreshedOnce → 把 AuthInterceptor.MARK_REFRESHED 继承进新 ctx.marks
            │     （ctx 每轮重建，不继承的话 AuthInterceptor 的"已刷仍 401"闸门永不触发）
            ├─ ③ runBefore(ctx)（按注册正序）
            │     Auth.before      → 公共头 + （必要时预刷新）+ Authorization
            │     Logging.before   → session.begin()：打请求日志 + Trace.count
            │     Mock.before      → 命中则写 ctx.mockedResponse（含延迟）
            │     ErrorMap.before  → no-op
            │     Retry.before     → no-op
            ├─ ④ if (无错 且 无 Mock 响应) → transport.send(ctx)
            │     catch → transport.toAppError(e, ctx)   ← 取消 / 超时 / 不可达
            ├─ ⑤ if (无错) runAfter(ctx)（按注册逆序 = 洋葱）
            │     Retry.after      → no-op
            │     ErrorMap.after   → HTTP 状态 / 业务码 → AppError（短路点）
            │     Mock.after       → no-op
            │     Logging.after    → session.finish(true)：只有"确认成功"才走到这里
            │     Auth.after       → no-op
            ├─ ⑥ if (无错 且 有响应) → return Success<NetResponse>
            ├─ ⑦ runOnError(ctx, error)   ← 链式替换，不短路（按注册正序）
            │     Auth.onError     → 401 → retryPlan{needRetry, requireRefresh}；
            │                        已带 MARK_REFRESHED → 直接 onUnauthorized 强制登出
            │     Logging.onError  → session.finish(false, code) + FAIL 日志
            │     Mock.onError     → 原样返回
            │     ErrorMap.onError → 原样返回
            │     Retry.onError    → 三条原则判定；已达上限 → 清空 retryPlan 后放弃
            ├─ ⑧ if (retryPlan 为空 / needRetry=false / 已取消) → return Failure
            ├─ ⑨ if (requireRefresh) → 单飞刷新后重放
            │     refreshedOnce 已为 true → 双保险闸门：onUnauthorized → return Failure
            │     provider.refreshToken() 失败 → provider.onUnauthorized(...) → return Failure
            │     成功 → refreshedOnce = true（一次请求最多刷新重放一次）
            ├─ ⑩ sleep(plan.delayMs)
            └─ ⑪ attempt++  ── 回到 ①
  └─ DefaultHttpApi.unwrap(response, options, parser)
       ├─ extractDataText(rawBody)  → 取 data 段文本（裸数组根原样透传，见 2.9.2）
       ├─ parser(dataText, issues)  → DTO → 领域模型（可能抛错 → PARSE_FAILED）
       └─ issues.length > 0 → XLogger.w（留痕，但不报错）

这张图建议对照 RcpClient.ets:188-275 逐行读一遍。八成的"网络层疑难杂症"都能在这张图上定位到是哪一步——例如"错误文案不对"一定在 ⑤/⑦，"请求头不对"一定在 ③/②，"重复提交"一定在 ⑨/⑪ 之外（即不该走到重试）。

---

2.4 重试设计

2.4.1 三条原则

三条原则被写进类型与代码，而不是写在文档里靠自觉（HttpTypes.ets:75-90、RetryInterceptor.ets:11-15）：

原则	代码落点
仅幂等请求重试	RetryInterceptor.onError 第 2 步：if (ctx.options.idempotent !== true) { return error; }
仅可恢复错误重试	第 5 步：if (!policy.retryOn(error)) { return error; }，默认实现是 e.retryable
有上限与退避	RetryPolicy.maxAttempts / baseBackoffMs 是必填字段；第 4 步检查 ctx.attempt >= policy.maxAttempts，命中上限时显式 ctx.retryPlan = undefined——否则此前 Auth 为 401 写入的刷新计划会让上限失效（见 2.3.7）

注意第 2 步的位置在第 5 步之前——注释写了"非幂等请求绝不重试 —— 这是安全底线，优先于一切"。即使错误是 5xx（retryable: true），只要请求非幂等就不重试。这个顺序不是随手写的。

RequestOptions.idempotent 的注释（HttpTypes.ets:185-189）值得抄下来：

是否幂等。决定能否重试 —— POST 提交审批必须为 false，重试会造成重复单据。幂等性由业务语义决定，不由 HTTP 方法决定。

DefaultHttpApi 的默认值体现了后半句（HttpApi.ets:57-103）：GET 默认 idempotent: true；POST / PUT / DELETE 默认 idempotent: false。要让写操作重试，必须显式传 idempotent: true，而这个显式声明本身就会在 code review 里被看见。

2.4.2 指数退避 + 抖动

// RetryInterceptor.ets:60-70
/**
 * 指数退避 + 抖动。
 * 抖动（jitter）很关键：没有抖动时，一批同时失败的客户端会在同一时刻集体重试，
 * 把刚恢复的服务再次打挂。
 */
static backoff(baseMs: number, attempt: number): number {
    const exponential: number = baseMs * Math.pow(2, attempt - 1);
    // 0.5~1.0 的随机因子，等价于 +/- 25% 抖动
    const jitter: number = 0.5 + Math.random() * 0.5;
    return Math.round(exponential * jitter);
}

以 baseBackoffMs = 300 为例：

attempt	指数部分	实际等待区间
1	300ms	150 ~ 300ms
2	600ms	300 ~ 600ms
3	1200ms	600 ~ 1200ms

抖动解决的是惊群问题。想象一次后端重启：1 万个客户端在同一秒失败、baseMs 相同、退避函数确定，那么它们会在同一毫秒一起重试，正好在服务刚起来、最脆弱的时候再打一次。加了抖动后，重试请求被摊平到半个退避窗口内。

不需要抖动的场景只有一种：你希望重试的时刻可预测以便测试。那时应该用 Mock 注入确定的延迟，而不是去掉抖动。

2.4.3 为什么重试循环在 RcpClient 而不在拦截器

RcpClient.ets:181-187 的注释：

重试循环放在这里（而不是拦截器内部）的原因：重发涉及"取消检查、尝试计数、退避等待、401 刷新"四件事，把它们集中在一处，语义清晰且只有一份实现。

反面设计是把 while 写在 RetryInterceptor.onError 里。会立刻带来三个问题：

1. onError 的返回类型是 AppError，不是 Promise<Result<T>>，重发必须打破这个签名；
2. 取消语义需要重新实现一遍（ctx.cancelled 在每一轮开头检查），极容易漏掉某一轮；
3. 拦截器内部再调 chain.runBefore 会造成递归执行链，LoggingInterceptor 的 session.begin() 被重复调用，日志里出现重复的 --> 行。

集中在一处的代价是 RcpClient.execute 那个 while (true) 有点长（约 60 行）。用一个有点长的循环换掉三处重复实现，是划算的。

2.4.4 各接口的重试声明

真实工程的声明情况（feature_approval/.../ApprovalRemoteDs.ets）：

接口	方法	idempotent	retry	理由
/approval/list	GET	true	defaultIdempotentRetry()	纯读，天然幂等
/approval/detail	GET	true	defaultIdempotentRetry()	纯读
/approval/count	GET	true	defaultIdempotentRetry()	纯读
/approval/submit	POST	false	noRetry()	写操作，重复单据
/approval/withdraw	POST	false	noRetry()	写操作
/approval/decide	POST	false	noRetry()	写操作
/auth/refresh	POST	true	默认	刷新是幂等的，且它是"救命路径"，必须允许重试

最后一行是唯一一个"POST 但 idempotent: true"的例子，理由写在 TokenRefresher.ets:167-169：

needAuth: false —— 刷新请求本身不能带（可能已过期的）访问令牌，否则服务端会先因过期令牌返回 401，导致刷新永远进不去。 idempotent: true —— 刷新是幂等的，允许网络层重试；这是它能作为"救命路径"的前提。

---

2.5 Result 模型

2.5.1 定义

// lib_base/src/main/ets/result/Result.ets
export abstract class Result<T> {
}

export class Success<T> extends Result<T> {
    readonly value: T;
    constructor(value: T) { super(); this.value = value; }
}

export class Failure<T> extends Result<T> {
    readonly error: AppError;
    constructor(error: AppError) { super(); this.error = error; }
}

两个设计决策的理由都写在文件头（Result.ets:3-12）：

为什么不用 { ok: boolean, data?: T, error?: AppError }：布尔判别下 data 与 error 都是可选的，调用方总能写出"访问了不存在的 data"的代码；类继承 + ArkTS 的类型收窄，能让编译器在 instanceof Success 分支内保证 value 存在。

为什么 Failure 不带泛型：失败分支不持有 T，带上泛型参数只会让类型推导变啰嗦，运行时也不存在那个 T。这就是为什么 Failure<T> 里没有 value 字段、Failure 的构造只接收 AppError。

实践中常见的写法分两类，注意区分：

// 从函数返回：用偏函数形式，T 由返回类型推导
async function load(): Promise<Result<Approval>> {
    return err<Approval>(e);          // 显式 T
}

// 判断：必须先 instanceof 再取字段
if (result instanceof Success) {
    const value: Approval = (result as Success<Approval>).value;
}

(result as Success<Approval>) 这个 cast 看起来啰嗦，但它是代价最低的写法：result instanceof Success 已经把分支收窄到了 Success，cast 只是补上泛型参数。若省略 cast，ArkTS 在某些嵌套场景下会推导出 Success<unknown> 而导致后续字段访问报错。

2.5.2 工厂函数

// Result.ets:34-51
export function ok<T>(value: T): Result<T> { ... }
export function err<T>(error: AppError): Result<T> { ... }

/** 把可能抛异常的同步块包成 Result，避免异常逃逸出数据访问层 */
export function attempt<T>(block: () => T, onError: (e: Error) => AppError): Result<T> {
    try {
        return new Success<T>(block());
    } catch (e) {
        return new Failure<T>(onError(e as Error));
    }
}

attempt 的用途是包裹同步的 IO（RDB 查询、文件读）。它的价值在于把"可能抛异常的第三方 API"转成 Result，从而让仓储层的 Result<T> 返回契约不会被一个意外的 throw 打破。

2.5.3 Results 组合子

方法	签名要点	典型用途
orElse	(Result<T>, fallback: T) => T	"有默认值就行"的读场景
valueOrUndefined	(Result<T>) => T | undefined	UI 层可选渲染
errorOrUndefined	(Result<T>) => AppError | undefined	只想拿错误做日志/判断
map	(Result<T>, (T) => R) => Result<R>	变换成功值，失败原样透传
flatMap	(Result<T>, (T) => Result<R>) => Result<R>	串联两次可能失败的调用
fold	(Result<T>, onSuccess, onFailure) => R	一并收敛两个分支，保证两种结局都被显式处理
recover	(Result<T>, (AppError) => Result<T>) => Result<T>	失败时尝试恢复
onSuccess	副作用，返回原 result	只有成功才做的事（写缓存、埋点）
onFailure	副作用，返回原 result	失败才做的事（注意过滤取消类错误）

两个使用纪律：

1. fold 优于 if (r instanceof Success)。if 会让"忘了处理失败分支"变成一件可能的事；fold 强制两个回调都传。
2. onFailure 里必须先判 error.isCancellation。注释写了："取消类错误应在这里被过滤掉，不要触发用户提示"。这条在真实工程里被反复使用，例如 ApprovalRepositoryImpl.ets:152 / :191 / :211 三处判断都是 error !== undefined && !error.isCancellation。

Results 存在的动机写在文件头：让"取值 → 变换 → 分支"这套高频动作有统一写法，避免每个 ViewModel 里都出现 if (r instanceof Success) 的复制粘贴。

2.5.4 sequence：批量提交的语义

// ResultExt.ets:75-90
/**
 * 把 Result 列表收敛为"全成功才成功"的 Result 列表。
 * 用于批量提交这类语义：要么整体成功，要么明确告知失败项。
 */
export function sequence<T>(results: Result<T>[]): Result<T[]> { ... }

注意它的语义是短路：遇到第一个 Failure 就返回，且返回的 AppError 是那个失败项的错误。这适合"批量删除"这类操作——用户关心的是"哪个失败了、为什么"，而不是"一共成功了几个"。要后者就得换一个返回结构（例如 { succeeded: T[], failed: Array<{index, error}> }），sequence 故意不承担这个职责。

2.5.5 与第 6 章的关系

docs/06-persistence-network.md 的 6.6 节用大量篇幅论证了"为什么用 Result 而不是异常"。本篇不重复论证，只做一件事：把 Result 在真实工程中的使用位置列出来，让你知道该在哪些层看到它。

层	返回类型	说明
RcpClient.execute	Promise<Result<NetResponse>>	原始响应，未解包
HttpApi.request / get / post …	Promise<Result<T>>	已解包 + 已解析
ApprovalRemoteDs.list / detail / …	Promise<Result<Paged<Approval>>> 等	已转领域模型
ApprovalRepositoryImpl.list / submit / …	Promise<Result<ApprovalListResult>> 等	已合并 SWR / 写穿透策略
ApprovalListViewModel.load	内部持有 UiState，方法返回 Promise<void>	视图模型不再向上返回 Result

最后一行是有意的：ViewModel 是 Result 的终点。它把 Result 收敛成 @Local 状态（UiState / 列表数据 / 错误文案），View 只读状态，不碰 Result。这条边界让 View 层完全不需要 import lib_base 的错误类型。

---

2.6 AppError 与三层归一化

2.6.1 字段表

lib_base/src/main/ets/error/AppError.ets:65-92：

字段	类型	谁写	谁读	说明
code	string	归一化方	UI 分支、埋点聚合	稳定错误码，见 2.6.3
kind	AppErrorKind	归一化方	UI 粗粒度分支	大类，比逐条 code 稳定
message	string	归一化方	日志、上报	开发者可见，可含技术细节
userMessage	string	归一化方	UI Toast / 错误页	面向用户，建议由资源文件提供
httpStatus	number	HTTP 层	日志、上报	非 HTTP 来源为 0
bizCode	string	业务码层	日志、上报	非业务错误为空串
retryable	boolean	错误的产生方判定	RetryPolicy.retryOn	消费方不猜
traceId	string	上下文 / 响应体	用户反馈反查	与网络层链路标识一致
cause	Error | undefined	传输层	深度排障	保留原始异常

两条设计纪律（文件头 AppError.ets:4-9）：

1. 用"稳定字符串 code"而不是裸 Error 穿越分层——UI 只认 code，文案走 userMessage。
2. retryable 由错误的产生方判定，消费方不猜。这条把"这个错误该不该重试"的知识留在了最懂它的地方：HttpStatusMapper 知道 429/5xx 可重试，BizCodeMapper 知道 50000 可重试，NetErrors.cancelled 知道取消不可重试。RetryPolicy.retryOn 只是读这个字段。

retryable 的默认值来自 ErrorCode.isRetryableCode（AppError.ets:57-62），只认四种：NET_UNREACHABLE / NET_TIMEOUT / HTTP_429 / HTTP_5XX。注意它的注释写了"仅表达网络层语义，不代表请求可重放"——可不可重放是幂等性的事，由 RequestOptions.idempotent 决定。这两件事必须分开，否则会出现"5xx 所以重试了提交审批"的事故。

2.6.2 AppErrorKind 九类

export enum AppErrorKind {
    NETWORK = 'network',        // 连接失败、DNS 失败、无网络
    TIMEOUT = 'timeout',        // 超时
    CANCELLED = 'cancelled',    // 主动取消（页面销毁），不应提示用户
    HTTP = 'http',              // HTTP 状态码非 2xx
    BUSINESS = 'business',      // HTTP 200 但业务 code 表示失败
    PARSE = 'parse',            // 响应解析失败
    STORAGE = 'storage',        // 本地存储失败
    UNSUPPORTED = 'unsupported',// 能力不可用（设备不支持 / 权限缺失）
    UNKNOWN = 'unknown'         // 兜底
}

UI 层做分支时优先用 kind。原因：kind 的取值集合是封闭的（9 个），而 code 会随业务增长。一个只想要"网络类错误显示重试按钮"的页面，写 error.kind === AppErrorKind.NETWORK 比列出所有 NET_* code 更稳。

2.6.3 ErrorCode 前缀约定

约定：NET_ / HTTP_ / BIZ_ / PARSE_ / STORE_ / CAP_。前缀的价值在日志检索与埋点聚合：在 Kibana 里搜 HTTP_5XX 只命中一类，搜 5XX 会命中一堆无关字符串。

export class ErrorCode {
    static readonly NET_UNREACHABLE: string = 'NET_UNREACHABLE';
    static readonly NET_TIMEOUT: string = 'NET_TIMEOUT';
    static readonly NET_CANCELLED: string = 'NET_CANCELLED';
    static readonly NET_TLS: string = 'NET_TLS';
    static readonly HTTP_UNAUTHORIZED: string = 'HTTP_401';
    static readonly HTTP_FORBIDDEN: string = 'HTTP_403';
    static readonly HTTP_NOT_FOUND: string = 'HTTP_404';
    static readonly HTTP_TOO_MANY_REQUESTS: string = 'HTTP_429';
    static readonly HTTP_SERVER_ERROR: string = 'HTTP_5XX';
    static readonly BIZ_FAILED: string = 'BIZ_FAILED';
    static readonly BIZ_TOKEN_EXPIRED: string = 'BIZ_TOKEN_EXPIRED';
    static readonly BIZ_NO_PERMISSION: string = 'BIZ_NO_PERMISSION';
    static readonly BIZ_CONFLICT: string = 'BIZ_CONFLICT';
    static readonly PARSE_FAILED: string = 'PARSE_FAILED';
    static readonly STORE_FAILED: string = 'STORE_FAILED';
    static readonly CAP_UNSUPPORTED: string = 'CAP_UNSUPPORTED';
    static readonly UNKNOWN: string = 'UNKNOWN';
}

注意 HTTP_SERVER_ERROR 的值是 'HTTP_5XX' 而不是 'HTTP_500'。这是刻意的：它覆盖整个 5xx 区间，而 httpStatus 字段里保留了精确的状态码（502 / 503 / 504）。只看 code 知道类别，要看具体值读 httpStatus。

2.6.4 四个便捷成员

// AppError.ets:98-127
/** 用户取消是"正常路径"，UI 不应对它弹错误 */
get isCancellation(): boolean {
    return this.kind === AppErrorKind.CANCELLED || this.code === ErrorCode.NET_CANCELLED;
}

/** 鉴权失效需要走统一的"清会话 + 跳登录"链路 */
get isUnauthorized(): boolean {
    return this.code === ErrorCode.HTTP_UNAUTHORIZED || this.code === ErrorCode.BIZ_TOKEN_EXPIRED;
}

/** 供日志与上报使用，避免各处自行拼字符串 */
toLogLine(): string {
    return `[${this.code}] http=${this.httpStatus} biz=${this.bizCode} msg=${this.message}` +
        (this.traceId.length > 0 ? ` trace=${this.traceId}` : '');
}

/** 派生一个新错误，用于在某一层补充上下文（如补 traceId） */
with(overrides: AppErrorParams): AppError { ... }

isUnauthorized 同时认 HTTP_401 与 BIZ_TOKEN_EXPIRED，这一点很关键：真实后端可能返回 HTTP 401，也可能返回 HTTP 200 + code: 40100。若只认前者，那么"业务码形式令牌过期"就不会触发单飞刷新，表现为"某些接口莫名跳登录、某些接口不跳"——一个极难排查的不一致。

toLogLine() 是唯一的错误日志格式化方式。它的存在消除了"每个地方拼出来的错误日志格式都不一样，grep 不出来"的问题。

with() 在真实工程里被用于两个地方：RetryInterceptor.ets:45-47 追加"已重试 N 次"上下文；未来需要在某一层补 traceId 时也可以用它。

2.6.5 三层归一化

              ┌─────────────────────────────────────────────┐
   第①层      │ 传输层：rcp 抛出的原生异常                    │
              │   RcpTransport.toAppError()                  │
              │   取消 → NET_CANCELLED                       │
              │   超时 → NET_TIMEOUT                         │
              │   其他 → NET_UNREACHABLE（带 cause）          │
              └────────────────────┬────────────────────────┘
                                   ▼
              ┌─────────────────────────────────────────────┐
   第②层      │ HTTP 层：状态码非 2xx                        │
              │   HttpStatusMapper.toError()                 │
              │   401 → HTTP_401（retryable=false）          │
              │   403 → HTTP_403  404 → HTTP_404             │
              │   429 → HTTP_429（retryable=true）           │
              │   5xx → HTTP_5XX（retryable=true）           │
              │   其他 → UNKNOWN（retryable=false）          │
              └────────────────────┬────────────────────────┘
                                   ▼
              ┌─────────────────────────────────────────────┐
   第③层      │ 业务层：HTTP 200 但 code != 0                │
              │   BizCodeMapper.toError()                    │
              │   40100 → BIZ_TOKEN_EXPIRED                  │
              │   40300 → BIZ_NO_PERMISSION                  │
              │   40901 → BIZ_CONFLICT                       │
              │   50000 → HTTP_SERVER_ERROR（retryable=true）│
              │   其他 → BIZ_FAILED                          │
              └────────────────────┬────────────────────────┘
                                   ▼
                      统一出口：AppError（UI 只认它）

第③层是最容易被漏掉的一层。BizCodeMapper 的文件头注释写得很直接：

很多团队会漏掉这层，导致业务失败被当成成功，最终在 UI 上表现为"提交后没反应"。

漏掉它的典型症状就是"提交后没反应"——因为 HTTP 200 被当成成功，UI 跳回列表，但服务端其实什么都没做。用户过一会儿发现单据不存在，再提交一次，得到两张单（如果幂等键也做错了的话）。

2.6.6 一个完整例子的流转

设：提交审批时后端返回 HTTP 200，体为 {"code":40901,"message":"duplicate","data":null,"traceId":"abc123"}。

步骤	结果
RcpTransport.send	返回 NetResponse(200, {...}, '{"code":40901,...}')
runAfter（逆序）	Retry.after no-op → ErrorMap.after：isHttpSuccess 为真 → tryEnvelope 解析出 code=40901 → 回填 response.traceId='abc123' → BizCodeMapper 返回 AppError{code:'BIZ_CONFLICT', bizCode:'40901', traceId:'abc123', retryable:false} → 短路，Mock/Logging/Auth 的 after 不再执行
runOnError（正序）	Auth：isUnauthorized 为 false → 原样返回；Logging：session.finish(false, 'BIZ_CONFLICT') + FAIL 日志（成功埋点没有打过，失败在此处唯一记账）；Mock/ErrorMap：原样；Retry：noRetry() 上限为 1 → 无 retryPlan
RcpClient	plan 为空 → 返回 Failure<NetResponse>(BIZ_CONFLICT)
HttpApi.request	Failure → 直接透传 Failure<T>
ApprovalRepositoryImpl.commitWrite	原样透传（保留 code / bizCode / traceId）
ViewModel	@Local 写入 error.userMessage = '该单据已提交，请勿重复操作'
View	显示提示

注意这个例子里的埋点视角：HTTP 200 但业务失败时，Logging.after 根本不会执行（它在逆序 after 链里排在 ErrorMap 之后，ErrorMap 已短路），不存在"先打 success=true 再打 success=false"的重复记账——失败请求由 onError 的 finish(false, code) 唯一记账。这正是 2.3.2 说的"after 逆序（洋葱）"换来的语义：埋点的 success 字段与请求的真实结局一一对应。

---

2.7 401 单飞刷新

2.7.1 为什么必须单飞

TokenRefresher.ets:13-19 的注释是这个问题最好的答案：

一次冷启动或一次返回前台，很可能有 5~10 个并发请求同时收到 401。若各自触发刷新：

• 产生 N 次无谓的刷新请求；
• 更致命的是服务端 refreshToken 是轮换的：第 1 次刷新成功后旧 refreshToken 立即失效，后 4 次拿旧值去刷必然失败 → 触发 onUnauthorized → 用户"莫名其妙被登出"。

第二点是关键。如果 refreshToken 不轮换，那么多刷几次只是浪费请求，用户无感。但轮换是安全实践的主流做法（refreshToken 一次性使用，用后作废并发新的），此时并发刷新会必然失败。

故障的用户视角：用户打开 App 看到列表在转圈，然后突然被踢到登录页。日志里有一堆 refresh failed。开发者第一反应是"刷新接口有问题"，去查服务端发现刷新接口每次都返回成功——因为第一次确实成功了。

2.7.2 pending 的实现与清理时机

// TokenRefresher.ets:106-124
refreshToken(): Promise<boolean> {
    const inflight: Promise<boolean> | undefined = this.pending;
    if (inflight !== undefined) {
        XLogger.i(this.tag, () => 'refresh already in flight, joining the same promise');
        return inflight;
    }
    const started: Promise<boolean> = this.runRefresh();
    this.pending = started;
    // 清理排在"结果已交付"之后；身份校验避免误清新一轮
    started.then((okFlag: boolean) => {
        this.release(started, okFlag);
    }, (e: Error) => {
        XLogger.e(this.tag, () => `refresh promise rejected unexpectedly: ${e.message}`);
        this.release(started, false);
    });
    return started;
}

单飞的实现极简：一个 pending 字段缓存"正在跑的那一个 Promise"。所有并发调用 await 的是同一个对象，于是"等同一个结果"这个语义不需要任何锁、队列或状态机。

清理时机的坑：注释（TokenRefresher.ets:25-29）明确写了不能用 finally：

如果在 finally 里清，那么清理发生在 Promise 交付给调用方之前，极端时序下（微任务被插队）会出现"上一个刷新还没交付、下一个已经开始"的重叠刷新。因此这里用 then 把清理排在交付之后，并用 this.pending === started 做身份校验，保证不会把"新一轮的 pending"误清掉。

release 里的身份校验：

// TokenRefresher.ets:231-239
private release(promise: Promise<boolean>, success: boolean): void {
    if (this.pending === promise) {
        this.pending = undefined;
    }
    ...
}

如果不用 this.pending === promise 判断，就会出现这样的时序问题：A 轮刷新慢，B 轮刷新已经开始并把 pending 设成了 B 的 Promise；此时 A 轮完成，无脑 this.pending = undefined，于是 B 轮失去了单飞保护，C 轮的调用者会看到 pending === undefined 从而又发起一次刷新。

这个 bug 的复现概率很低（需要精确的微任务交错），但一旦出现就是"偶尔莫名被登出"。而这类问题的排查成本极高——因为它在你的机器上永远复现不了。

2.7.3 三条防线

防线	位置	触发条件	行为
① 预刷新	AuthInterceptor.before	shouldRefresh() && idempotent === true	先刷新再发请求，省掉一次 401 往返
② 401 触发	AuthInterceptor.onError	收到 401 且 needAuth !== false	写 retryPlan{needRetry, delayMs:0, requireRefresh:true}，由 RcpClient 刷新后重放
③ 已刷仍 401	AuthInterceptor.onError	ctx.marks[MARK_REFRESHED] === true	说明 refreshToken 也失效 → 直接 onUnauthorized('refresh_retry_unauthorized')，不再重放

第三道防线是必须的，否则就会出现"刷新成功但服务端仍然 401"时的无限循环：刷新 → 重放 → 401 → 刷新 → …。这条防线上有两道闸门，缺一不可：

1. 循环级上限 + 标记继承（RcpClient.ets:191-216）。ctx 每一轮都会重建，任何"只写在 ctx 上"的标记都活不过一次重放——这正是无界循环的根源。因此 execute 用循环级局部变量 refreshedOnce 记录"本次请求是否已刷新并重放过"，并在每轮构造新 ctx 时把 AuthInterceptor.MARK_REFRESHED 继承进去；重放轮再次 401 时，AuthInterceptor.onError 见到该标记即强制登出（refresh_retry_unauthorized）。
2. 双保险闸门（RcpClient.ets:254-260）。即便标记的继承逻辑将来被改坏，requireRefresh 分支里还有一道不依赖任何 ctx 标记的判断：refreshedOnce 已为 true 就直接 onUnauthorized 并放弃，绝不发生二次刷新。

一次请求的生命周期里"刷新并重放"最多发生一次——这是写进执行循环结构的硬约束，不是靠调用方自觉。

NetContext.marks 的类型是 Record<string, boolean>，注释写明"键为拦截器私有常量"。AuthInterceptor.MARK_REFRESHED = '__auth_refreshed__' 用双下划线包裹，是一种约定俗成的"这是内部键"标记。

为什么预刷新只对幂等请求做？因为预刷新会额外增加一次网络往返。对 GET 列表这类高频调用，如果 token 快过期就先刷一次，等于每次到临界点都会多一次请求；而且多个并发 GET 会各自判断 shouldRefresh() 都为真——不过它们会被单飞收敛成一次刷新，所以成本可控。对 POST 提交，重放语义更敏感，宁可让服务端 401 再走标准流程。

2.7.4 unauthorizedHandled 一次性闸门

// TokenRefresher.ets:43-49
/**
 * onUnauthorized 的一次性闸门。
 * 契约要求"只应触发一次"：一次 401 风暴里 AuthInterceptor 与 RcpClient
 * 都会调它，若不去重会清 5 次存储、广播 5 次登出、跳 5 次登录页。
 * 刷新成功后复位，使下一段会话仍能被正常登出。
 */
private unauthorizedHandled: boolean = false;

实现在 onUnauthorized（TokenRefresher.ets:131-144）：

onUnauthorized(reason: string): void {
    if (this.unauthorizedHandled) {
        XLogger.d(this.tag, () => `onUnauthorized ignored (already handled): ${reason}`);
        return;
    }
    this.unauthorizedHandled = true;
    XLogger.must(this.tag, () => `unauthorized, purging session. reason=${reason}`);
    this.purge(reason).then(() => {
        // 先清数据、再广播
    }).catch((e: Error) => {
        XLogger.e(this.tag, () => `purge session failed: ${e.message}`);
    });
}

三个细节：

1. 用 XLogger.must 而不是 XLogger.e。must 是不受日志级别过滤的强制输出（见 03 篇）。被登出是"必须能在日志里看到"的事件。
2. purge 是异步的，但 onUnauthorized 是同步签名。因为接口 AuthTokenProvider.onUnauthorized(reason: string): void 是同步的，注释说明"这样即使存储清理较慢，UI 的登出跳转也不必等它"。
3. 先清数据、再广播。注释：根组件收到信号时状态已经干净，否则登录页可能先渲染出旧用户名再被清空（一闪而过）。

purge 的三步（TokenRefresher.ets:222-229）：

private async purge(reason: string): Promise<void> {
    const store: TokenStore | undefined = TokenStore.get();
    if (store !== undefined) { await store.clear(); }   // 1. 清 token 存储
    SessionStore.connect().reset();                     // 2. 清会话状态
    LogoutBus.connect().broadcast(reason);              // 3. 广播登出信号
}

顺序不能换：broadcast 会让根组件（entry/pages/Index.ets 的 @Monitor('logoutBus.logoutEpoch')）跳登录页，而登录页会读 SessionStore 里的用户名。如果先广播再清，登录页就会瞬间渲染出上一个用户的昵称。

2.7.5 刷新请求自身的参数

// TokenRefresher.ets:167-178
const result: Result<TokenPair> = await this.http.post<TokenPair>(
    TokenRefresher.REFRESH_PATH,          // '/auth/refresh'
    TokenRefresher.tokenPairParser,
    { refreshToken: refresh },
    {
        needAuth: false,      // 不带（可能已过期的）访问令牌
        idempotent: true,     // 刷新是幂等的，允许网络层重试
        tag: 'auth:refresh'
    });

needAuth: false 这一点极易漏。如果刷新请求也带 Authorization 头，那么服务端在鉴权中间件里就会先因为过期令牌返回 401，刷新请求永远进不到刷新逻辑。表现为"刷新永远失败 → 永远登出"。

idempotent: true 让刷新成为"救命路径"：弱网下刷新请求本身被重试，而不是一次失败就登出。

2.7.6 轮换兼容

// TokenRefresher.ets:197-202
/**
 * 轮换兼容：服务端可能不返回新的 refreshToken（未开启轮换），
 * 此时必须**保留旧的**。直接覆盖会让下一次刷新必然失败 —— 这是很常见的坑。
 */
const effectiveRefresh: string = pair.refreshToken.length > 0 ? pair.refreshToken : refresh;
const merged: TokenPair = new TokenPair(pair.accessToken, effectiveRefresh, pair.expiresIn);

同时注意 store.save(merged, store.currentUser()) 传的是 store.currentUser() 而不是空对象：

用 store.currentUser() 而不是空 UserInfo：/auth/refresh 只返回令牌，把用户信息一并覆盖会清掉昵称头像与 tenantId。

这是"部分更新"场景的通病：刷新接口只返回令牌，但保存逻辑是"整体覆盖"，于是一次刷新把用户昵称清空了。解法是在调用处显式传入应保留的部分，而不是让存储层去猜。

---

2.8 幂等键

2.8.1 为什么由客户端生成

HttpApi.ets:187-195 的注释：

客户端生成、随请求发送、服务端据此去重。这比"服务端自己防重"更可靠：能在网络层重发与用户重复点击两种场景下都生效。

服务端自己防重的常见做法是"同一用户 5 秒内相同内容视为重复"。它有两个漏洞：一是窗口外的重试（用户 6 秒后点重试）防不住；二是"相同内容"的判定不精确（用户确实想提交两张一模一样的报销单）。

客户端生成的键则精确地对齐业务语义：同一个用户动作 = 同一个键。服务端只需按键去重，不需要猜业务。

IdempotencyKeys.next 的实现（HttpApi.ets:196-201）：

export class IdempotencyKeys {
    static next(prefix: string): string {
        const rand: number = Math.floor(Math.random() * 0xFFFFFF);
        return `${prefix}-${Date.now().toString(36)}-${rand.toString(16)}`;
    }
}

时间戳 + 随机数，不带用户信息（避免键本身泄漏隐私）。prefix 用于服务端侧聚合与排查（approval / approval-withdraw / approval-approve）。

2.8.2 生成时机：点击提交时一次

ApprovalCreatePage.ets:20-27 的注释是本篇最值得抄进团队规范的一段：

✗ 错误做法：在发请求的地方生成（submit() 里每次 new 一个键） 用户点提交 → 请求超时（但服务端其实已处理成功，只是响应丢了）→ 用户点"重试" → 带一个新键 → 服务端认为这是第二次提交 → 两张审批单。也就是说"每次生成"等于没有幂等。

✓ 正确做法：在用户点击提交的那一刻生成一次，记在 this.idempotencyKey 上；失败后用户可以无限次重试，每次都复用同一个键，服务端据此去重；只有在"这次业务动作真的结束了"（提交成功、或用户改了内容重新提交）时才重置。

对应的代码（ApprovalCreatePage.ets:236-251）：

if (this.idempotencyKey.length === 0) {
    this.idempotencyKey = IdempotencyKeys.next('approval');
}
// ...
const cmd: SubmitApprovalCmd = new SubmitApprovalCmd({ /* ... */, idempotencyKey: this.idempotencyKey });

注意 if (this.idempotencyKey.length === 0) 这个守卫：它同时覆盖了两种情况——首次提交（空 → 生成）与重试（非空 → 复用）。这就是"生成一次、复用多次"的全部实现。

2.8.3 保留与重置规则

事件	键的处理	位置	理由
用户首次点击提交	生成	:237	新业务动作
提交成功	重置为空	:279	动作已结束，键作废
用户改了表单内容	重置为空	:310	内容变了就是另一个业务动作
提交失败（网络/服务端错误）	保留	:318	重试必须复用，否则重复单据

第三条最反直觉，但注释解释了（ApprovalCreatePage.ets:29-30）：

为什么"改了内容"要重置键：内容变了就是另一个业务动作，复用旧键会被服务端当成重复提交直接拒掉（40901），用户会卡死在"改了也提交不了"。

这是一个很典型的坑：只知道"要复用键"的开发者，会把键留在页面上直到成功为止。用户提交失败后改了标题再提交，服务端看到旧键 → 返回 40901 → 提示"该单据已提交，请勿重复操作" → 用户困惑（"我明明改了内容，而且它根本没提交成功"）。

2.8.4 幂等键的传输与响应

传输：RcpClient.buildHeaders 把 options.idempotencyKey 写成 Idempotency-Key 头（RcpClient.ets:316-319）。用 HTTP 头而不是请求体字段，原因是头是传输层关注点，与业务字段解耦——同一个键也能被网关、WAF 等中间层读取。

响应：服务端识别出重复后返回 code: 40901，经 BizCodeMapper 归一为 BIZ_CONFLICT，用户看到"该单据已提交，请勿重复操作"。

一个完整的幂等闭环（ApprovalRepositoryImpl.ets:254-266 的注释）：

• 网络层已由 RequestOptions.idempotent=false 禁止自动重试；
• 这一层也不做应用层重试；
• 用户点"重试"时复用同一个 idempotencyKey（幂等安全）；
• 服务端 40901（重复提交）会被归一为 BIZ_CONFLICT，UI 提示"该单据已提交"。 一句话：幂等键是允许重试的前提，而重试的决定权交给用户。

---

2.9 契约漂移的可观测性

2.9.1 三种归宿

响应解析过程中发现的"字段缺失 / 类型不符"有两种处理方式，取决于它是否影响可用性：

情况	处理	理由
载荷为空（'' / 'null' / '[]' / '{}'）	返回空页 / 空值，不是错误	可能是分页越界或后端确实没数据
有内容但结构不符	抛出 → HttpApi 归一为 PARSE_FAILED	契约变了
部分字段缺失但主体可用	降级填默认值 + 记录 issue，返回成功	静默数据丢失的早期信号

第三种是最需要可观测性的。ApprovalRemoteDs.pageParser 的注释（ApprovalRemoteDs.ets:195-203）：

• 空载荷：可能是分页越界或后端没数据 → 空页，不是错误；
• 有内容但结构不符：说明契约变了 → 抛出，由 HttpApi 归一为 PARSE_FAILED。若这里也静默返回空页，表现是"用户列表忽然空了"，而日志里什么都没有，是典型的"静默数据丢失"事故。

2.9.2 HttpApi.unwrap 的处理

// HttpApi.ets:111-131
private static unwrap<T>(response: NetResponse, options: RequestOptions, parser: Parser<T>): Result<T> {
    const tag: string = options.tag === undefined ? options.path : options.tag;
    const dataText: string = DefaultHttpApi.extractDataText(response.rawBody);

    const issues: string[] = [];
    let value: T;
    try {
        value = parser(dataText, issues);
    } catch (e) {
        const detail: string = (e as Error).message;
        XLogger.e('net:HttpApi', () => `parser threw for ${tag}: ${detail}`);
        return new Failure<T>(NetErrors.parse(tag, detail));
    }

    // 解析过程中记录到的问题不上报为错误，但要留痕：
    // 它意味着后端契约与客户端预期已经漂移，是"下一次线上事故"的早期信号。
    if (issues.length > 0) {
        XLogger.w('net:HttpApi', () => `parse issues (${issues.length}) for ${tag}: ${issues.join('; ')}`);
    }
    return new Success<T>(value);
}

三层设计：

1. issues 是出参（Parser<T> = (dataText: string, issues: string[]) => T）。为什么用出参而不是返回值包装：保持 Result<T> 这一条统一契约，调用方不需要先解包再判断。
2. parse 抛错 → PARSE_FAILED。这是"结构不符"的归宿。
3. issues 非空 → WARN 日志，但仍返回 Success。这是"降级但可观测"的归宿。

unwrap 上游的 extractDataText（HttpApi.ets:133-159）也有两条值得知道的契约：

• 裸数组根原样透传（:141-143）：JsonReader.tryParse 只收对象根（根节点是数组/标量时返回 undefined，见 JsonReader.ets:46-68 的注释——不拦住的话，后续所有键读取都会静默 miss）。而"裸数组响应"是一种需要交给 parser 检测的契约漂移形态（Mock 服务器的 simulate=raw-array 就是演练它），必须在 extractDataText 里显式放行，不能被折叠成 'null'。
• 无 data 段或 data 为标量时同样有明确约定：非统一包装 → 整个响应体交给 parser；标量 data → JSON.stringify 成合法 JSON 文本，保持"parser 只吃 JSON 文本"的契约。

2.9.3 数据源的 drain：把 issues 递出去

HttpApi 创建的 issues 数组是局部变量，请求返回后就没了。ApprovalRemoteDs 用 collector 出参把它复制出来（ApprovalRemoteDs.ets:242-255）：

/**
 * 把 HttpApi 收集到的 issues 复制到调用方的收集器。
 * 为什么是"复制"：HttpApi 每次请求都会新建 issues 数组（局部变量），
 * 不复制出去，请求返回后这些信息就只能靠日志捞，无法驱动埋点。
 */
private static drain(from: string[], to?: string[]): void {
    if (to === undefined) { return; }
    for (let i = 0; i < from.length; i++) { to.push(from[i]); }
}

drain 在三个 parser 工厂里各调一次（:209 / :223 / :234）。注释也诚实指出了这个设计的缺点："出参容易被遗忘。所以只有 repo 一个调用方，且它每次都传。"——这是"为了不打破 Result<T> 统一契约"付出的代价，工程师接受了它。

2.9.4 仓库层上报

// ApprovalRepositoryImpl.ets:26-32
/**
 * 契约漂移事件名。
 * 说明：lib_log 的 EventNames 是**跨模块共享契约**，新增事件应先在那里注册。
 * 该事件尚在评审中，这里先用模块内常量落地，避免为了一个实验性指标
 * 去改动公共契约（改公共契约会让所有模块重新走一遍评审）。
 */
private static readonly EVENT_CONTRACT_DRIFT: string = 'contract_drift';

reportDrift 的实现（ApprovalRepositoryImpl.ets:400-412）：

private reportDrift(tag: string, issues: string[]): void {
    if (issues.length === 0) { return; }
    XLogger.w(ApprovalRepositoryImpl.LOG_TAG,
        () => `contract drift on ${tag} (${issues.length}): ${issues.join(' | ')}`);
    Analytics.emit(EventBuilder.of(ApprovalRepositoryImpl.EVENT_CONTRACT_DRIFT)
        .str(EventProps.ROUTE, tag)
        .num(EventProps.COUNT, issues.length)
        .str(ApprovalRepositoryImpl.PROP_SAMPLE, issues[0])
        .result(false, 'PARSE_DRIFT')
        .build());
}

埋点的三个属性（route / count / sample）对应三种看板用法：

• 按 route 聚合 → "哪个接口开始漂移了"；
• count 的分布 → "漂移严重程度"；
• sample → "具体是哪个字段少了"（样本字符串会经 Analytics 的 Masker 脱敏）。

reportDrift 被调用的位置（:107 / :138 / :182 / :203 / :272 / :303）覆盖了全部六个接口。注意它在 commitWrite 里也调了——写操作的响应同样可能字段缺失，而且写操作的静默降级更危险（用户以为提交成功，但拿到的 Approval 里没有 id）。

2.9.5 为什么不上报为错误

代码注释给了完整的答案（ApprovalRepositoryImpl.ets:388-399）：解析问题不是错误（HttpApi 已经把降级做完了，用户看到的是可用数据），但它是"下一次线上事故的早期信号"：

后端改了字段名/类型，客户端静默降级成默认值，用户看到的是"金额都是 0"、"状态都是待审批"。等到有人投诉时，已经过去很久了。所以这里把它变成可聚合的指标。

这句话值得单独记住，它是这一节的全部价值：可观测性的目标不是"记录错误"，而是"让还没变成投诉的问题可见"。

---

2.10 常见误区

1. 把 token 写进 SessionConfiguration.headers

见 2.2.2。症状是"刷新成功但请求仍带旧 token → 无限 401 → 被登出"，且 TokenStore 里的值是正确的，极易误判为服务端问题。

2. 在拦截器里自己写 while 重试

见 2.4.3。三重后果：取消语义要重实现、日志重复、onError 的签名被破坏。

3. 用 HTTP 方法推断幂等性

POST 不一定非幂等（/auth/refresh 就是幂等的），PUT 也不一定幂等（取决于服务端实现）。RequestOptions.idempotent 的注释写得很清楚：幂等性由业务语义决定，不由 HTTP 方法决定。

4. 在"发请求的地方"生成幂等键

见 2.8.2。等于没有幂等。这是本篇最容易在 code review 里被抓到的错误，因为它的代码形态很自然（submit() 里 const key = ...）。

5. RetryPolicy.retryOn 里判断"是否幂等"

常见写法：retryOn: (e) => e.retryable && isIdempotentPath(...)。这是错的——幂等性判断已经在 RetryInterceptor.onError 的第 2 步做过了，而且 retryOn 拿不到 RequestOptions。正确职责划分：retryOn 只回答"这个错误本身可恢复吗"。

6. pending 用 finally 清理

见 2.7.2。会退化成重叠刷新，且概率极低、极难复现。

7. 只处理 HTTP 401，不处理 code: 40100

isUnauthorized 同时认两者。只认前者会表现为"某些接口跳登录、某些接口不跳"——取决于后端用哪种形式返回令牌过期。

8. 在 onFailure 里直接弹 Toast

取消类错误（用户返回上一页触发的 cancelToken.cancel()）会走进 onFailure。不看 error.isCancellation 就直接弹提示，症状是"用户每返回一次就闪一个错误提示"。

9. 跳过 ErrorMap，让业务自己判断 statusCode

后果是"有的地方 401 弹登录、有的地方 401 弹通用错误"（ErrorMapInterceptor.ets:10-12 的注释）。这是"错误处理分散"的经典症状：每个调用方都以为自己在做正确的事。

10. 把 issues 当错误处理

issues 非空仍然返回 Success。如果调用方看到 issues 非空就返回失败，会把"一个可选字段缺失"升级成"列表加载失败"——比静默降级更糟。

11. 让 MockInterceptor 直接 return new Success(...)

before 的返回类型是 AppError | undefined，它不能返回成功结果。Mock 必须把响应写进 ctx.mockedResponse，否则会绕过 after 阶段——错误映射与日志全部失效，Mock 与真实的链路出现分歧（见 2.3.5）。

---

2.11 实践任务

任务 1：注入一个可复现的失败，验证重试与告警

1. 打开 code/office-flow，在 entry 的启动流程里找到 AppInitializer.initMock()；
2. 添加 MockRegistry.setFailureRate(0.5)（50% 请求返回 503）；
3. 运行 entry，反复进入审批列表，观察日志中的：
   • HIT ... status=503（Mock 命中）
   • injected failure for ...（注入日志）
   • retry approval.list attempt=2 after XXXms（重试日志，注意 delay 的抖动）
   • SLOW REQUEST（若退避叠加到 3s 以上）
   • FAIL ... [HTTP_5XX]（重试耗尽后的最终失败）
4. 观察 Trace.count('net:retry', 1) 是否在 hiTraceMeter 里出现。

验收

• [ ] 能观察到至少一次 attempt=2 的重试日志
• [ ] 两次重试的 delay 值不相同（抖动生效）
• [ ] 关闭 Mock（MockRegistry.enable(false)）后，同样操作不再出现 MOCKED 标记

交付物：一段不超过 30 行的日志摘录（含时间戳与 traceId），标注出上述 5 类行。

任务 2：为新接口写一个完整的声明

为"批量审批"设计一个 POST /approval/batch-decide，要求：

1. 正确声明 idempotent / retry，并说明理由；
2. 提供一个具名 parser，明确"空载荷"与"结构不符"两种情况的处理；
3. 决定要不要 idempotencyKey；
4. 写出该接口在 BizCodeMapper 里需要新增（或不必新增）的业务码映射。

验收

• [ ] idempotent: false 且 retry: noRetry()，理由写明"写操作、重复审批有外部后果"
• [ ] 载荷为空返回空数组（不是错误）；结构不符 throw
• [ ] 有 idempotencyKey，且生成时机写在注释里（用户点击"批量通过"时）
• [ ] 说明服务端返回 40901 时的用户文案

交付物：一段 ApprovalRemoteDs 风格的方法实现（20~40 行，含注释）。

任务 3：复现"token 写进 Session"的事故

1. 在 RcpTransport.ensureSession 里临时加上 headers: { 'Authorization': 'Bearer FIXED_TOKEN' }；
2. 登录后手动把 TokenStore 里的 token 改掉（或用 AuthMockRules 的变体开关触发刷新）；
3. 观察请求头是否仍带旧值；
4. 恢复代码，改用 AuthInterceptor 注入，确认请求头跟着变。

验收

• [ ] 能复现出"存储里是新 token、网络上跑的是旧 token"
• [ ] 能解释为什么 LoggingInterceptor 打印的头是"最终发出的头"（它在链的第 2 位，Auth 之后）
• [ ] 恢复后 Authorization 每次都等于 TokenStore.accessToken()

交付物：两次请求的日志对照（改前 / 改后），各不超过 10 行。

---

2.12 对表记录：发现的实现缺陷

编写本篇时逐行对照过真实工程，早期版本曾记录三处代码层面的不一致。三处均已修复，留作"文档对表 → 工程收敛"的记录：

#	位置	当时的问题	现状
1	lib_network/src/main/ets/rcp/NetInterceptor.ets:2	一行自引用导入（三个符号全部定义在本文件内，'../NetInterceptor' 指向不存在的路径），依赖编译器对"未解析导入 + 同名本地定义"的宽容	已删除。文件头只保留 lib_base 与 ../model/HttpTypes 的合法导入
2	lib_network/src/main/ets/rcp/RcpClient.ets:20	文件头注释写作"只需改 RcpTransport 的 3 个方法（createSession / send / mapError）"，与实际方法名不符	已改为 ensureSession / send / toAppError，与类中实际签名一致（见 2.1.3）
3	lib_network/src/main/ets/model/HttpTypes.ets:7	注释提到的 RcpInterceptorBridge 在工程中不存在，与"RcpTransport 是唯一适配点"的表述冲突	已统一为 RcpTransport（lib_network/src/main/ets/rcp/RcpClient.ets）

另外，本篇早期版本描述的部分行为也随工程演进而更新：NetResponse 从未使用过的 elapsedMs 字段已删除（耗时统一走 NetContext.elapsedMs）；NetInterceptor 的死导出 NET_TRACE_ENABLED、HttpApi 的死导出 parseFailure / isCancelled、RetryInterceptor 的死常量 NEED_RETRY / NEXT_DELAY_MS 均已清理；runAfter 改为逆序（洋葱模型，见 2.3.2）；401 刷新-重放加上循环级 refreshedOnce 上限与双保险闸门（见 2.7.3）；RetryInterceptor 达上限时显式清空 retryPlan（见 2.3.7）。正文均已按当前代码改写。

---

2.13 延伸阅读

• 官方文档 → 网络管理 → Remote Communication Kit（rcp）→ 会话管理与请求配置 —— 理解 createSession / fetch 的官方语义，对照本篇 2.1.3 的五个方法
• 官方文档 → 网络管理 → Remote Communication Kit（rcp）→ 拦截器与重试策略 —— 对照本篇 2.3 / 2.4，看清哪些是本工程自建、哪些是 SDK 提供
• 官方文档 → 应用框架 → ArkTS → 类型系统与 instanceof 收窄 —— 理解 Result<T> 为什么必须配 (result as Success<T>) 的 cast
• 官方文档 → 应用框架 → ArkTS → 模块化与循环依赖 —— 理解 2.3.1 里 LoggingSession 接口为什么要单独放在 NetInterceptor.ets
• 教程 docs/06-persistence-network.md 6.3~6.6 节 —— 概念模型部分
• 教程 docs/11/01-architecture-modules.md 1.6 节 —— AuthTokenProvider 与前一篇的"跨模块解耦三手法"呼应
• 教程 docs/11/03-logging-tracking.md —— Masker 脱敏、Trace 打点、Analytics.network 的完整实现
• 教程 docs/11/04-login-auth.md —— TokenRefresher 与 TokenStore 的完整登录链路
• 教程附录 D —— 本地 Mock 方案的 MockRegistry 规则写法与 server/mock-server.js

---

导航

上一章：11/01 架构与模块划分 ｜ 下一章：11/03 日志与埋点