在 HarmonyOS（尤其是 HarmonyOS NEXT）应用开发中，“共用层”与“形态模型” 是实现“一次开发，多端部署”（一多能力）的关键工程实践。
官方和社区（包括华为开发者社区、CSDN、掘金等）普遍推荐采用 三层工程架构 来清晰拆分代码，使核心业务逻辑最大化复用，同时针对不同设备形态（手机、平板、折叠屏、PC、大屏、手表等）进行差异化适配。
下面是目前最主流、最推荐的拆分方式和实践指南。
三层工程架构（官方推荐 & 社区共识）
HarmonyOS 应用工程通常拆分成以下三层模块，从底层到上层依赖关系严格单向：
- 共用层 / 公共能力层（Common / Shared）
- 定位：存放与设备形态完全无关的核心能力、业务无关的基础设施
- 典型内容：
- 网络请求框架（HttpClient、Retrofit 风格封装）
- 数据管理（数据库、KV存储、数据模型、Repository）
- 工具类（日期、字符串、加密、日志、权限工具）
- 通用组件（自定义控件、弹窗基类、Loading 状态管理）
- 状态管理（全局 Store、事件总线）
- 业务无关的常量、枚举、接口定义
- 第三方库的二次封装（如果需要统一处理）
- 依赖关系：无上层依赖，只被其他层依赖
- 模块类型：通常是 Library 或 Shared 类型的 HAP / HSP
- 关键原则：“零形态感知” — 不能出现任何与屏幕尺寸、折叠、分屏、多窗口相关的代码
- 特性层 / 基础特性层（Feature / Business）
- 定位：存放可复用的业务能力，实现核心功能逻辑，但尽量保持形态中立或弱形态感知
- 典型内容：
- 页面/组件的业务逻辑（ViewModel、Controller）
- 数据转换、业务规则、UseCase
- 特定功能的完整模块（如登录、搜索、详情、列表、支付流程）
- 可复用的 UI 组件组合（但不涉及具体布局）
- 依赖关系：依赖共用层，可被产品层（不同形态）依赖
- 模块类型：通常是 Feature 类型的 HAP
- 关键原则：高内聚、低耦合，尽量让业务逻辑不关心设备形态，只关心“做什么”
- 产品定制层 / 形态适配层（Product / Entry / Shape）
- 定位：针对具体设备形态做差异化适配、UI 布局、交互、资源
- 典型内容：
- 不同形态的入口模块（Entry 类型 HAP）
- 响应式布局（Column、Row、Grid、媒体查询、断点布局）
- 形态专属组件（分屏布局、多窗口、折叠屏适配、大屏导航）
- 设备专属资源（drawable-480dpi、drawable-600dpi、布局变体）
- 交互适配（手势、键盘、遥控器、触控笔）
- 窗口模式（全屏、分屏、悬浮、自由窗）
- 依赖关系：依赖共用层 + 特性层，不被其他层依赖
- 模块类型：通常是多个 Entry 或 Feature 模块，按形态拆分（如 phone、tablet、pc、foldable、watch）
- 关键原则：形态差异化隔离 — 只在这里写“怎么在当前设备上呈现和交互”
典型工程目录结构示例（HarmonyOS NEXT / Stage 模型）
MyApp (工程根目录)
├── common (共用层 - Library / Shared)
│ ├── src/main/ets
│ │ ├── network/ # 网络层
│ │ ├── repository/ # 数据仓库
│ │ ├── model/ # 数据模型
│ │ ├── utils/ # 工具类
│ │ └── components/ # 通用组件（不含布局）
│ └── ohos.build-profile.json5
├── features (特性层 - 多个 Feature 模块)
│ ├── feature-login/
│ ├── feature-home/
│ ├── feature-detail/
│ └── ... (按业务域拆分)
├── products (产品/形态层 - 多个 Entry)
│ ├── entry-phone/ # 手机形态入口
│ ├── entry-tablet/ # 平板形态
│ ├── entry-foldable/ # 折叠屏
│ ├── entry-pc/ # PC 大屏
│ └── entry-watch/ # 手表（如果支持）
└── build-profile.json5 # 整体构建配置关键实践建议（避免常见坑）
- 共用层最严格的边界
- 绝对不能出现
window、display、breakpoint、foldState等形态相关 API - 不能 import 任何 UI 布局相关的类（Column、Row、Grid 等除非是纯逻辑组件）
- 推荐：共用层只提供接口 + 数据模型 + 纯逻辑实现
- 形态层如何适配
- 使用 响应式布局：
@ohos.display、media query、breakpoint、relativeContainer - 使用 多窗口 API：
windowManager、systemBar、freeform等 - 资源限定符：
resources/rawfile/phone/、resources/rawfile/tablet/等 - 不同形态的路由表、导航栏、Tab 栏在这里定制
- 依赖管理
- common → features → products（单向依赖）
- 禁止反向依赖、循环依赖
- 使用 HSP（静态共享包）或 HAR（Harmony Archive）共享 common 层
- 构建与打包
- 在
build-profile.json5中配置多 Entry - 可以为不同形态生成不同 HAP（手机 HAP、平板 HAP）
- 支持 按需部署（一个工程打多个形态的 App Pack，上架后云端分发）
官方 & 社区参考
- 华为开发者联盟：一次开发，多端部署 文档中多次提到“三层工程架构”
- 社区最佳实践（CSDN、掘金、知乎）：绝大多数高赞文章都推荐 Common → Feature → Product 三层拆分
- 典型案例：华为自研应用（如“玩机技巧”）就是采用这种分层，代码复用率提升 40% 左右
总结一句话：
共用层 解决“能做什么”（业务能力、数据、工具），形态模型 解决“在当前设备上怎么呈现和交互”（布局、导航、窗口、资源）。
通过三层拆分，你可以最大化复用核心代码，同时保持不同形态的灵活性和可维护性。
如果你有具体的业务模块或某个形态的适配痛点（比如折叠屏分屏、PC 多窗口、Watch 圆形屏），可以告诉我，我可以给出更细的拆分示例或代码结构建议。
