📚 课程目录第3章 MethodChannel基础与消息编解码

3. MethodChannel基础与消息编解码

MethodChannel 是 Flutter 与原生平台之间最常用的双向通信通道。它把 Dart 侧的方法调用封装成一条二进制消息，经由 BinaryMessenger 投递到原生侧，原生侧处理后把结果再编码回 Dart。理解这条链路上“谁负责搬运、谁负责编解码、数据长什么样”，是排查通道类问题的前提。

一、三层职责：Channel、Codec、BinaryMessenger

MethodChannel 本身并不传输数据，它只负责“方法名 + 参数 + 返回值”这一语义层的组织。真正把数据变成字节的是 MethodCodec，真正把字节送过平台边界的是 BinaryMessenger。三者的分工可以概括为：

MethodChannel：持有通道名（如 com.example.app/battery），提供 invokeMethod、setMethodCallHandler 等 API，决定“调用哪个方法、传什么参数”。
MethodCodec：把 MethodCall（方法名 + 参数）编码为 ByteData，把原生返回的 ByteData 解码为成功结果或 PlatformException。默认实现是 StandardMethodCodec。
BinaryMessenger：按通道名收发 ByteData，是平台通道的底层传输层。Dart 侧通过 ServicesBinding.instance.defaultBinaryMessenger 访问，原生侧通过 FlutterEngine.getDartExecutor().getBinaryMessenger()（Android）或 FlutterBinaryMessenger（iOS）访问。

因此，当出现“方法找不到”“参数类型不对”“返回值解析失败”等问题时，要区分是通道名不匹配（Channel 层）、编码格式不一致（Codec 层），还是消息未送达（BinaryMessenger 层）。

二、StandardMethodCodec 的序列化规则

StandardMethodCodec 是 MethodChannel 的默认编解码器，它规定了 Dart 与原生之间可安全传递的类型集合。理解这套规则，能避免“传了原生不认识的类型”这类运行时错误。

Dart 侧可编码的类型与原生对应关系如下：

Dart 类型	Android（Java/Kotlin）	iOS（Swift/ObjC）
`null`	`null`	`nil`
`bool`	`Boolean`	`NSNumber(bool)`
`int`	`Integer` / `Long`	`NSNumber(int)`
`double`	`Double`	`NSNumber(double)`
`String`	`String`	`NSString`
`Uint8List`	`byte[]`	`FlutterStandardTypedData`
`List`	`ArrayList`	`NSArray`
`Map`	`HashMap`	`NSDictionary`

注意几个容易踩坑的点：Dart 的 int 在 64 位平台上可能超出 32 位范围，Android 侧若用 Integer 接收会溢出，应使用 Long；Dart 的 List 和 Map 可以嵌套，但嵌套层级过深会增加编解码开销；自定义对象不能直接传递，必须先转成 Map 或 JSON 字符串。

三、方法调用的完整生命周期

一次 invokeMethod 调用，在底层会经历以下阶段：

Dart 侧构造 MethodCall，包含方法名和参数（可为 null）。
StandardMethodCodec 将其编码为 ByteData，格式为：成功标志字节 + 方法名 + 参数。
BinaryMessenger 按通道名把字节投递到原生侧。
原生侧 BinaryMessenger 收到字节，交给注册的 MethodCallHandler。
StandardMethodCodec 解码出方法名和参数，分发给对应的处理分支。
原生侧执行逻辑，调用 result.success(value) 或 result.error(code, message, details)。
返回值被编码为 ByteData，沿原路返回 Dart 侧。
Dart 侧解码：成功则 Future 完成并携带值；失败则抛出 PlatformException。

如果原生侧忘记调用 result，Dart 侧的 Future 会一直挂起，表现为“调用无响应”。这是新手最常见的错误之一。

四、一个可运行的最小示例

下面以获取电池电量为例，展示 Dart 侧与 Android 侧的完整实现。通道名统一使用 com.example.app/battery。

// Dart 侧
static const _channel = MethodChannel('com.example.app/battery');

Future<int> getBatteryLevel() async {
  final level = await _channel.invokeMethod<int>('getBatteryLevel');
  return level ?? -1;
}

// Android 侧（Kotlin）
class MainActivity : FlutterActivity() {
  private val CHANNEL = "com.example.app/battery"

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

运行后，Dart 侧 getBatteryLevel() 返回一个 int，例如 85。如果原生侧返回 result.error，Dart 侧会抛出 PlatformException，可通过 try/catch 捕获并读取 code、message、details 三个字段。

调试建议：在原生侧 handler 入口打印 call.method 和 call.arguments，在 Dart 侧打印 invokeMethod 前后的日志，可以快速定位是通道名不匹配、方法名拼写错误，还是参数类型转换失败。

五、返回值与异常的处理约定

StandardMethodCodec 对返回值的编码有三种状态：成功、错误、未实现。对应到 Dart 侧：

result.success(value) → Future 正常完成，值为 value。
result.error(code, message, details) → 抛出 PlatformException(code, message, details)。
result.notImplemented() → 抛出 MissingPluginException，通常意味着原生侧没有注册该通道或方法名不匹配。

因此，在 Dart 侧调用时，建议始终用 try/catch 包裹，并根据异常类型区分处理：MissingPluginException 说明插件未正确注册，PlatformException 说明原生逻辑执行失败。这样可以把“通道问题”和“业务问题”分开排查。

注意：MethodChannel 的调用是异步的，且默认在主线程（UI 线程）上执行。如果原生侧处理耗时较长，应切换到后台线程，处理完再回到主线程调用 result，否则会阻塞 UI。

掌握 BinaryMessenger 的传输职责、StandardMethodCodec 的类型规则，以及方法调用从编码到解码的完整路径，就能在遇到通道问题时快速定位到具体环节，而不是盲目猜测。