01-three-layer-architecture

01 --- HarmonyOS 多设备短视频应用的三层架构设计与实践

一、引言

在多设备应用开发中，如何高效组织代码、实现业务复用是核心挑战。本系列基于多设备短视频（Multi-Short-Video）项目，该系统覆盖手表、直板机、折叠屏、平板、电脑和智慧屏六种设备形态，采用 HarmonyOS 三层架构进行代码组织。

二、三层架构概览

项目采用 products → features → common 的依赖关系，自顶向下引用：

复制代码

┌──────────────────────────────────────────────────┐
│ products 层（产品定制层）                          │
│ default(手机/平板) │ pc(电脑) │ tv(智慧屏) │ wearable(手表) │
├──────────────────────────────────────────────────┤
│ features 层（基础特性层）                          │
│ multishortvideoadaptivevideo(视频播放)            │
│ multishortvideocomment(评论区)                    │
│ multishortvideoindividual(个人作品页)              │
├──────────────────────────────────────────────────┤
│ common 层（公共能力层）                            │
│ multishortvideobase(公共组件/常量/工具类/数据模型)  │
└──────────────────────────────────────────────────┘

2.1 common 层 --- 公共能力层

定义在 common/multishortvideobase 模块中，提供：

公共组件 ：MSVTabs、MSVTextIcon、MSVEmptyComponent
常量定义 ：CommonConstants（AVPlayer 状态常量、百分比常量等）
数据模型 ：MSVDataModel（Tabs 数据模型）
工具类 ：WindowUtil（窗口管理）、Logger（日志）、WidthBreakpointType（断点工具）、AdaptiveImmersion（沉浸式算法）

2.2 features 层 --- 基础特性层

三个独立业务模块，被 products 层统一调用：

模块	功能	关键文件
`multishortvideoadaptivevideo`	视频播放	`AdaptiveAVPlayer.ets`, `AdaptiveVideo.ets`
`multishortvideocomment`	评论区	`Comment.ets`, `CommentViewModel.ets`
`multishortvideoindividual`	个人作品页	`Individual.ets`, `Works.ets`, `IndividualByRouter.ets`

2.3 products 层 --- 产品定制层

四个 HAP 包作为独立入口，各自处理设备特有的 UI 差异：

HAP	设备	入口文件	导航模式
`default`	手机、平板	`products/default/.../Index.ets`	MSVTabs + Navigation
`pc`	电脑	`products/pc/.../Index.ets`	SideBarContainer
`tv`	智慧屏	`products/tv/.../Index.ets`	TVTabs + Navigation
`wearable`	手表	`products/wearable/.../Index.ets`	MSVTabs（精简版）

三、模块依赖配置

在 build-profile.json5 中定义 8 个模块，通过 srcPath 映射到各层目录：

json5 复制代码

{
  modules: [
    { name: "multishortvideodefaultsample", srcPath: "./products/default" },
    { name: "multishortvideopcsample",      srcPath: "./products/pc" },
    { name: "multishortvideotvsample",      srcPath: "./products/tv" },
    { name: "multishortvideowearablesample", srcPath: "./products/wearable" },
    { name: "multishortvideobase",           srcPath: "./common/multishortvideobase" },
    { name: "multishortvideoadaptivevideo",  srcPath: "./features/multishortvideoadaptivevideo" },
    { name: "multishortvideoindividual",     srcPath: "./features/multishortvideoindividual" },
    { name: "multishortvideocomment",        srcPath: "./features/multishortvideocomment" },
  ]
}

各模块的 oh-package.json5 中声明依赖，如 features 层依赖 common 层，products 层依赖 features 层。

四、最佳实践总结

按层次拆分模块：common 层放通用工具，features 层放业务逻辑，products 层放设备差异化代码
单向依赖：products → features → common，禁止反向依赖
模块粒度控制：每个 HAP 包独立编译，避免不必要的依赖膨胀
统一数据模型：公共数据模型集中在 common 层，避免跨模块重复定义