适合谁看正在做多端共存 Flutter 工程的人想把 HarmonyOS 加进现有 Flutter 项目的人担心平台目录越来越乱的人问题背景很多人做 Flutter 多端时最初的默认想法通常是业务层共用平台层尽量少看这个思路在 Android iOS 双端阶段通常还能撑住。但 HarmonyOS 加进来以后复杂度会变得更立体一些入口模型不同系统能力层不同构建与签名链路不同卡片和意图直达这类系统触达也会进来这时如果还沿用“先都塞进共享层平台差异以后再说”的思路项目很容易越做越乱。真正的问题不是三端能不能共存而是共享什么、隔离什么、谁负责承接平台现实。项目中的真实场景食界探味当前就是一个很典型的三端共存结构app/android/app/ios/app/ohos/app/lib/其中app/lib/继续承接 Flutter 主体业务app/ohos/独立承接 HarmonyOS 壳工程app/lib/core/platform/承接 Flutter 与平台层的边界如果再往细里看会更清楚Flutter 侧的平台边界文件在app/lib/core/platform/HarmonyOS 侧原生插件在app/ohos/entry/src/main/ets/plugins/HarmonyOS 侧入口承接在app/ohos/entry/src/main/ets/entryability/HarmonyOS 侧卡片能力在app/ohos/entry/src/main/ets/formability/这恰好说明三端共存最重要的不是“目录都留着”而是“共享和隔离的边界有没有先收清”。核心实现先说一个最实用的判断多端共存的关键从来不是“所有东西都共享”而是“共享业务语义隔离平台现实”。只要先记住这一句很多结构选择都会清楚很多。一、应该优先共享什么在食界探味这种 Flutter 主体项目里优先共享的部分通常包括页面路由状态管理数据模型仓储层业务流程这些内容主要集中在app/lib/features/app/lib/data/app/lib/core/它们的共同点是更接近产品体验更接近跨平台业务不依赖某一个平台独占的系统能力所以这些东西继续留在 Flutter 共享层是合理而且高性价比的。二、必须按平台隔离什么一旦进入下面这些内容就应该主动接受“它们不该强行共享”原生插件实现权限流程系统入口模型卡片与桌面触达平台构建和签名配置在食界探味里HarmonyOS 这部分复杂度就明显集中在app/ohos/app/ohos/build-profile.json5app/ohos/entry/src/main/module.json5app/ohos/entry/src/main/ets/plugins/app/ohos/entry/src/main/ets/entryability/app/ohos/entry/src/main/ets/formability/这说明 HarmonyOS 加进来以后平台隔离不只是“多一个目录”而是多了一整层系统承接结构。三、为什么app/lib/core/platform/在三端共存里特别关键如果只有 Android 和 iOS有些团队会把平台差异直接零散写进页面层。但三端共存以后这种方式会很快变得不可控。食界探味当前的结构给了一个更稳的方向平台能力先收进app/lib/core/platform/Flutter 页面层只调语义化方法各平台壳工程再各自实现自己的那一段系统现实当前已经能看到的边界文件包括anti_peep_protection_channel.dartintent_navigation_channel.dartspeech_recognition_channel.darttext_to_speech_channel.dart这样做的好处是页面层不直接碰平台差异HarmonyOS 的新复杂度不会直接冲进业务层后面 Android、iOS、HarmonyOS 可以各自扩展实现四、HarmonyOS 加进来后项目复杂度为什么会明显上一个台阶这不是因为 HarmonyOS “更难”而是因为它带来的差异更立体。以食界探味现在的鸿蒙壳工程为例至少已经能看到这些新增复杂度EntryAbility主入口InsightIntentExecutorImpl意图入口DailyRecommendFormAbility卡片入口语音、TTS、Intent、防窥这些原生插件module.json5和build-profile.json5这类鸿蒙配置层也就是说HarmonyOS 不是只多出一个“运行平台”而是多出了一层更强的系统入口和系统能力语境。这也是为什么三端共存时HarmonyOS 一进来就更需要主动管理平台边界。五、三端共存时新增一个鸿蒙能力应该改哪几层这是实际开发里最容易把工程做乱的地方。如果现在要在食界探味里新增一个 HarmonyOS 独占能力比如新的系统级入口或新的 Kit 能力我更建议按下面这个顺序落第一步先定义 Flutter 侧语义接口先在app/lib/core/platform/里定义清楚这个能力对 Flutter 页面来说叫什么它返回的是一次性结果还是持续事件失败时页面应该拿到什么语义第二步再决定 HarmonyOS 壳层谁来承接如果它是一次性能力调用通常落在plugins/系统入口能力通常会牵涉entryability/卡片或桌面触达能力通常会牵涉formability/这一步的意义是不要让所有鸿蒙能力都无差别堆进同一个原生文件。第三步最后再看 Android、iOS 是否需要跟进三端共存不等于三端必须同时做同一件事。有些能力只在鸿蒙上存在那就应该老老实实只在鸿蒙层实现并在 Flutter 边界层做好能力探测平台判断降级策略六、最稳的多端工程思路是什么如果压缩成一个最小实践可以先这样做共享层app/lib/这里放页面路由状态数据模型仓储与业务流程平台边界层app/lib/core/platform/这里放平台语义化调用入口结果和事件收口平台异常兜底平台实现层app/android/app/ios/app/ohos/这里放构建配置权限与系统入口原生插件和平台特定实现只要先按这三层收后面多端共存通常都会稳定很多。七、哪些迹象说明你的三端结构开始失控了如果项目里开始出现下面这些信号就说明平台边界可能已经在变形Flutter 页面里到处是平台判断分支一个新能力要同时改页面、业务、路由和多端原生代码却没有明确边界HarmonyOS 的入口和插件逻辑开始直接侵入共享业务层Android、iOS、HarmonyOS 的实现差异没有收口而是散落在很多 Dart 页面里这类问题早期看起来只是“有点乱”后面会直接影响维护成本新能力接入速度教程可读性回归排查效率关键代码位置app/lib/app/lib/core/platform/app/android/app/ios/app/ohos/app/ohos/entry/src/main/ets/plugins/app/ohos/entry/src/main/ets/entryability/app/ohos/entry/src/main/ets/formability/鸿蒙侧实现从鸿蒙侧看新增复杂度主要不在 Flutter 页面层而在壳工程和系统能力层EntryAbilityplugins/formability/module.json5build-profile.json5所以 HarmonyOS 不应该被看成“又一个外壳”而应该被看成“多端体系里独立的一层系统入口实现”。Flutter 侧实现从 Flutter 侧看最重要的目标不是把所有平台差异隐藏到看不见而是把它们控制在页面层外面。食界探味现在的做法更接近Flutter 承接共享业务平台边界层承接平台语义各平台壳工程承接系统现实这比“平台差异直接混进页面层”要稳得多。常见坑为了共用而硬把平台差异塞进 Dart 页面层HarmonyOS 接入后没有重新划清平台边界看到 Flutter 可跨平台就误以为平台入口和权限流程也应该完全共享三端共存时没有独立平台边界层最后页面到处都是条件分支新增一个鸿蒙能力时不先决定它落在plugins/、entryability/还是formability/可复用模板共享层app/lib/ 边界层app/lib/core/platform/ 平台层android/ ios/ ohos/共享的是 - 业务语义 - 页面体验 - 数据组织 隔离的是 - 系统入口 - 权限流程 - 原生能力 - 构建与签名本篇总结一个 Flutter 项目同时保留 Android、iOS、HarmonyOS 支持时最关键的不是“目录都还在”而是共享和隔离的边界是否足够清楚。食界探味当前的结构说明真正稳的做法不是强行统一所有实现而是共享业务层独立平台层中间再加一层稳定的平台边界层HarmonyOS 一旦进来这件事反而更重要而不是更可忽略。
一个 Flutter 项目同时保留 Android、iOS、HarmonyOS 支持的实践
适合谁看正在做多端共存 Flutter 工程的人想把 HarmonyOS 加进现有 Flutter 项目的人担心平台目录越来越乱的人问题背景很多人做 Flutter 多端时最初的默认想法通常是业务层共用平台层尽量少看这个思路在 Android iOS 双端阶段通常还能撑住。但 HarmonyOS 加进来以后复杂度会变得更立体一些入口模型不同系统能力层不同构建与签名链路不同卡片和意图直达这类系统触达也会进来这时如果还沿用“先都塞进共享层平台差异以后再说”的思路项目很容易越做越乱。真正的问题不是三端能不能共存而是共享什么、隔离什么、谁负责承接平台现实。项目中的真实场景食界探味当前就是一个很典型的三端共存结构app/android/app/ios/app/ohos/app/lib/其中app/lib/继续承接 Flutter 主体业务app/ohos/独立承接 HarmonyOS 壳工程app/lib/core/platform/承接 Flutter 与平台层的边界如果再往细里看会更清楚Flutter 侧的平台边界文件在app/lib/core/platform/HarmonyOS 侧原生插件在app/ohos/entry/src/main/ets/plugins/HarmonyOS 侧入口承接在app/ohos/entry/src/main/ets/entryability/HarmonyOS 侧卡片能力在app/ohos/entry/src/main/ets/formability/这恰好说明三端共存最重要的不是“目录都留着”而是“共享和隔离的边界有没有先收清”。核心实现先说一个最实用的判断多端共存的关键从来不是“所有东西都共享”而是“共享业务语义隔离平台现实”。只要先记住这一句很多结构选择都会清楚很多。一、应该优先共享什么在食界探味这种 Flutter 主体项目里优先共享的部分通常包括页面路由状态管理数据模型仓储层业务流程这些内容主要集中在app/lib/features/app/lib/data/app/lib/core/它们的共同点是更接近产品体验更接近跨平台业务不依赖某一个平台独占的系统能力所以这些东西继续留在 Flutter 共享层是合理而且高性价比的。二、必须按平台隔离什么一旦进入下面这些内容就应该主动接受“它们不该强行共享”原生插件实现权限流程系统入口模型卡片与桌面触达平台构建和签名配置在食界探味里HarmonyOS 这部分复杂度就明显集中在app/ohos/app/ohos/build-profile.json5app/ohos/entry/src/main/module.json5app/ohos/entry/src/main/ets/plugins/app/ohos/entry/src/main/ets/entryability/app/ohos/entry/src/main/ets/formability/这说明 HarmonyOS 加进来以后平台隔离不只是“多一个目录”而是多了一整层系统承接结构。三、为什么app/lib/core/platform/在三端共存里特别关键如果只有 Android 和 iOS有些团队会把平台差异直接零散写进页面层。但三端共存以后这种方式会很快变得不可控。食界探味当前的结构给了一个更稳的方向平台能力先收进app/lib/core/platform/Flutter 页面层只调语义化方法各平台壳工程再各自实现自己的那一段系统现实当前已经能看到的边界文件包括anti_peep_protection_channel.dartintent_navigation_channel.dartspeech_recognition_channel.darttext_to_speech_channel.dart这样做的好处是页面层不直接碰平台差异HarmonyOS 的新复杂度不会直接冲进业务层后面 Android、iOS、HarmonyOS 可以各自扩展实现四、HarmonyOS 加进来后项目复杂度为什么会明显上一个台阶这不是因为 HarmonyOS “更难”而是因为它带来的差异更立体。以食界探味现在的鸿蒙壳工程为例至少已经能看到这些新增复杂度EntryAbility主入口InsightIntentExecutorImpl意图入口DailyRecommendFormAbility卡片入口语音、TTS、Intent、防窥这些原生插件module.json5和build-profile.json5这类鸿蒙配置层也就是说HarmonyOS 不是只多出一个“运行平台”而是多出了一层更强的系统入口和系统能力语境。这也是为什么三端共存时HarmonyOS 一进来就更需要主动管理平台边界。五、三端共存时新增一个鸿蒙能力应该改哪几层这是实际开发里最容易把工程做乱的地方。如果现在要在食界探味里新增一个 HarmonyOS 独占能力比如新的系统级入口或新的 Kit 能力我更建议按下面这个顺序落第一步先定义 Flutter 侧语义接口先在app/lib/core/platform/里定义清楚这个能力对 Flutter 页面来说叫什么它返回的是一次性结果还是持续事件失败时页面应该拿到什么语义第二步再决定 HarmonyOS 壳层谁来承接如果它是一次性能力调用通常落在plugins/系统入口能力通常会牵涉entryability/卡片或桌面触达能力通常会牵涉formability/这一步的意义是不要让所有鸿蒙能力都无差别堆进同一个原生文件。第三步最后再看 Android、iOS 是否需要跟进三端共存不等于三端必须同时做同一件事。有些能力只在鸿蒙上存在那就应该老老实实只在鸿蒙层实现并在 Flutter 边界层做好能力探测平台判断降级策略六、最稳的多端工程思路是什么如果压缩成一个最小实践可以先这样做共享层app/lib/这里放页面路由状态数据模型仓储与业务流程平台边界层app/lib/core/platform/这里放平台语义化调用入口结果和事件收口平台异常兜底平台实现层app/android/app/ios/app/ohos/这里放构建配置权限与系统入口原生插件和平台特定实现只要先按这三层收后面多端共存通常都会稳定很多。七、哪些迹象说明你的三端结构开始失控了如果项目里开始出现下面这些信号就说明平台边界可能已经在变形Flutter 页面里到处是平台判断分支一个新能力要同时改页面、业务、路由和多端原生代码却没有明确边界HarmonyOS 的入口和插件逻辑开始直接侵入共享业务层Android、iOS、HarmonyOS 的实现差异没有收口而是散落在很多 Dart 页面里这类问题早期看起来只是“有点乱”后面会直接影响维护成本新能力接入速度教程可读性回归排查效率关键代码位置app/lib/app/lib/core/platform/app/android/app/ios/app/ohos/app/ohos/entry/src/main/ets/plugins/app/ohos/entry/src/main/ets/entryability/app/ohos/entry/src/main/ets/formability/鸿蒙侧实现从鸿蒙侧看新增复杂度主要不在 Flutter 页面层而在壳工程和系统能力层EntryAbilityplugins/formability/module.json5build-profile.json5所以 HarmonyOS 不应该被看成“又一个外壳”而应该被看成“多端体系里独立的一层系统入口实现”。Flutter 侧实现从 Flutter 侧看最重要的目标不是把所有平台差异隐藏到看不见而是把它们控制在页面层外面。食界探味现在的做法更接近Flutter 承接共享业务平台边界层承接平台语义各平台壳工程承接系统现实这比“平台差异直接混进页面层”要稳得多。常见坑为了共用而硬把平台差异塞进 Dart 页面层HarmonyOS 接入后没有重新划清平台边界看到 Flutter 可跨平台就误以为平台入口和权限流程也应该完全共享三端共存时没有独立平台边界层最后页面到处都是条件分支新增一个鸿蒙能力时不先决定它落在plugins/、entryability/还是formability/可复用模板共享层app/lib/ 边界层app/lib/core/platform/ 平台层android/ ios/ ohos/共享的是 - 业务语义 - 页面体验 - 数据组织 隔离的是 - 系统入口 - 权限流程 - 原生能力 - 构建与签名本篇总结一个 Flutter 项目同时保留 Android、iOS、HarmonyOS 支持时最关键的不是“目录都还在”而是共享和隔离的边界是否足够清楚。食界探味当前的结构说明真正稳的做法不是强行统一所有实现而是共享业务层独立平台层中间再加一层稳定的平台边界层HarmonyOS 一旦进来这件事反而更重要而不是更可忽略。
