HarmonyOS 项目中如何拆分共用层与形态模型

大家好，我是子玥酱，一名长期深耕在一线的前端程序媛 👩‍💻。曾就职于多家知名互联网大厂，目前在某国企负责前端软件研发相关工作，主要聚焦于业务型系统的工程化建设与长期维护。

我持续输出和沉淀前端领域的实战经验，日常关注并分享的技术方向包括前端工程化、小程序、React / RN、Flutter、跨端方案，
在复杂业务落地、组件抽象、性能优化以及多端协作方面积累了大量真实项目经验。

技术方向：前端 / 跨端 / 小程序 / 移动端工程化
内容平台：掘金、知乎、CSDN、简书
创作特点：实战导向、源码拆解、少空谈多落地
文章状态：长期稳定更新，大量原创输出

我的内容主要围绕前端技术实战、真实业务踩坑总结、框架与方案选型思考、行业趋势解读展开。文章不会停留在“API 怎么用”，而是更关注为什么这么设计、在什么场景下容易踩坑、真实项目中如何取舍，希望能帮你在实际工作中少走弯路。

子玥酱 · 前端成长记录官 ✨
👋 如果你正在做前端，或准备长期走前端这条路
📚 关注我，第一时间获取前端行业趋势与实践总结
🎁 可领取11 类前端进阶学习资源（工程化 / 框架 / 跨端 / 面试 / 架构）
💡 一起把技术学“明白”，也用“到位”

持续写作，持续进阶。
愿我们都能在代码和生活里，走得更稳一点 🌱

引言

HarmonyOS 项目中，为什么要拆「共用层」和「形态模型」

在 HarmonyOS 项目里，真正能复用的东西，其实非常有限。

如果你把一个项目跑在：

• 手机
• 平板
• PC
• 甚至游戏窗口 / 多实例

你会发现一个很残酷的现实：

逻辑看起来一样，但模型几乎一定不一样。

所以在 HarmonyOS 中，正确的拆法不是：

「这段代码能不能复用？」

而是先想清楚：

哪些东西“不该知道设备形态”？
哪些东西“必须知道自己跑在哪”？

这就是共用层和形态模型的边界。

一、什么是真正的「共用能力层」

共用能力层只有一个标准：

它不应该关心：

• 屏幕大小
• 窗口是否可缩放
• 是否支持多文档
• 是否存在鼠标 / 键盘
• 是否允许后台常驻

典型可以下沉为共用层的内容

这几类，在 HarmonyOS 上几乎永远成立：

• 网络请求（API / GraphQL / WebSocket）
• 数据持久化（KV / RDB / 文件 IO）
• 业务计算规则
• 状态派生逻辑（非 UI）
• 跨设备同步协议
• 权限与能力判断封装

共用层的一个重要原则

共用层只输出“能力”，不输出“行为”。

举个例子

错误的共用层设计：

// 不该出现在共用层exportfunctionopenDocument(id:string){Router.pushUrl({url:'pages/editor',params:{id}})}

正确的共用层设计：

// common/document/DocumentRepository.tsexportclassDocumentRepository{asyncload(id:string):Promise<Document>{// 只负责数据}asyncsave(doc:Document){// 只负责持久化}}

“怎么打开、在哪打开、能不能多开”——一律不在共用层出现。

二、什么是「形态专属模型层」

这是很多 HarmonyOS 项目最容易偷懒、但后期最痛的地方。

形态模型层解决的不是 UI，而是：

“这个形态下，业务是怎么运转的”

不同形态，模型关注点完全不同

手机 App 模型关心什么？

• 单页面 / 栈式导航
• 页面切换即上下文切换
• 生命周期频繁
• 强依赖前后台状态

PC 模型关心什么？

• 多窗口 / 多文档并行
• 文档是否脏（dirty）
• 是否允许并排视图
• 窗口最小化 ≠ 生命周期结束

游戏 / 强交互形态关心什么？

• 帧循环
• 输入源多样化
• 状态常驻
• UI 与逻辑高度解耦

你可以共用数据层，但你不可能共用模型层。

三、一个推荐的拆分结构（真实可用）

下面是我在 HarmonyOS PC 项目里比较稳定的一套结构：

src/ ├── common/ │ ├── network/ │ ├── storage/ │ ├── domain/ │ │ ├── Document.ts │ │ └── User.ts │ └── service/ │ ├── app/ │ ├── model/ │ │ └── AppSessionModel.ts │ └── ui/ │ ├── pc/ │ ├── model/ │ │ ├── WorkspaceModel.ts │ │ └── DocumentWindowModel.ts │ └── ui/ │ └── game/ ├── model/ └── runtime/

关键点在于：

• common永远不 import app / pc
• pc/model可以组合common
• 模型之间允许策略不同，不强求一致

四、PC 形态下，一个“必须独立”的模型例子

PC 文档模型的核心，不是内容，而是「状态」

// pc/model/DocumentWindowModel.tsexportclassDocumentWindowModel{constructor(privaterepo:DocumentRepository){}document:Document|null=nullisDirty:boolean=falseisActive:boolean=falseasyncopen(id:string){this.document=awaitthis.repo.load(id)this.isDirty=false}updateContent(content:string){if(!this.document)returnthis.document.content=contentthis.isDirty=true}asyncsaveIfNeeded(){if(this.document&&this.isDirty){awaitthis.repo.save(this.document)this.isDirty=false}}}

如果你把这个模型强行塞进手机 App：

• 页面切换时你会丢状态
• 多文档会变成噩梦
• 后台恢复逻辑会失控

不是代码写得不好，是模型选错了形态。

五、一个判断标准：这段逻辑该放哪？

我给你一个非常好用的判断表：

六、总结

HarmonyOS 的“统一”，是能力层的统一，不是模型的统一。