适合谁看

• 已经会 Flutter，但刚开始接触 HarmonyOS 的开发者

• 不想只看最小 Demo，而是想尽快形成完整项目理解的人

• 想做鸿蒙迁移、比赛项目或技术连载，需要一个真实母项目的人

问题背景

很多 Flutter 开发者开始看鸿蒙时，最容易掉进两个极端：

• 要么只看最小样例，看完知道 API 怎么调，却还是不知道完整项目该怎么搭

• 要么一上来就啃复杂原生工程，结果文件很多、概念很多，很快失去上下文

这两条路都不算错，但都不够适合作为大多数 Flutter 开发者的“第一切入点”。

我更推荐的方式是：

先找一个业务完整、结构清晰、又确实接入了鸿蒙能力的真实项目，先把全局理解建立起来，再去拆具体 API。

对我来说，食界探味 就是这样一个很合适的切入样本。

为什么我不建议把最小 Demo 当成第一入口

最小 Demo 的价值当然存在，它适合回答的是：

• 某个能力能不能调起来

• 某个 API 需要哪些参数

• 某个权限应该怎么申请

但它回答不了另外一类更关键的问题：

• 真实项目里，Flutter 和鸿蒙原生到底怎么分工

• 哪些东西应该放 Flutter，哪些东西应该放 ArkTS

• 系统能力接进来之后，怎么和页面、路由、状态管理、AI 流程连起来

• 为什么这个能力值得接，而不是只是“能接”

对于大多数已经做过 Flutter App 的人来说，后面这一组问题反而更重要。

因为你真正要做的不是“跑一个鸿蒙能力样例”，而是“把鸿蒙能力放进一个能长期迭代的产品里”。

为什么真实项目是更好的切入方式

真实项目最大的价值，不是代码更多，而是上下文更完整。

以 食界探味 为例，它同时具备下面几层信息：

1. 有明确产品目标

它不是纯技术试验品，而是一个有清晰定位的产品：

以食材为入口，探索全球不同吃法的美食探索 App。

这意味着你看每一段技术实现时，都知道它最终服务的是什么体验。

2. 有完整工程结构

这个项目并不只有 App 本体，而是同时包含：

• app/：Flutter 主应用

• app/ohos/：HarmonyOS 壳工程

• server/：后端与内容工具

• docs/：产品、比赛、内容和策划文档

这类结构特别适合初学者，因为你会意识到：

Flutter + HarmonyOS 不是“给一个页面加个插件”这么简单，而是一个完整工程协作问题。

3. 有真实鸿蒙能力接入

这个项目当前已经接入或预留了多类 HarmonyOS 能力：

• 语音识别

• 文本转语音

• Intents Kit 页面跳转

• 防窥保护

• Form Kit 卡片能力

所以你看到的不只是 Flutter 页面，而是“Flutter 页面如何获得 HarmonyOS 的差异化价值”。

4. 有完整产品叙事

在 docs/competition/prd.md 里，这个项目被定义成：

基于 HarmonyOS AI 能力的全球饮食探索助手。

这句话非常重要。它告诉你：

• 为什么会接 Speech Kit

• 为什么会接 Intents Kit

• 为什么会做卡片

• 为什么 AI 助手会成为主入口

有了这个叙事之后，技术实现就不再是零散拼图，而是一条连续的产品链路。

那么，理解 Flutter + HarmonyOS 的正确顺序是什么

如果你也想通过一个真实项目来建立整体理解，我建议按下面这个顺序来。

第一步：先理解“它是个什么产品”

很多人一上来就想看插件、看原生、看配置，这其实太快了。

更好的第一步是先搞清楚：

• 这个项目面向谁

• 它解决什么问题

• 它的核心体验是什么

• 鸿蒙能力为什么会出现在这里

在 食界探味 里，答案其实很明确：

• 它不是菜谱教学 App

• 它更像一个“饮食灵感探索工具”

• 它想强调的是 AI 理解、系统触达和内容探索

这一步的意义在于，你后面看每个能力时，都会知道它为什么存在。

比如：

• 语音输入，不是为了演示语音识别，而是为了让用户自然说出“家里有鸡蛋和番茄”

• TTS，不是为了展示播报，而是为了让 AI 推荐结果可被“听”

• Intents Kit，不是为了注册个意图，而是为了让页面能被系统入口直达

第二步：再理解“谁是主业务层”

在 食界探味 里，主业务层很清楚，就是 Flutter。

从 app/lib/ 往下看，你会发现它承载的是项目真正的产品复杂度：

• 页面 UI

• 路由结构

• 状态管理

• 数据模型

• AI 助手交互

比如在 app/lib/app.dart 里，可以直接看到完整的路由组织：

• /explore

• /search

• /ai-assistant

• /wish-box

• /dish/:id

这类信息特别重要，因为它会帮助你建立一个判断：

在这个项目里，Flutter 不是外壳，而是主战场。

一旦这个判断建立起来，后面你就不会误以为“鸿蒙部分一定是最核心的”。

第三步：再去看鸿蒙工程承担什么职责

当你已经知道 Flutter 是主业务层之后，再去看 app/ohos/，思路就会清楚很多。

这时候你不会再把它当作第二个完整 App，而会把它理解成：

• 平台壳工程

• 系统入口承接层

• 原生能力调用层

在 app/ohos/entry/src/main/ets/ 下，当前项目大致分成三类内容：

1. plugins/

这里放的是 ArkTS 插件实现，例如：

• SpeechRecognitionPlugin.ets

• TextToSpeechPlugin.ets

• IntentNavigationPlugin.ets

• AntiPeepProtectionPlugin.ets

这一层的职责很明确：
把 HarmonyOS 的系统能力变成 Flutter 可以调用的能力接口。

2. entryability/

这里放的是系统入口相关逻辑，例如：

• EntryAbility.ets

• InsightIntentExecutorImpl.ets

这一层更像“系统和应用之间的接缝”，它决定了应用如何被鸿蒙生态理解和拉起。

3. formability/

这里放的是卡片能力，例如：

• DailyRecommendFormAbility.ets

• RecommendData.ets

它体现的不是普通页面逻辑，而是系统级触达能力。

看到这里，你会很自然地得出一个结论：

鸿蒙工程不是在和 Flutter 抢主导权，而是在补齐 Flutter 本身不直接覆盖的系统层能力。

第四步：重点看“Flutter 和 ArkTS 的边界”

这是理解真实项目最关键的一步。

如果你只看 Flutter，或者只看 ArkTS，都容易误判。真正有价值的是理解两者之间怎么协作。

在 食界探味 里，这个边界被收得很清楚，主要集中在 app/lib/core/platform/。

这里目前能看到几种典型桥接：

• speech_recognition_channel.dart

• text_to_speech_channel.dart

• intent_navigation_channel.dart

• anti_peep_protection_channel.dart

这几个文件的共同特点是：

• Flutter 侧接口都比较薄

• 不承载太多原生实现细节

• 重点是把“业务层需要什么能力”表达出来

比如语音识别这一组：

• Flutter 侧只负责发起 startListening 和 stopListening

• ArkTS 侧负责申请权限、创建引擎、监听回调和回传结果

这就是一种非常适合入门者学习的结构，因为它把复杂性分层得很清楚。

第五步：最后再回头看文档和策划材料

很多人会觉得文档是“最后再看”的东西，但对鸿蒙项目来说，文档反而很重要。

尤其是这个项目里的 docs/competition/prd.md，它不是附属资料，而是理解技术选型的关键背景。

在这份 PRD 里，你能看到项目为什么强调：

• AI 智能化体验

• 语音输入

• 图片输入

• 系统级入口触达

• HarmonyOS 能力融合

这会帮助你明白一件事：

项目接入鸿蒙能力，并不是因为“这些能力很酷”，而是因为产品目标本来就需要它们。

对于一个初学者来说，这种“先理解目标，再理解能力”的顺序，比死记 API 更有效。

用 食界探味 看 Flutter + HarmonyOS，到底能学到什么

如果你用这个项目来做切入点，我觉得至少能学到下面几件事。

1. 学会看分层

你会逐渐看明白：

• 哪些是 Flutter 业务层

• 哪些是鸿蒙系统层

• 哪些是平台边界层

这比单纯记住“某个 API 怎么调”更有长期价值。

2. 学会看能力为什么存在

在真实项目里，一个能力从来不是孤立存在的。

它一定要回答：

• 它服务什么场景

• 它改善什么体验

• 它为什么值得维护

食界探味 的好处就在于，这些问题都能落回具体产品语境里。

3. 学会看系统能力如何回到业务体验

这是很多 Demo 学不到的。

比如：

• 语音识别最终要回到输入框和推荐流里

• Intent 跳转最终要回到 Flutter 路由里

• 卡片最终要回到推荐内容和页面消费里

只有真实项目，才能把这些链路连起来。

4. 学会判断“什么时候该继续下钻”

通过一个完整项目入门之后，你才更容易知道下一步应该去哪深挖：

• 想学平台通道，就继续看 core/platform/ 和 plugins/

• 想学系统入口，就继续看 entryability/

• 想学卡片，就继续看 formability/

• 想学产品叙事，就继续看 PRD 和竞赛文档

这比一开始盲目搜零散教程要高效得多。

初学者最容易踩的几个坑

坑 1：只看最小 Demo，不看真实场景

结果就是你知道 API 名字，但不知道项目里应该放在哪里、为什么要放在那里。

坑 2：一上来就沉到原生层

对于 Flutter 开发者来说，先建立全局理解比先啃原生细节更重要。

坑 3：把 app/ohos 当成第二个完整产品

它更像系统层和入口层，而不是和 Flutter 平行的第二套业务系统。

坑 4：忽略策划文档

没有产品目标，你就会把所有能力都看成“技术点”；有了产品目标，你才知道哪些能力是核心，哪些只是装饰。

可复用的理解模板

以后你拿到任何一个 Flutter + HarmonyOS 项目，都可以先用这 5 个问题建立全局理解：

1. 这个项目首先是个什么产品

2. 它的主业务层放在哪里

3. 鸿蒙工程承担什么职责

4. Flutter 和 ArkTS 的边界怎么划

5. 系统能力为什么值得被接进来

只要这 5 个问题想清楚了，后面的学习速度会快很多。

本篇总结

理解 Flutter + HarmonyOS 的最好方式，不是从最小 API 样例开始，也不是从最复杂的原生工程开始，而是从一个“业务完整、结构清晰、能力真实、产品叙事成立”的项目开始。

食界探味 之所以适合作为切入点，恰恰是因为它同时具备：

• Flutter 主体业务层

• HarmonyOS 原生能力接入

• 系统入口与卡片能力

• AI 产品语境

• 文档与比赛表达

对于 Flutter 开发者来说，这种真实项目比孤立 Demo 更能帮助你快速建立正确的鸿蒙开发认知。