HarmonyOS 工程化实践：HAP、HAR、HSP 模块拆分与依赖治理

一、单 HAP 打天下会遇到什么

项目初期把所有代码放进一个 HAP 最省事。但随着业务增长，会出现四个典型问题：包体积持续膨胀导致安装与启动变慢；多人协作时模块边界模糊、改动互相影响；不同设备形态无法按需加载；公共代码复制粘贴、重复维护。

HarmonyOS 的工程化方案是 HAP + HAR + HSP 三类包形态，各司其职。

二、HAP、HAR、HSP 的区别

关键差异：HAR 在编译期被合入 HAP，会增加使用方体积；HSP 在运行时加载，多应用可共享同一份代码，适合体积大且不必首屏加载的公共能力。

三、拆分原则：按“变更原因”而不是按“文件类型”

常见的错误拆法是把所有 model 放一个 HAR、所有 view 放一个 HAR、所有 utils 放一个 HAR。这样每次业务变更都要同时改多个模块，反而更混乱。更合理的拆法是按业务域与复用范围：

1. 基础层 HAR：日志、网络、存储、埋点等与业务无关的能力，变更频率低；
2. 公共 UI HAR：设计系统组件（按钮、卡片、空态页），被多个业务模块复用；
3. 业务 HAR：按域拆分，例如订单、消息、个人中心，各自独立演进；
4. 按需 HSP：体积较大的低频能力，例如离线地图、音视频编辑。

四、依赖方向要单向

模块化最容易失控的是依赖成环：A 依赖 B，B 又依赖 A，最终无法独立编译，也无法单独测试。约定一条规则：业务模块可以依赖基础层与公共 UI，业务模块之间不直接依赖，跨域通信通过路由或事件总线。

// 通过路由跳转，而不是直接 import 另一个业务模块的页面
router.pushUrl({ url: 'pages/OrderDetail' });

五、版本与发布

HAR/HSP 也有自己的版本号与依赖声明。内部模块建议使用固定版本而非范围版本，避免一次依赖升级导致所有模块行为变化。发布到私有仓库时，注意同步维护 CHANGELOG，记录破坏性变更。

六、拆分后的验证

模块拆分是否有效，不看目录树有多整齐，而看三个指标：

1. 单个模块能否独立编译通过；
2. 修改一个业务模块，是否需要同时改动其它业务模块；
3. 包体积与启动耗时是否因按需加载而下降。

如果拆分后第 2 条依然经常发生，说明边界划错了，应重新审视模块职责，而不是继续增加层级。

七、小结

HAP 负责交付形态，HAR 负责编译期复用，HSP 负责运行时共享。拆分时按变更原因划边界、保持依赖单向、用独立编译与改动范围来验证效果。模块化的目标不是“看起来专业”，而是让并行开发与长期维护变得可控。