把 Android / iOS / 鸿蒙（HarmonyOS） 之间的工程迁移交给「大模型 + 工具」时，真正决定上限的往往不是单次对话写得多漂亮，而是：上下文从哪来、结果怎么验、每一轮提交怎么收口。本文从实践角度串一条链路：用 MCP 把仓库与外部能力接到 Agent 上，再用 Skill 把「怎么评转换质量、怎么总结变更、怎么对照需求、怎么看代码质量」固化成可重复执行的检查步骤。

说明：下文中的「转换」泛指在统一业务语义下，把一侧平台的实现（Kotlin/Swift/ArkTS 等）迁到另一侧或生成可对照骨架；不是宣称存在某种全自动、零成本的万能翻译器。MCP 与 Skill 解决的是流程与门禁，不是替代架构决策与人工验收。

1. 问题长什么样

典型诉求可以概括成四类：

纯靠聊天窗口贴代码，很快会遇到：上下文截断、无法读全仓库、无法跑构建与静态检查、无法稳定对比两次提交的差异。这就是 MCP 要接进来的原因。

2. MCP 在这条链路里干什么

MCP（Model Context Protocol） 做的是：让模型通过标准协议调用「工具」和拉取「资源」，而不是把整台电脑或整库文件糊进提示词。

在跨端迁移/转换场景里，常见有价值的 MCP 能力包括（按优先级大致排序）：

1. 代码与版本：读文件、搜索符号、git diff / git log、关联 issue / 需求文档（若你们有对应 MCP 或 HTTP 封装）。
2. 构建与检查：触发 Gradle / xcodebuild / hvigor（鸿蒙）的非交互命令，采集编译错误与警告（需沙箱与安全策略）。
3. 静态分析：对接 linter、格式化结果、甚至你们内部的二进制接口规范检查脚本。
4. 知识库：设计文档、接口契约、历史 CR 结论——用 resource 或检索类工具喂给模型当约束，而不是当闲聊材料。

一张很粗的协作关系如下：

flowchart LR
  subgraph agent["Agent（IDE / CLI）"]
    A[对话与计划]
  end
  subgraph mcp["MCP 服务"]
    G[Git / 文件]
    B[构建与日志]
    L[Lint / 测试]
    D[需求与文档]
  end
  subgraph repo["工程仓库"]
    R[Android / iOS / Harmony 模块]
  end
  A --> G
  A --> B
  A --> L
  A --> D
  G --> R
  B --> R
  L --> R

要点：MCP 负责「能持续拿到真实状态」；模型负责在约束下改代码。没有 MCP，跨端转换很容易变成「语法像、跑不通」的演示。

项目实践里 MCP 真正帮上忙的一块

在自己项目里跑下来，MCP 带来的提效很实在的一点，是支撑 大块功能在端之间的直接互转：网络、状态、一条完整业务链路里的多个类/模块，在接好仓库与构建/日志之后，Agent 能按「功能点」连续改，而不是只在聊天里贴片段。这和「整仓库一键翻译」不是一回事，但已经能覆盖不少成块迁移的工作。

转换落地之后，仍然需要人按需求自己多走几遍：主路径、边界条件、各端差异（权限、后台、埋点）往往要手动点一点才暴露。这里不必讳言——人工走查仍是验收的一环。差别在于：一旦发现问题，把报错、堆栈、复现步骤丢回给 AI，在 MCP 能读到工程上下文的前提下，修一轮的成本明显低于从零手改。整体仍是：大功能先转过去 → 人按需求验收 → 卡点再交给 AI 迭代，提效很多，但预期是「加速器」，不是「免验收」。

3. 转换工作流建议（可落地的一版）

下面是一条在团队里较容易推广的最小闭环，可按你们 CI 成熟度裁剪。

flowchart TB
  Q[对齐需求与范围] --> S[建立对照表：模块/接口/平台差异]
  S --> T[分支策略：按端或按业务垂直切]
  T --> C[大功能点互转 + 本地构建]
  C --> H[人按需求走查多遍]
  H -->|发现问题| F[把现象与日志交给 AI 修复]
  F --> C
  H -->|通过| V[门禁：Skill 清单跑一遍]
  V -->|不通过| C
  V -->|通过| P[PR：说明对照与风险]

1. 对齐需求与范围：哪些类/模块要迁、哪些只做适配层、哪些必须行为一致（加密、存储、埋点）。
2. 对照表：把「Android 类 / iOS 类型 / ArkTS 组件」映射到同一张表，避免三端各写各的命名与语义漂移。
3. 分支：要么「一需求一分支三端子目录」，要么「按端拆分支但共享契约文档」——关键是 diff 可读、review 可追责。
4. 大功能点转换 + 构建优先：先争取「能编过、主链路能跑」；报错与日志进 Agent 上下文（MCP），便于迭代大块改动而不是零散粘贴。
5. 人工按需求走查：对照验收条目多点几遍；出问题再 提醒 AI 修（复现步骤 + 日志/截图），形成短闭环，而不是指望一次生成就结项。
6. 门禁再走 PR：下文 Skill 部分把这一步拆成可执行检查项。

4. 用 Skill 做「质量门禁」：评什么、怎么评

Skill 在这里不是替你做代码审查的人，而是把「每次该怎么审」写成稳定流程，让 Agent 和人类用同一套清单。可以与 .cursor/rules 分工：规则偏常驻约束，Skill 偏「进入迁移任务时按需加载」。

下面四类，对应你提到的诉求。

4.1 评估「转换质量」（对照与语义）

建议在 Skill 里写清输入与输出：

• 输入：源端关键文件路径、目标端对应路径、需求编号或用户故事摘要。
• 输出：一张结构化表，至少包含：
  • API / 行为对照：异步模型（Kotlin 协程 vs Swift async vs Promise）、主线程约束、错误类型是否可对应。
  • 平台差异显式声明：例如 Keychain vs Keystore vs 鸿蒙安全存储、推送与后台任务差异。
  • 已知妥协：哪些为赶进度采用临时方案，必须带 TODO(@owner, deadline)。

转换质量不是「看起来像」，而是「在约束下可维护且可验证」。

4.2 总结「每次提交的变更内容」

与其让模型自由发挥写 PR 描述，不如在 Skill 里规定：

• 固定调用 git diff / git show（通过 MCP）得到事实；
• 再按模板归纳：文件级摘要 → 行为变化 → 风险点 → 测试建议；
• 禁止把「推测的业务意图」写进摘要当事实（除非文档里有依据）。

这样每一轮提交都有可比对、可审计的变更说明，也方便后面做需求完成度对照。

4.3 评估「需求完成度」

把需求拆成可勾选条目（验收标准），在 Skill 中要求：

• 每条对应 commit 或 PR 中的证据（实现位置、测试用例、或文档更新）；
• 未完成项必须标 阻塞原因（依赖、接口未就绪、平台能力缺失）。

没有结构化条目，「差不多做完了」无法复盘。

4.4 评估「提交代码的质量」

建议在 Skill 里分三层，由浅入深：

静态检查能覆盖机械层与部分工程层；语义层需要测试或人工 spot check。Skill 里应写明：哪些必须跑命令、哪些允许仅人工。

5. 示例：Skill 里可以长什么样（片段）

下面是一段示意性的 Markdown 结构，便于你落到仓库里的 SKILL.md（真实项目请补全 name、description 与触发条件）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

---
name: cross-platform-migration-review
description: Android/iOS/鸿蒙互迁时的对照审查与提交摘要
---

## 何时使用
用户提到跨端迁移、对照实现、ArkTS/Kotlin/Swift 同步修改时加载本 Skill。

## 步骤
1. 用 MCP 读取当前分支相对 main 的 diff 与最近 N 次提交信息。
2. 对照 `docs/platform-mapping.md`（若存在）检查涉及模块是否登记。
3. 按「转换质量 / 变更摘要 / 需求条目 / 代码质量」四节输出，缺信息则列出待补充问题。
4. 若涉及鸿蒙，显式检查线程与权限相关 API 是否与文档一致。

## 输出模板（节选）
### 变更摘要（基于 diff）
- 范围：...
- 行为变化：...
- 风险：...

### 需求完成度
| 条目 | 状态 | 证据 |

实际仓库里你会把路径、分支名、文档名换成自己的约定。

6. 局限与诚实边界

• MCP 不是魔法：没有构建环境、没有测试、没有清晰需求，再好的协议也只能产出「更像代码的文本」。
• 三端互转在工程上常卡在 能力不对等（系统服务、商店政策、声明式 UI 数据流），Skill 应要求把这些写进「已知妥协」，而不是一笔带过。
• 安全：能执行命令的 MCP 必须限权、审计；不要把生产密钥放进可被模型读取的资源。

7. 小结

• MCP 解决的是：让 Agent 稳定读仓库、跑检查、对齐事实，跨端转换才有可持续的闭环。
• Skill 解决的是：把 转换质量、变更摘要、需求完成度、代码质量 变成可重复执行的评审步骤，减少「同一类问题每次重新口头讲一遍」。

若你已经在用 Cursor / Claude Code 一类工具，优先落地的往往是：一个最小 MCP 集合（git + 终端或 CI 日志）+ 一个迁移审查 Skill；再逐步把需求条目与对照表接进来。和自己在项目里的做法一样：大功能点先互转、人按需求走查、问题再丢给 AI，比一上来追求「全自动三端零走查」更实在，也更容易稳定提效。

本文为工程流程向说明，具体工具链与 MCP Server 名称以各厂商文档为准；实施时请结合团队安全与合规要求。

由浅入深，从基本概念到源码原理，再到实战示例与生产级应用案例，系统梳理 Kotlin 跨平台开发之道

一、基础概念

1.1 什么是 Kotlin Multiplatform（KMP）？

Kotlin Multiplatform（又称 KMP 或 KMM）是 JetBrains 推出的跨平台代码共享方案，其核心理念是：共享业务逻辑，保留原生 UI。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

┌─────────────────────────────────────────────────────────────────────────┐
│                      KMP 架构：共享逻辑，原生 UI                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                  │
│   │   Android   │    │    iOS      │    │    Web      │                  │
│   │  (Kotlin)   │    │   (Swift)   │    │ (JS/WasM)   │                  │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘                  │
│          │                  │                  │                          │
│          │   原生 UI 层     │                  │                          │
│          ▼                  ▼                  ▼                          │
│   ┌──────────────────────────────────────────────────────────────┐      │
│   │              共享模块 (shared / commonMain)                    │      │
│   │    业务逻辑 · 网络请求 · 数据模型 · 存储 · ViewModel            │      │
│   └──────────────────────────────────────────────────────────────┘      │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

与 Flutter、React Native 等「一套 UI 到处跑」的方案不同，KMP 让你：

• 用 Kotlin 写共享的业务逻辑、网络、数据层
• 用 Jetpack Compose 写 Android UI，用 SwiftUI 写 iOS UI
• 得到的是 原生体验，而非 WebView 或自绘引擎

1.2 为什么需要 KMP？

1.3 KMP 与主流跨平台方案对比

适用场景：KMP 更适合「业务逻辑复杂、希望 UI 保持原生」的应用，如金融、电商、工具类 App。

二、核心原理

2.1 编译模型

KMP 将 Kotlin 代码编译成各平台的原生产物，而不是通过虚拟机或解释器运行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

                    ┌──────────────────┐
                    │  commonMain      │
                    │  (共享 Kotlin)   │
                    └────────┬─────────┘
                             │
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│  JVM / Android │  │  Kotlin/Native │  │  Kotlin/JS     │
│  (.class/DEX)  │  │  (LLVM → .a)   │  │  (JS/Wasm)     │
└────────────────┘  └────────────────┘  └────────────────┘
         │                   │                   │
         ▼                   ▼                   ▼
    Android APK         iOS Framework       Web Bundle

• Android：Kotlin → JVM 字节码 → DEX → APK
• iOS：Kotlin → Kotlin/Native（LLVM）→ 静态库/框架
• Web：Kotlin → JavaScript 或 WebAssembly

因此，共享代码在运行时就是本地代码，无额外解释层。

2.2 expect / actual 机制

当共享代码需要调用平台特有 API 时（如文件系统、UUID、日期格式化），KMP 使用 expect / actual 做编译期抽象：

在 commonMain 中声明 expect（契约）：

1
2
3
4
5

// commonMain/kotlin/platform/Platform.kt
package platform

expect fun currentTimeMillis(): Long
expect fun randomUUID(): String

在各平台提供 actual 实现：

1
2
3
4
5
6
7

// androidMain/kotlin/platform/Platform.android.kt
package platform

import java.util.UUID

actual fun currentTimeMillis(): Long = System.currentTimeMillis()
actual fun randomUUID(): String = UUID.randomUUID().toString()

1
2
3
4
5
6
7
8

// iosMain/kotlin/platform/Platform.ios.kt
package platform

import platform.Foundation.NSDate
import platform.Foundation.NSUUID

actual fun currentTimeMillis(): Long = (NSDate().timeIntervalSince1970 * 1000).toLong()
actual fun randomUUID(): String = NSUUID().UUIDString()

原理要点：

• 编译时，编译器将 expect 与对应平台的 actual 匹配
• 每个目标平台都必须有且仅有一个 actual 实现
• 保证 common 代码只能依赖抽象，无法引用平台专属 API

2.3 Source Sets（源集）与层级结构

KMP 用 Source Set 组织代码，每个源集对应一组目标平台：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

┌─────────────────────────────────────────────────────────────────┐
│                        Source Sets 层级                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   commonMain  ◄── 编译到所有目标，只可写平台无关代码               │
│        │                                                         │
│        ├── androidMain  ◄── 仅 Android                            │
│        │                                                         │
│        ├── iosMain (中间源集) ◄── 所有 iOS 目标共享                │
│        │       ├── iosArm64Main   (真机)                          │
│        │       └── iosSimulatorArm64Main (模拟器)                 │
│        │                                                         │
│        └── appleMain (中间源集) ◄── iOS + macOS + watchOS + tvOS  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

依赖方向：androidMain → commonMain，iosMain → commonMain，commonMain 不能依赖平台源集。

典型目录结构：

1
2
3
4
5
6
7
8
9
10
11
12

shared/
├── src/
│   ├── commonMain/
│   │   └── kotlin/
│   │       ├── domain/
│   │       ├── data/
│   │       └── di/
│   ├── androidMain/
│   │   └── kotlin/
│   └── iosMain/
│       └── kotlin/
└── build.gradle.kts

三、源码与实现原理

3.1 expect / actual 的编译期处理

expect/actual 并非运行时多态，而是编译期替换：

1. 在 common 编译时，expect 仅作为「占位声明」参与类型检查
2. 在平台编译时，编译器用对应平台的 actual 替换 expect
3. 最终产物中只存在 actual 实现，无额外抽象开销

这保证了共享代码在目标平台上等价于「直接调用平台 API」。

3.2 中间源集（Hierarchical Source Sets）

当多个平台共享同一套「非 common」逻辑时，可引入中间源集，避免重复：

1
2
3
4
5
6
7

// 声明目标
kotlin {
    android()
    iosArm64()
    iosSimulatorArm64()
    macosArm64()
}

Kotlin 插件会自动生成：

• appleMain：所有 Apple 平台共享（iOS + macOS + watchOS + tvOS）
• iosMain：iOS 真机 + 模拟器共享

在 appleMain 中可以使用 Apple 专属 API（如 platform.Foundation.NSUUID），而无需在 iosArm64Main、iosSimulatorArm64Main 里各写一遍。

3.3 依赖解析规则

1
2
3
4
5
6
7
8
9
10
11
12
13

commonMain 只能依赖：
  - Kotlin 标准库（多平台版本）
  - kotlinx-* 多平台库（coroutines, serialization, datetime 等）
  - 其他 commonMain 或「包含当前目标」的中间源集

androidMain 可额外依赖：
  - Android SDK
  - Jetpack 库
  - 纯 JVM 库

iosMain 可额外依赖：
  - Kotlin/Native 平台库
  - CocoaPods 依赖

四、实战示例

4.1 项目搭建

根 build.gradle.kts：

1
2
3
4
5

plugins {
    kotlin("multiplatform") version "2.0.0" apply false
    kotlin("plugin.serialization") version "2.0.0" apply false
    id("com.android.application") version "8.2.0" apply false
}

shared/build.gradle.kts（共享模块）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

plugins {
    kotlin("multiplatform")
    kotlin("plugin.serialization")
}

kotlin {
    androidTarget()
    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "shared"
            isStatic = true
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
            implementation("io.ktor:ktor-client-core:2.3.6")
            implementation("io.ktor:ktor-client-content-negotiation:2.3.6")
            implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.6")
        }
        androidMain.dependencies {
            implementation("io.ktor:ktor-client-okhttp:2.3.6")
        }
        iosMain.dependencies {
            implementation("io.ktor:ktor-client-darwin:2.3.6")
        }
    }
}

4.2 网络层：Ktor + kotlinx.serialization

commonMain - 数据模型与 API：

1
2
3
4
5
6
7
8
9
10
11
12

// commonMain/kotlin/data/model/User.kt
import kotlinx.serialization.Serializable

@Serializable
data class User(
    val id: Long,
    val name: String,
    val email: String
)

@Serializable
data class ApiResponse<T>(val data: T)

1
2
3
4
5
6
7
8
9
10
11
12
13

// commonMain/kotlin/data/remote/UserApi.kt
import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.request.*
import io.ktor.http.*

class UserApi(private val client: HttpClient) {
    suspend fun getUser(id: Long): User {
        return client.get("https://api.example.com/users/$id") {
            contentType(ContentType.Application.Json)
        }.body()
    }
}

commonMain - Ktor 客户端工厂：

1
2
3
4
5
6
7
8
9
10
11
12

// commonMain/kotlin/di/NetworkModule.kt
import io.ktor.client.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
import kotlinx.serialization.json.Json

expect fun createHttpClient(): HttpClient

fun createJson(): Json = Json {
    ignoreUnknownKeys = true
    isLenient = true
}

androidMain - OkHttp 引擎：

1
2
3
4
5
6
7
8
9
10

// androidMain/kotlin/di/NetworkModule.android.kt
import io.ktor.client.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.plugins.contentnegotiation.*

actual fun createHttpClient(): HttpClient = HttpClient(OkHttp) {
    install(ContentNegotiation) {
        json(createJson())
    }
}

iosMain - Darwin 引擎：

1
2
3
4
5
6
7
8
9
10

// iosMain/kotlin/di/NetworkModule.ios.kt
import io.ktor.client.*
import io.ktor.client.engine.darwin.*
import io.ktor.client.plugins.contentnegotiation.*

actual fun createHttpClient(): HttpClient = HttpClient(Darwin) {
    install(ContentNegotiation) {
        json(createJson())
    }
}

4.3 ViewModel 共享

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// commonMain/kotlin/presentation/UserViewModel.kt
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.*

class UserViewModel(
    private val userApi: UserApi,
    private val scope: CoroutineScope
) {
    private val _user = MutableStateFlow<User?>(null)
    val user: StateFlow<User?> = _user.asStateFlow()

    fun loadUser(id: Long) {
        scope.launch {
            _user.value = userApi.getUser(id)
        }
    }
}

• Android：注入 viewModelScope，通过 viewModel() 获取
• iOS：注入 MainScope() 或 ViewModelScope，通过 KMP 的 StateFlow 订阅

两端共享同一套 ViewModel 逻辑，仅 CoroutineScope 由各平台注入。

4.4 expect/actual 实用示例：日期格式化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// commonMain
expect fun formatDate(timestamp: Long): String

// androidMain
actual fun formatDate(timestamp: Long): String {
    val sdf = SimpleDateFormat("yyyy-MM-dd", Locale.getDefault())
    return sdf.format(Date(timestamp))
}

// iosMain
actual fun formatDate(timestamp: Long): String {
    val formatter = NSDateFormatter().apply {
        dateFormat = "yyyy-MM-dd"
    }
    return formatter.stringFromDate(NSDate(timestamp = timestamp / 1000.0))
}

五、实际项目应用案例

5.1 Cash App（Block 旗下金融应用）

启示：大型金融场景下，KMP 在「持久化」和「纯函数业务逻辑」上收益最大，且便于服务端参与共享代码。

5.2 Netflix

• 在移动工作室 App 中共享逻辑，减少重复开发
• 在影视制作的高节奏迭代下，提升交付效率与稳定性

5.3 McDonald’s

• 共享应用内支付等复杂业务逻辑
• 支撑每月 650 万+ 笔支付
• 验证 KMP 在电商/支付场景的可行性

5.4 Forbes

• 在 iOS 与 Android 间共享 80%+ 逻辑
• 双端可同步上线新功能，缩短发布周期

5.5 其他采用者

• Wrike、Bilibili、Feres 等使用 KMP + Compose Multiplatform
• Vouched、Karma 等采用 KMP 共享核心业务

六、最佳实践与注意事项

6.1 共享范围建议

6.2 常见陷阱

1. 在 commonMain 中引用平台 API：编译器会报错，应使用 expect/actual 抽象
2. expect/actual 签名不一致：必须保持完全一致（包名、函数名、参数、返回值）
3. 并发与线程：Kotlin/Native 对线程模型有约束，需注意 @ThreadLocal、freeze 等
4. 依赖版本：多平台库需保证各目标使用兼容版本

6.3 学习路线建议

1. 搭建最小 KMP 工程，跑通 Android + iOS
2. 用 expect/actual 封装 1～2 个平台 API
3. 接入 Ktor + kotlinx.serialization 实现共享网络层
4. 共享一个 ViewModel，在双端展示数据
5. 按业务模块逐步迁移，避免一次性大改

七、小结

KMP 以 「共享逻辑、原生 UI」 为核心，通过 expect/actual 和 Source Sets 实现跨平台抽象，在不牺牲原生体验的前提下显著降低双端重复开发。从 Cash App、Netflix、McDonald’s 等实践来看，KMP 已可用于生产环境，特别适合业务逻辑复杂、对一致性与性能要求较高的应用。结合 Jetpack Compose 与 SwiftUI，KMP 正成为 Android 开发者拓展 iOS 能力的重要路径。

参考资料

• Kotlin Multiplatform 官方文档
• Expect and actual declarations
• Kotlin Multiplatform project structure
• Cash App KMP 案例研究
• Ktor Client
• kotlinx.serialization

由浅入深，从基本概念到源码原理，再到实战案例，系统梳理 Web、移动、原生各平台的状态管理方案

一、什么是状态管理？

1.1 状态（State）的本质

状态是应用在某一时刻的数据快照，它决定了 UI 的展示内容和行为。任何会随时间变化的数据——用户输入、网络请求结果、权限、主题——都可视为状态。

1
2
3
4
5
6
7
8
9

+------------+   +------------+   +------------+   +------------+
| User Input |   |  Biz Data  |   |  UI State  |   |   Server   |
| Form/Search|   | List/Detail|   |Modal/Load  |   |   Cache    |
+------+-----+   +------+-----+   +------+-----+   +------+-----+
      |                 |                 |                 |
      +-----------------+--------+--------+-----------------+
                         |
                         v
               UI 渲染 / 副作用执行

用户输入·业务数据·UI状态·服务端 → 汇聚为统一的 UI 渲染与副作用执行

1.2 为什么需要状态管理？

1.3 各平台状态管理方案概览

二、状态管理的核心原则与模式

2.1 单向数据流（Unidirectional Data Flow）

大多数现代框架采用「单向数据流」：状态向下流动，事件向上反馈。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

┌─────────────┐
│   State     │  ← 单一数据源
└──────┬──────┘
       │ 只读传递
       ▼
┌─────────────┐
│    View     │  → 用户操作
└──────┬──────┘
       │ 事件 / Action
       ▼
┌─────────────┐
│  Reducer /  │  → 计算新状态
│  setState   │
└──────┬──────┘
       │
       └──────────► 更新 State → 重新渲染

React、Redux、Flutter Bloc、Jetpack Compose 的 ViewModel 均遵循此模式。

2.2 观察者模式：统一的底层基石

状态管理大多基于观察者模式：被观察对象变化时，通知所有订阅者。

2.3 局部状态 vs 全局状态

三、Web 前端：React 与 Next.js

3.1 React 状态管理

3.1.1 基本概念：useState

useState 是 React 最基础的状态 Hook，返回当前值和更新函数：

1
2
3
4
5
6
7
8

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

原理简述：React 在内部维护 Fiber 树，每个组件对应一个 Fiber 节点，useState 将状态存储在 Fiber 的 memoizedState 链表中。更新时调度 setState，标记组件需要重渲染，之后执行 diff 并提交 DOM 变更。

3.1.2 派生状态与 useReducer

当状态逻辑复杂时，用 useReducer 集中处理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

function reducer(state, action) {
  switch (action.type) {
    case 'increment': return { count: state.count + 1 };
    case 'decrement': return { count: state.count - 1 };
    default: return state;
  }
}
function Counter() {
  const [state, dispatch] = useReducer(reducer, { count: 0 });
  return (
    <>
      <span>{state.count}</span>
      <button onClick={() => dispatch({ type: 'increment' })}>+</button>
    </>
  );
}

3.1.3 跨组件共享：Context

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

const ThemeContext = createContext('light');

function App() {
  const [theme, setTheme] = useState('light');
  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      <Header />
      <Main />
    </ThemeContext.Provider>
  );
}

function Header() {
  const { theme } = useContext(ThemeContext);
  return <div className={theme}>...</div>;
}

注意：Context 变化会导致所有消费该 Context 的组件重渲染，可配合 useMemo / 拆分 Provider 优化。

3.1.4 副作用与依赖：useEffect

1
2
3
4
5
6
7
8
9
10

const [keyword, setKeyword] = useState('');
const [users, setUsers] = useState([]);

useEffect(() => {
  if (keyword.length < 2) return;
  const timer = setTimeout(() => {
    fetchUsers(keyword).then(setUsers);
  }, 300);
  return () => clearTimeout(timer);  // 清理函数
}, [keyword]);

3.2 Next.js 状态管理

Next.js 引入 Server Components 与 Client Components 的区分，状态管理策略随之变化。

3.2.1 服务端 vs 客户端状态

3.2.2 组合模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// app/page.tsx - Server Component（默认）
async function Page() {
  const data = await fetchFromDB();  // 服务端直接拉取
  return (
    <Layout>
      <StaticContent data={data} />
      <InteractiveCart />  {/* Client Component，内部用 useState */}
    </Layout>
  );
}

// components/InteractiveCart.tsx
'use client';
export function InteractiveCart() {
  const [items, setItems] = useState([]);
  return <CartUI items={items} onAdd={...} />;
}

3.2.3 Context 在 Next.js 中的使用

Context Provider 必须放在 Client Component 中：

1
2
3
4
5
6
7
8
9
10

// providers/ThemeProvider.tsx
'use client';
export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');
  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

四、跨平台移动：Flutter

4.1 基本概念

Flutter 的 UI 是声明式的：给定状态，构建对应 Widget 树。状态变化触发 setState 或 notifyListeners，进而重建 Widget。

4.2 内置方案

4.2.1 StatefulWidget + setState

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

class Counter extends StatefulWidget {
  @override
  _CounterState createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  int _count = 0;
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () => setState(() => _count++),
      child: Text('$_count'),
    );
  }
}

4.2.2 ValueNotifier + ValueListenableBuilder（局部重建）

1
2
3
4
5
6
7

final counter = ValueNotifier<int>(0);

ValueListenableBuilder<int>(
  valueListenable: counter,
  builder: (context, value, child) => Text('$value'),
)
// 只有 ValueListenableBuilder 会重建，而非整棵子树

4.2.3 ChangeNotifier + Provider

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class CartModel extends ChangeNotifier {
  final List<Item> _items = [];
  void add(Item item) {
    _items.add(item);
    notifyListeners();
  }
}

// 根节点
ChangeNotifierProvider(create: (_) => CartModel(), child: MyApp())

// 子节点消费
context.watch<CartModel>();  // 监听变化并重建
context.read<CartModel>();   // 仅读取，不监听

4.3 进阶：Riverpod / Bloc

• Riverpod：编译期安全、可测试、不依赖 BuildContext
• Bloc：事件 → 状态 的显式映射，适合复杂业务流

五、iOS 原生：Swift、RxSwift、SwiftUI

5.1 Swift 传统方式

• 属性观察器：willSet / didSet
• KVO：observe(_:options:changeHandler:)
• 通知：NotificationCenter
• Delegate / 闭包回调

5.2 RxSwift 响应式状态

RxSwift 将状态抽象为流，通过 Observable / Subject 管理：

1
2
3
4
5
6
7
8
9
10
11

// 文本框输入 → 搜索
let searchResults = searchTextField.rx.text.orEmpty
    .debounce(.milliseconds(300), scheduler: MainScheduler.instance)
    .flatMapLatest { api.search($0) }
    .observe(on: MainScheduler.instance)

searchResults
    .bind(to: tableView.rx.items(cellIdentifier: "Cell")) { _, model, cell in
        cell.textLabel?.text = model.name
    }
    .disposed(by: disposeBag)

Subject 可同时作为观察者和被观察者，常用于「桥接」命令式代码与响应式流：

1
2
3
4
5
6
7
8

let buttonTaps = PublishSubject<Void>()
buttonTaps
    .flatMapLatest { api.fetchData() }
    .subscribe(onNext: { updateUI($0) })
    .disposed(by: disposeBag)

// 命令式触发
button.rx.tap.bind(to: buttonTaps).disposed(by: disposeBag)

5.3 SwiftUI 声明式状态

5.3.1 @State：组件内部值类型状态

1
2
3
4
5
6

struct CounterView: View {
    @State private var count = 0
    var body: some View {
        Button("Count: \(count)") { count += 1 }
    }
}

5.3.2 @Binding：父子双向绑定

1
2
3
4
5
6
7
8
9
10
11
12
13

struct ParentView: View {
    @State private var isOn = false
    var body: some View {
        ToggleView(isOn: $isOn)  // 传递 Binding
    }
}

struct ToggleView: View {
    @Binding var isOn: Bool
    var body: some View {
        Toggle("", isOn: $isOn)
    }
}

5.3.3 @ObservedObject / @StateObject：引用类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class UserViewModel: ObservableObject {
    @Published var name = ""
    @Published var isLoading = false
}

struct ProfileView: View {
    @StateObject private var viewModel = UserViewModel()  // 创建并持有
    var body: some View {
        Text(viewModel.name)
    }
}

struct ChildView: View {
    @ObservedObject var viewModel: UserViewModel  // 从父组件传入
    var body: some View { ... }
}

5.3.4 @Observable（iOS 17+）

新宏 @Observable 可替代 ObservableObject，更简洁：

1
2
3
4
5
6
7
8
9
10
11
12

@Observable
class User {
    var name: String = ""
    var age: Int = 0
}

struct UserView: View {
    @State private var user = User()
    var body: some View {
        Text(user.name)  // 自动追踪依赖
    }
}

六、Android 原生：RxJava、Agera、Jetpack Compose

6.1 RxJava 响应式状态

1
2
3
4
5
6
7
8
9

val querySubject = PublishSubject.create<String>()
val results = querySubject
    .debounce(300, TimeUnit.MILLISECONDS)
    .filter { it.length >= 2 }
    .switchMap { api.search(it).toObservable() }
    .observeOn(AndroidSchedulers.mainThread())

results.subscribe { updateUI(it) }.addTo(compositeDisposable)
querySubject.onNext(editText.text.toString())

StateFlow / SharedFlow（Kotlin Flow）是官方推荐替代 LiveData 的方案：

1
2
3
4
5
6
7
8
9
10

class ViewModel : ViewModel() {
    private val _uiState = MutableStateFlow<UiState>(UiState.Loading)
    val uiState: StateFlow<UiState> = _uiState.asStateFlow()

    fun loadData() {
        viewModelScope.launch {
            _uiState.value = UiState.Success(repository.fetch())
        }
    }
}

6.2 Agera 简介（已归档）

Agera 是 Google 早期的轻量级响应式库，采用推事件、拉数据模型：

• Observable：广播事件
• Updatable：监听事件，从 Repository 拉取数据

1
2
3
4
5
6
7
8
9

// 概念示例（Agera 已归档，仅作了解）
val repository = Repositories.repositoryWithInitialValue(initialData)
    .observe()
    .onUpdatesPerLoop()
    .getFrom { fetchFromNetwork() }
    .compile()

repository.addUpdatable(updatable)
// 事件触发时，Updatable 从 Repository 拉取最新数据

注意：Agera 已于 2023 年 3 月归档，新项目建议使用 Kotlin Flow / StateFlow。

6.3 Jetpack Compose 状态管理

6.3.1 remember + mutableStateOf

1
2
3
4
5
6
7

@Composable
fun Counter() {
    var count by remember { mutableStateOf(0) }
    Button(onClick = { count++ }) {
        Text("Count: $count")
    }
}

• remember：在重组间保持值，避免每次重组重新创建
• mutableStateOf：创建可观察状态，读该状态的 Composable 会在值变化时重组

6.3.2 状态提升（State Hoisting）

1
2
3
4
5
6
7
8
9
10
11
12

@Composable
fun Parent() {
    var count by remember { mutableStateOf(0) }
    Child(count = count, onCountChange = { count = it })
}

@Composable
fun Child(count: Int, onCountChange: (Int) -> Unit) {
    Button(onClick = { onCountChange(count + 1) }) {
        Text("$count")
    }
}

6.3.3 ViewModel + StateFlow

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class MyViewModel : ViewModel() {
    private val _state = MutableStateFlow(MyState())
    val state: StateFlow<MyState> = _state.asStateFlow()

    fun update() {
        _state.update { it.copy(...) }
    }
}

@Composable
fun Screen(viewModel: MyViewModel = viewModel()) {
    val state by viewModel.state.collectAsStateWithLifecycle()
    // 使用 state
}

6.3.4 配置变更保留：rememberSaveable

1
2

var count by rememberSaveable { mutableStateOf(0) }
// 屏幕旋转等配置变更后，count 会保留

七、鸿蒙：ArkTS

7.1 装饰器驱动的状态

ArkTS 通过装饰器声明「可观察」状态，状态变化自动触发 UI 更新。

7.1.1 @State：组件内部状态

1
2
3
4
5
6
7
8
9
10
11
12

@Entry
@Component
struct Counter {
  @State count: number = 0
  build() {
    Column() {
      Text(`Count: ${this.count}`)
      Button('+1')
        .onClick(() => { this.count++ })
    }
  }
}

7.1.2 @Prop：父 → 子单向

1
2
3
4
5
6
7
8
9
10

@Component
struct Child {
  @Prop value: number  // 父组件传入，子组件只读
  build() {
    Text(`${this.value}`)
  }
}

// 父组件
Child({ value: this.count })

7.1.3 @Link：父子双向

1
2
3
4
5
6
7
8
9
10

@Component
struct Child {
  @Link value: number  // 子组件修改会同步回父组件
  build() {
    Button('+1').onClick(() => { this.value++ })
  }
}

// 父组件
Child({ value: $count })  // $ 语法传递引用

7.1.4 @Provide / @Consume：跨层级

1
2
3
4
5

// 祖先
@Provide('theme') theme: string = 'light'

// 任意后代
@Consume('theme') theme: string

7.1.5 @Observed + @ObjectLink：嵌套对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14

@Observed
class User {
  name: string
  constructor(name: string) { this.name = name }
}

@Component
struct UserView {
  @ObjectLink user: User
  build() {
    Text(this.user.name)
      .onClick(() => { this.user.name = 'New' })  // 触发更新
  }
}

7.2 状态管理 V2（@ObservedV2 + @Trace）

V2 支持深层属性观察，解决嵌套对象内部属性不可观察的问题。

八、跨平台对比与选型

8.1 概念映射表

8.2 选型建议

九、源码原理浅析

9.1 React：Fiber 与 Hooks 链表

React 在 Fiber 节点上维护 memoizedState 链表，每个 Hook 对应链表中的一个节点：

1
2
3
4
5

Fiber.memoizedState → useState → useEffect → useContext → ...
                          │
                          ├─ baseState
                          ├─ baseQueue
                          └─ next (下一个 Hook)

setState 会将更新放入队列，调度器在合适时机执行重渲染，按顺序应用更新，保证 Hooks 调用顺序稳定。

9.2 Jetpack Compose：快照与重组

Compose 使用 Snapshot 系统追踪状态读取：

1. mutableStateOf 创建 SnapshotMutableState
2. 读取 state.value 时，当前 Composable 的「重组作用域」会记录对该 state 的依赖
3. 写入 state.value = x 时，Compose 标记依赖该 state 的作用域需要重组
4. 重组时重新执行对应 Composable，得到新 UI

1

读取 state → 记录依赖 → 写入 state → 标记无效 → 调度重组 → 重新执行 Composable

9.3 SwiftUI：@State 与依赖追踪

SwiftUI 在编译期和运行期结合，追踪 body 中对 @State 等属性的访问。当 @State 变化时，视图的 body 会重新求值，生成新的 View 描述，再与旧描述 diff 后更新真实视图。

9.4 ArkTS：装饰器与更新调度

@State 等装饰器在编译期生成观察逻辑，运行时状态变化会标记组件为脏，下一帧统一执行 build 更新 UI，类似 Flutter 的 setState + 帧调度。

十、实战案例

10.1 登录表单校验（多字段组合）

需求：用户名 ≥3 字符、密码 ≥6 字符时，登录按钮才可点击。

React：

1
2
3
4

const [user, setUser] = useState('');
const [pwd, setPwd] = useState('');
const canLogin = user.length >= 3 && pwd.length >= 6;
return <Button disabled={!canLogin}>登录</Button>;

SwiftUI：

1
2
3
4

@State private var user = ""
@State private var pwd = ""
var canLogin: Bool { user.count >= 3 && pwd.count >= 6 }
Button("登录") { }.disabled(!canLogin)

Jetpack Compose：

1
2
3
4

var user by remember { mutableStateOf("") }
var pwd by remember { mutableStateOf("") }
val canLogin = user.length >= 3 && pwd.length >= 6
Button(onClick = {}, enabled = canLogin) { Text("登录") }

ArkTS：

1
2
3
4
5
6

@State user: string = ''
@State pwd: string = ''
private get canLogin(): boolean {
  return this.user.length >= 3 && this.pwd.length >= 6
}
Button('登录').enabled(this.canLogin)

10.2 搜索防抖 + 取消旧请求

React：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

const [keyword, setKeyword] = useState('');
const [results, setResults] = useState([]);

useEffect(() => {
  if (keyword.length < 2) return;
  const timer = setTimeout(() => {
    let cancelled = false;
    search(keyword).then(data => {
      if (!cancelled) setResults(data);
    });
    return () => { cancelled = true; };
  }, 300);
  return () => clearTimeout(timer);
}, [keyword]);

RxSwift：

1
2
3
4
5
6
7

searchTextField.rx.text.orEmpty
    .filter { $0.count >= 2 }
    .debounce(.milliseconds(300), scheduler: MainScheduler.instance)
    .flatMapLatest { api.search($0) }
    .observe(on: MainScheduler.instance)
    .bind(to: resultsRelay)
    .disposed(by: disposeBag)

Jetpack Compose + ViewModel：

1
2
3
4
5
6

val query = MutableStateFlow("")
val results = query
    .debounce(300)
    .filter { it.length >= 2 }
    .flatMapLatest { repository.search(it) }
    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())

10.3 购物车总价实时计算

Flutter (Provider)：

1
2
3
4
5

class CartModel extends ChangeNotifier {
  final List<CartItem> _items = [];
  double get total => _items.fold(0, (sum, item) => sum + item.price * item.qty);
  void add(CartItem item) { _items.add(item); notifyListeners(); }
}

React：

1
2
3
4
5

const [items, setItems] = useState([]);
const total = useMemo(
  () => items.reduce((s, i) => s + i.price * i.qty, 0),
  [items]
);

10.4 Next.js 服务端数据 + 客户端状态

1
2
3
4
5
6
7
8
9
10

// app/product/[id]/page.tsx
export default async function Page({ params }: { params: { id: string } }) {
  const product = await fetchProduct(params.id);  // 服务端拉取
  return (
    <div>
      <ProductInfo product={product} />
      <AddToCartButton productId={product.id} />  {/* 内部用 useState 管理数量 */}
    </div>
  );
}

十一、总结与最佳实践

11.1 核心要点

11.2 最佳实践

1. 最小化状态：能推导的不要存储，用 useMemo / computed / getter
2. 状态提升：当多组件需要共享时，提升到共同祖先
3. 不可变更新：避免直接修改，使用 setState/copy/扩展运算符
4. 副作用清理：useEffect 清理、Disposable.dispose、viewModelScope
5. 服务端状态分离：与 UI 状态区分，用专门库（React Query 等）管理
6. 类型安全：TypeScript、Swift、Kotlin 充分利用类型约束状态结构

11.3 各平台快速对照

参考资源

• React 官方文档 - 状态管理
• Next.js - Server and Client Components
• Flutter 状态管理
• SwiftUI 数据流
• Jetpack Compose 状态
• 鸿蒙 ArkUI 状态管理
• RxSwift
• RxJava
• Agera (Archived)

由浅入深，从基本概念到源码解析，全面掌握 Flutter 与 Android/iOS/鸿蒙、Electron 与 Mac/Windows 的原生交互能力

一、为什么需要原生交互？

1.1 跨平台框架的局限

跨平台框架（Flutter、Electron、React Native 等）为开发效率带来巨大提升，但受限于自身运行时，无法直接访问所有原生能力：

核心矛盾：跨平台代码运行在「沙箱」中，必须通过桥接层与原生世界通信。

1.2 两种典型架构对比

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

┌─────────────────────────────────────────────────────────────────────────┐
│                    Flutter 移动端（Android / iOS / 鸿蒙）                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   Dart (UI/逻辑)  ──► Platform Channel  ──►  Native (Kotlin/Swift/ArkTS)   │
│   MethodChannel      EventChannel          Android/iOS/HarmonyOS API      │
│   BasicMessageChannel                                                     │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                    Electron 桌面端（Mac / Windows / Linux）                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   Renderer (HTML/JS)  ──► IPC  ──►  Main Process  ──►  Native Addon       │
│                              contextBridge         Node-API / FFI         │
│                                                     .node / .dll / .dylib  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

二、Flutter 与原生交互

2.1 基本概念

2.1.1 Platform Channel 架构

Flutter 的 Platform Channel 是 Dart 与原生代码之间的消息传递机制，底层基于 BinaryMessenger 进行异步二进制通信。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

┌──────────────────┐         channel name          ┌──────────────────┐
│                  │   ◄────────────────────────►   │                  │
│   Dart 端        │   ByteData (序列化消息)         │   Native 端      │
│   (Client)       │   Future/Stream 响应            │   (Host)         │
│                  │                                │                  │
│  MethodChannel   │                                │  MethodChannel   │
│  EventChannel    │                                │  EventChannel    │
│  BasicMessageChannel                              │  BasicMessageChannel │
└──────────────────┘                                └──────────────────┘
         │                                                      │
         │  StandardMessageCodec (JSON-like 序列化)               │
         │  支持: null, bool, int, double, String                 │
         │       Uint8List, List, Map                            │
         ▼                                                      ▼
    Flutter Engine (C++)  ────────────────────  Platform Embedder

2.1.2 三种 Channel 类型辨析

2.1.3 数据类型映射（Dart ↔ Native）

2.2 MethodChannel 实战：获取电池电量

2.2.1 Dart 端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import 'package:flutter/services.dart';

class _MyHomePageState extends State<MyHomePage> {
  static const platform = MethodChannel('samples.flutter.dev/battery');
  String _batteryLevel = 'Unknown';

  Future<void> _getBatteryLevel() async {
    try {
      final int level = await platform.invokeMethod<int>('getBatteryLevel');
      setState(() => _batteryLevel = 'Battery level: $level%');
    } on PlatformException catch (e) {
      setState(() => _batteryLevel = "Failed: '${e.message}'");
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        ElevatedButton(onPressed: _getBatteryLevel, child: Text('Get Battery')),
        Text(_batteryLevel),
      ],
    );
  }
}

要点：

• Channel 名必须与原生端完全一致
• invokeMethod 返回 Future，支持泛型
• 捕获 PlatformException 处理原生端 result.error()

2.2.2 Android (Kotlin)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// MainActivity.kt
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel

class MainActivity : FlutterActivity() {
    private val CHANNEL = "samples.flutter.dev/battery"

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)
        MethodChannel(
            flutterEngine.dartExecutor.binaryMessenger,
            CHANNEL
        ).setMethodCallHandler { call, result ->
            when (call.method) {
                "getBatteryLevel" -> {
                    val level = getBatteryLevel()
                    if (level != -1) {
                        result.success(level)
                    } else {
                        result.error("UNAVAILABLE", "Battery level not available.", null)
                    }
                }
                else -> result.notImplemented()
            }
        }
    }

    private fun getBatteryLevel(): Int {
        val batteryManager = getSystemService(Context.BATTERY_SERVICE) as BatteryManager
        return batteryManager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY)
    }
}

2.2.3 iOS (Swift)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// AppDelegate.swift
import Flutter
import UIKit

@main
@objc class AppDelegate: FlutterAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let controller = window?.rootViewController as! FlutterViewController
        let channel = FlutterMethodChannel(
            name: "samples.flutter.dev/battery",
            binaryMessenger: controller.binaryMessenger
        )
        channel.setMethodCallHandler { [weak self] (call, result) in
            guard call.method == "getBatteryLevel" else {
                result(FlutterMethodNotImplemented)
                return
            }
            self?.receiveBatteryLevel(result: result)
        }
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

    private func receiveBatteryLevel(result: FlutterResult) {
        let device = UIDevice.current
        device.isBatteryMonitoringEnabled = true
        if device.batteryState == .unknown {
            result(FlutterError(code: "UNAVAILABLE", message: "Battery level not available.", details: nil))
        } else {
            result(Int(device.batteryLevel * 100))
        }
    }
}

2.2.4 鸿蒙 (ArkTS)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// EntryAbility.ets
import type { FlutterPlugin } from '@ohos/flutter';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    const flutterEngine = getFlutterEngine();
    const messenger = flutterEngine.getBinaryMessenger();
    
    const channel = new MethodChannel(messenger, 'samples.flutter.dev/battery');
    channel.setMethodCallHandler(async (call) => {
      if (call.method === 'getBatteryLevel') {
        const level = await this.getBatteryLevel();
        return level;
      }
      throw new Error('NotImplemented');
    });
  }

  private async getBatteryLevel(): Promise<number> {
    const batteryInfo = await battery.getBatteryInfo();
    return batteryInfo.batterySoc; // 0-100
  }
}

2.3 EventChannel 实战：监听位置更新

适用于持续从 Native 向 Dart 推送数据的场景。

2.3.1 Dart 端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import 'dart:async';
import 'package:flutter/services.dart';

class LocationService {
  static const _channel = EventChannel('samples.flutter.dev/location');

  Stream<Location> get locationStream => _channel
      .receiveBroadcastStream()
      .map((dynamic event) => Location.fromMap(Map<String, dynamic>.from(event as Map)));
}

// 使用
StreamSubscription? _subscription;

void _startListening() {
  _subscription = LocationService().locationStream.listen(
    (loc) => print('Lat: ${loc.lat}, Lng: ${loc.lng}'),
    onError: (e) => print('Error: $e'),
  );
}

void _stopListening() {
  _subscription?.cancel();
}

2.3.2 Android (Kotlin) - EventChannel.StreamHandler

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

class LocationStreamHandler : EventChannel.StreamHandler {
    private var eventSink: EventChannel.EventSink? = null
    private var locationCallback: LocationCallback? = null

    override fun onListen(arguments: Any?, events: EventChannel.EventSink?) {
        eventSink = events
        locationCallback = object : LocationCallback() {
            override fun onLocationResult(result: LocationResult) {
                for (loc in result.locations) {
                    eventSink?.success(mapOf(
                        "lat" to loc.latitude,
                        "lng" to loc.longitude
                    ))
                }
            }
        }
        fusedLocationClient.requestLocationUpdates(request, locationCallback!!, Looper.getMainLooper())
    }

    override fun onCancel(arguments: Any?) {
        locationCallback?.let { fusedLocationClient.removeLocationUpdates(it) }
        eventSink = null
    }
}

// 注册
EventChannel(flutterEngine.dartExecutor.binaryMessenger, "samples.flutter.dev/location")
    .setStreamHandler(LocationStreamHandler())

2.4 底层原理：BinaryMessenger

所有 Channel 的底层都依赖 BinaryMessenger：

1
2
3
4
5
6
7
8
9

Dart 侧 (binary_messenger.dart)
├── send(channel, message) → Future<ByteData?>
├── setMessageHandler(channel, handler)
└── 消息以 ByteData 形式序列化传输

Native 侧 (Android: DartExecutor, iOS: FlutterBinaryMessenger)
├── 实现 BinaryMessenger 接口
├── 通过 Flutter Engine 与 Dart 隔离
└── 线程：Android 主线程，iOS 主线程

关键点：

• 消息是异步的，保证 UI 不阻塞
• 序列化由 StandardMessageCodec 完成（或自定义 MessageCodec）
• Channel 名称是路由键，用于区分不同功能

2.5 Pigeon：类型安全的 Platform Channel

手动维护 MethodChannel 容易出错（字符串拼写、类型不匹配）。Pigeon 是 Flutter 官方代码生成工具，从接口定义自动生成各端代码。

2.5.1 定义接口 (pigeon/api.dart)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import 'package:pigeon/pigeon.dart';

@HostApi()
abstract class BatteryApi {
  int getBatteryLevel();
}

@HostApi()
abstract class LocationApi {
  void startLocationUpdates();
  void stopLocationUpdates();
}

@FlutterApi()
abstract class LocationCallback {
  void onLocation(double lat, double lng);
}

2.5.2 生成代码

1
2
3

# pubspec.yaml
dev_dependencies:
  pigeon: ^26.0.0

1

flutter pub run pigeon --input pigeon/api.dart

会生成：

• dart/*.dart：Dart 端接口实现
• kotlin/*.kt：Android Kotlin 实现骨架
• swift/*.swift：iOS Swift 实现骨架

2.5.3 优势

2.6 实际项目应用案例

案例 1：支付 SDK 接入

1
2
3
4
5
6
7

业务需求：Flutter 调起微信/支付宝支付，并接收支付结果回调

实现要点：
1. MethodChannel 调用 Native 调起支付
2. 支付结果通过 EventChannel 或 MethodChannel.invokeMethod 反向回调
3. Android: Activity Result API，iOS: URL Scheme / Universal Links
4. 注意：支付必须在主线程/主 Activity 完成

案例 2：相机自定义预览 + 拍照

1
2
3
4
5
6
7

业务需求：自定义相机 UI，支持滤镜、闪光灯、变焦

实现要点：
1. 使用 Platform View (AndroidView / UiKitView) 嵌入原生相机 View
2. MethodChannel 控制：开始预览、拍照、切换滤镜
3. EventChannel 或 Texture 传递预览帧（如需实时处理）
4. 注意线程：相机回调可能在子线程，需 Post 到主线程再通过 Channel 回传

案例 3：蓝牙设备扫描与连接

1
2
3
4
5
6
7

业务需求：扫描 BLE 设备，连接并读写特征值

实现要点：
1. EventChannel 持续推送扫描到的设备列表
2. MethodChannel 执行：连接、断开、读/写特征值
3. 连接状态、数据回调通过 EventChannel 流式回传
4. 鸿蒙侧使用 @ohos.bluetooth 相关 API，需申请权限

三、Electron 与原生交互

3.1 基本概念

3.1.1 Electron 架构回顾

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

┌─────────────────────────────────────────────────────────────────────┐
│                        Renderer Process (多个)                        │
│   HTML + CSS + JavaScript (前端界面)                                  │
│   受沙箱限制，无法直接访问 Node.js / 原生模块                          │
└───────────────────────────────────┬─────────────────────────────────┘
                                    │ IPC (ipcRenderer / contextBridge)
┌───────────────────────────────────▼─────────────────────────────────┐
│                        Main Process (单个)                            │
│   Node.js 运行时，可 require('fs')、require('原生模块')                │
│   可加载 .node (Native Addon)、调用 FFI                               │
└───────────────────────────────────┬─────────────────────────────────┘
                                    │ Node-API / N-API
┌───────────────────────────────────▼─────────────────────────────────┐
│                        Native Addon / 系统 API                        │
│   C/C++ 编写，编译为 .node (Unix) / .dll (Windows)                     │
│   或通过 FFI 调用已有 .dll / .dylib / .so                             │
└─────────────────────────────────────────────────────────────────────┘

核心原则：所有原生调用必须在 Main Process 完成，Renderer 通过 IPC 与 Main 通信。

3.1.2 两种原生交互方式

3.2 Native Addon 开发（Node-API）

3.2.1 环境准备

macOS：

1

xcode-select --install  # 安装 Xcode Command Line Tools

Windows：

• 安装 Node.js 时勾选 “Tools for Native Modules”
• 或通过 npm install -g windows-build-tools 安装 VS Build Tools

依赖：

1
2

npm install node-addon-api bindings
npm install -g node-gyp

3.2.2 项目结构

1
2
3
4
5
6

native-addon/
├── binding.gyp          # 构建配置
├── src/
│   └── addon.cc         # C++ 源码
├── package.json
└── index.js             # 对外导出

3.2.3 binding.gyp

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "targets": [{
    "target_name": "my_addon",
    "sources": [ "src/addon.cc" ],
    "include_dirs": [
      "<!@(node -p \"require('node-addon-api').include\")"
    ],
    "dependencies": [
      "<!(node -p \"require('node-addon-api').gyp\")"
    ],
    "cflags!": [ "-fno-exceptions" ],
    "cflags_cc!": [ "-fno-exceptions" ],
    "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ],
    "conditions": [
      ["OS=='win'", { "msvs_settings": { "VCCLCompilerTool": { "ExceptionHandling": 1 } } }]
    ]
  }]
}

3.2.4 C++ 源码 (src/addon.cc)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

#include <napi.h>

Napi::Value Add(const Napi::CallbackInfo& info) {
  Napi::Env env = info.Env();
  if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsNumber()) {
    Napi::TypeError::New(env, "Number expected").ThrowAsJavaScriptException();
    return env.Null();
  }
  double a = info[0].As<Napi::Number>().DoubleValue();
  double b = info[1].As<Napi::Number>().DoubleValue();
  return Napi::Number::New(env, a + b);
}

Napi::Object Init(Napi::Env env, Napi::Object exports) {
  exports.Set("add", Napi::Function::New(env, Add));
  return exports;
}

NODE_API_MODULE(my_addon, Init)

3.2.5 调用方 (index.js)

1
2

const addon = require('bindings')('my_addon');
console.log(addon.add(1.5, 2.3));  // 3.8

3.2.6 在 Electron 中使用

关键：Electron 的 Node.js 版本与官方 Node 不同，需要重新编译 Native Addon：

1
2

npm install @electron/rebuild --save-dev
npx electron-rebuild

或在 package.json 中配置：

1
2
3
4
5

{
  "scripts": {
    "rebuild": "electron-rebuild"
  }
}

Main Process 中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// main.js
const { app, BrowserWindow, ipcMain } = require('electron');
const addon = require('bindings')('my_addon');

let win;

function createWindow() {
  win = new BrowserWindow({
    webPreferences: { nodeIntegration: false, contextIsolation: true }
  });
  win.loadFile('index.html');
}

ipcMain.handle('add-numbers', (event, a, b) => {
  return addon.add(a, b);
});

app.whenReady().then(createWindow);

Preload (preload.js)：

1
2
3
4
5

const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('native', {
  add: (a, b) => ipcRenderer.invoke('add-numbers', a, b)
});

Renderer：

1
2

const result = await window.native.add(1.5, 2.3);
console.log(result);  // 3.8

3.3 FFI：调用已有 C 库

当需要调用已有的 .dll (Windows)、.dylib (macOS)、.so (Linux) 时，使用 FFI 无需重写 C++ 代码。

3.3.1 使用 koffi（推荐，支持 N-API）

1

npm install koffi

1
2
3
4
5
6
7
8
9
10
11
12
13

const koffi = require('koffi');

// 加载系统库
const libc = koffi.load('libc.so.6');  // Linux
// const libc = koffi.load('msvcrt.dll');  // Windows
// const libc = koffi.load('libc.dylib');  // macOS

const ceil = libc.func('double ceil(double)', 'ceil');
console.log(ceil(3.2));  // 4

// 加载自定义 DLL
const myLib = koffi.load('./my_lib.dll');
const myFunc = myLib.func('int my_func(const char* str, int len)', 'my_func');

3.3.2 使用 node-ffi-napi（注意 Electron 兼容性）

1
2
3
4
5
6
7
8

const ffi = require('ffi-napi');
const ref = require('ref-napi');

const msvcrt = ffi.Library('msvcrt', {
  'ceil': ['double', ['double']]
});

console.log(msvcrt.ceil(3.2));  // 4

注意：Electron 20.3.8+ 的沙箱可能限制指针操作，导致 ffi-napi 崩溃，可考虑：

• 使用 koffi（基于 N-API，兼容性更好）
• 或通过 Main Process 调用，避免在 Renderer 使用 FFI

3.4 实际项目应用案例

案例 1：调用 Windows 系统 API（获取 CPU 使用率）

1
2
3
4
5
6
7

需求：在 Electron 应用中显示实时 CPU 使用率

实现：
1. 使用 node-ffi-napi 或 koffi 加载 kernel32.dll / pdh.dll
2. 调用 GetSystemTimes、PdhCollectQueryData 等 API
3. Main Process 定时采样，通过 IPC 推送到 Renderer 展示
4. 跨平台：macOS 使用 sysctl，Linux 使用 /proc/stat

案例 2：硬件加密狗认证

1
2
3
4
5
6
7

需求：桌面端软件需插入 USB 加密狗才能使用

实现：
1. 厂商提供 .dll / .so SDK
2. 通过 FFI 加载 SDK，调用 CheckDongle()、GetLicense() 等
3. Main Process 启动时校验，失败则禁止启动
4. 注意：.dll 路径需随应用打包正确配置（如 resources/ 目录）

案例 3：大文件加解密（性能敏感）

1
2
3
4
5
6
7

需求：对 GB 级文件进行 AES 加解密，纯 JS 太慢

实现：
1. 用 C++ 编写加解密模块，基于 OpenSSL 或 crypto 库
2. 编译为 Native Addon，暴露 encryptFile(path)、decryptFile(path)
3. Main Process 调用，通过 Stream 或进度回调推送到 Renderer
4. 可考虑 Worker 线程 + 原生模块，避免阻塞主进程

四、对比与选型

4.1 Flutter vs Electron 原生交互对比

4.2 何时用 MethodChannel / EventChannel / FFI / Native Addon

五、最佳实践与注意事项

5.1 Flutter

1. Channel 命名：使用反向域名，如 com.yourapp.service/battery，避免冲突
2. 主线程：Android/iOS 的 Channel 回调一般在主线程，耗时操作应异步处理
3. 错误处理：原生端务必调用 result.error() 或 result.notImplemented()，避免 Dart 侧 Future 一直挂起
4. 内存泄漏：EventChannel 的 onCancel 必须移除监听器、释放资源
5. 插件化：可复用逻辑封装为 Flutter Plugin，发布到 pub.dev

5.2 Electron

1. 安全：禁用 Renderer 的 nodeIntegration，仅通过 contextBridge 暴露必要 API
2. 重建：每次升级 Electron 版本后执行 electron-rebuild
3. 路径：Native Addon 的 .node 文件路径在打包后可能变化，使用 __dirname、app.getPath('userData') 等正确处理
4. 崩溃：C++ 模块崩溃会导致整个进程退出，需做好 try-catch 和日志

5.3 鸿蒙特别说明

• Flutter 对 OpenHarmony/HarmonyOS 的支持在快速演进，需关注官方文档和 flutter_harmony 等生态
• ArkTS 与 Dart 的 MethodChannel 接口类似，但需使用鸿蒙提供的 FlutterPlugin、MethodChannel 等 API
• 权限、包名、签名等需符合鸿蒙应用规范

六、总结

掌握原生交互能力，是跨平台开发从「能写」到「写好」的关键一步。建议先跑通官方示例，再结合实际业务逐步封装和优化。

附录：参考资源

• Flutter Platform Channels 官方文档
• Flutter Pigeon 包
• Electron Native Code 文档
• Node-API 文档
• node-addon-api

目录

• 一、响应式编程基础
• 二、iOS响应式状态管理
• 三、Flutter响应式状态管理
• 四、React响应式状态管理
• 五、React Native响应式状态管理
• 六、鸿蒙响应式状态管理
• 七、性能优化与对比
• 八、最佳实践与架构选型

一、响应式编程基础