Flutter异步原理-Future

前言

• 在 Dart 中，谈到异步就离不开 Future。无论是 .then()、还是 await，它们背后运作的都是一个私有实现类：_Future ，我们平时使用的 Future 只是一个抽象接口，其真正的实现逻辑由_Future 承担。

class _Future<T> implements Future<T> {int _state; // 当前状态，如未完成、已完成、链式等待等。_Zone _zone; // 创建时绑定的执行 Zone。var _resultOrListeners; // 保存完成结果或注册的监听器链表。bool get _mayComplete => (_state & _completionStateMask) == _stateIncomplete;bool get _isComplete => (_state & (_stateValue | _stateError)) != 0;bool get _hasError => (_state & _stateError) != 0;void _complete(FutureOr<T> value); // 完成 Future（同步）void _asyncComplete(FutureOr<T> value); // 异步完成 Future（microtask）void _chainCoreFutureSync(_Future source, _Future target); // 同步触发 Future，如果source已完成，则把结果克隆给target，并触发回调。如果source未完成，void _chainCoreFutureAsync(Future source); // 异步链接 Futurevoid _chainForeignFuture(Future source); // 链接外部 Futurevoid _propagateToListeners();//将Future的完成结果（值或错误）传播给所有已注册的监听器void _addListener(_FutureListener listener); //添加 单个 Future 回调到链表头部void _prependListeners(_FutureListener? listeners) //将回调链添加到链表头部void _removeListeners(); //移除并返回当前Future的所有监听器void __reverseListeners(_FutureListener? listeners); //反转链表}

从我们贴出的 _Future 类结构可以看出，它是 Future 真正的底层实现，承担了 Dart 异步机制中绝大部分实际工作。其主要功能可以拆解为以下四个部分：

1. 状态管理
   _Future 本质上是一个状态机（state machine）。它管理异步任务的生命周期：未完成 → 完成（成功/失败）→ 回调派发。
   1.1 _state
   _state 描述了可能出现的状态，包括：

• incomplete：Future 尚未完成；
• value：Future 已完成，有一个正常结果；
• error：Future 已完成，抛出了异常；
• chained：Future 自己不持有结果，而是依赖另一个 Future。
  并允许组合判断状态：
  bool get _isComplete => (_state & (_stateValue | _stateError)) != 0;
  bool get _hasError => (_state & _stateError) != 0;
  1.2 _resultOrListeners
  _resultOrListeners 是 _Future 状态同步的关键容器字段，它的类型是 var，也就是说它可以根据当前状态动态切换存储内容：
• Future未完成时： 注册的 listener 链表；
• 已完成，有一个正常结果：完成的值；
• Future 已完成，抛出了异常：异常对象 (AsyncError)；
• Future 自己不持有结果，而是依赖另一个 Future：链式模式中所依赖的源 _Future。

可以说，_resultOrListeners 是整个 _Future 状态机的“状态内容仓库”，配合 _state 一起完成了状态标志 + 状态数据的组合表达。
2. 链式触发
当我们在一个 Future 上调用 .then()、.catchError() 或 .whenComplete() 时，Dart 会创建一个新的 Future 并注册对应的回调，当原始 Future 完成后触发回调，新的 Future 则根据回调的返回值决定如何完成。如果返回的是普通值，新 Future 立即完成；如果返回的是另一个 Future，则进入链式等待，直到该 Future 完成。

Future<R> then<R>(FutureOr<R> f(T value), {Function? onError}) {//...错误处理_Future<R> result = new _Future<R>();_addListener(new _FutureListener<T, R>.then(result, f, onError));return result;}

梳理一下then方法执行的过程：

1. 创建一个新的 _Future result；
2. 构造一个 _FutureListener 对象，把回调绑定进去；
3. 把这个 listener 挂在当前 Future（source）上；
4. 当前 Future 完成时，调度执行 listener 的回调；

如果回调返回了另一个 Future（记作 returned），Dart 会调用 _chainCoreFutureSync(returned, result)，让 target 依赖于 returned 的完成状态，构建链式触发关系。

链式（Chain）
chain 的意思是：我这个 Future 不自己决定什么时候完成，而是等另一个 Future 完成，把它的结果“搬过来”当作自己的结果。

那么出现了一个问题：为什么 result 明明是等 source 完成才有结果，但 Dart 不把它们 chain，在回调里返回 Future 的时候却要 chain？
我们来深入分析 _propagateToListeners() 中对回调返回值的判断处理，是如何决定当前 result 的完成方式的。
关键代码如下：

var returned = listener.handleValue(source._resultOrListeners);if (returned is Future && !identical(returned, listener.result)) {// 回调返回了一个 Future（而且不是自己）_chainCoreFutureSync(returned, listener.result); // 关键链式触发点
} else {// 回调返回的是普通值，直接完成listener.result._complete(returned);
}

问题就变成了：当source Future执行完成时，如果回调函数的返回值是数值就去执行_complete()方法，结束result Future, 如果返回值类型是Future类型会将 新的Future(returned) 与result Future的生命周期绑定。这两种不都是一个结束另一个也结束吗？

主要问题在于： 情况1 的Future A结束 ，B也结束，并不是同时完成的，换句话说，Future A结束只是通过回调去 通知 B去执行并变成完成状态，而 情况2 是B 完全放弃自己的生命周期管理，将自己的回调节点完全转移到A的回调链上。
其实 情况1 更符合我们认知的chain的概念，但是情况2是Future设计的精髓，await 关键词将修饰的Future与异步函数返回的Future绑定本质是也是通过chain实现。
Chain 建立流程
下面我们看一下chain建立的过程
2.1 监听器转移机制 ：

• 当调用 _setChained 建立链式关系时，会将当前Future的监听器转移到源Future

// 在_chainCoreFutureSync中_FutureListener ? listeners = target._resultOrListeners;target. _setChained ( source ) ;source. _prependListeners ( listeners ) ; // 将监听器转移到源Future

这个过程表示：
target 自己不执行任何回调了，而是“把所有后续操作都挂到 source（returned）上”，由它完成后再向下传播。

2.2 完成传播路径 ：
当源 Future（比如某个回调返回的 Future）完成后：

• 会调用 _propagateToListeners()，遍历并通知其所有监听器；
• 如果这些监听器来自于一个链式 Future（如上面的 target），它们会被特殊处理：
  • 通过 _FutureListener 的子类包装，确保在值传递的同时更新目标 result 的状态；
  • 例如 .then() 的监听器会调用 handleValue()，并可能再触发 _complete() 或新的 chain。

2.3 状态检查 ：
Dart 会通过以下两个方式标识和追踪链式状态：
_isChained

• 这是 target 的状态位；
• 当 target._setChained(source) 被调用时会设置；
• 表示当前 Future 并不自己持有结果，而是依赖另一个 Future；
• 它的 _resultOrListeners 字段也被设置为 source，表示链的指向。

_chainSource

• 提供链式结构中当前 Future 所依赖的源 Future；
• 如果是链式 Future，_chainSource 返回的是 _resultOrListeners 中的源 Future；
• 可以用于调试、诊断依赖结构，或从链式 Future 中找出最初的结果拥有者。

总结
当 Dart 判断一个 Future 需要被 chain（即回调返回了另一个 Future），它会让当前 Future 的回调挂到 returned Future 上，完成后再统一传播，并通过 _isChained 和 _resultOrListeners 标记整个依赖关系。
3. 异步调度

- _Completer<T> / _AsyncCompleter<T> / _SyncCompleter<T>：提供手动完成 Future 的机制。
- _complete / _asyncComplete ：完成Future的方法_Completer<T>及其子类abstract class _Completer<T> implements Completer<T> {final _Future<T> future = _Future<T>();void complete([FutureOr<T>? value]);void completeError(Object error, [StackTrace? stackTrace]);
}class _AsyncCompleter<T> extends _Completer<T> { /* microtask完成Future */ }
class _SyncCompleter<T> extends _Completer<T> { /* 同步立即完成Future */ }

用法区别：

• Completer() = _AsyncCompleter（异步完成，本质是调用_asyncComplete）
• Completer.sync() = _SyncCompleter（同步完成,本质是调用_complete）

_complete() & _asyncComplete()
Future 支持“立即完成”与“异步完成”两种模式。这一机制由 _complete() 与 _asyncComplete() 方法控制，调用者可以通过不同方式选择调度路径。

_complete()：同步完成

void _complete(FutureOr<T> value) {assert(!_isComplete);if (value is Future<T>) {if (value is _Future<T>) {_chainCoreFutureSync(value, this);} else {_chainForeignFuture(value);}} else {_FutureListener? listeners = _removeListeners();_setValue(value);_propagateToListeners(this, listeners);}}

• 直接完成当前 Future，立即更新状态并分发监听器；
• 不进入 microtask 队列，适合需要同步完成的场景；
• 用于 Completer.sync() 创建的同步 Completer。

_asyncComplete()：异步完成

void _asyncComplete(FutureOr<T> value) {assert(!_isComplete); // 保证当前 Future 还没完成if (value is Future<T>) {_chainFuture(value); // 如果是 Future，立即链式绑定return;}_asyncCompleteWithValue(value); // 如果是数值，推入微任务中完成
}

• 将 _complete() 推入 microtask 队列中异步执行；
• 保证 Future 的完成不会打断当前同步代码执行栈；
• 是 Completer() 默认使用的路径。

4. 回调管理
5. _FutureListener<S, T>

• _FutureListener<S, T>：监听回调单元，代表 .then()、.catchError()、.whenComplete() 等注册。

class _FutureListener<S, T> {final _Future<T> result; // 回调结果将赋值到的新 Future。final int state; // 掩码标记当前 listener 类型。final Function? callback; // 正常回调final Function? errorCallback; // 错误回调FutureOr<T> handleValue(S value); // 成功回调执行FutureOr<T> handleError(AsyncError asyncError); // 错误回调执行dynamic handleWhenComplete(); // 完成回调执行
}

state取值如下：

• stateThen：处理成功值
• stateCatchError：处理异常
• stateWhenComplete：处理 finally 场景

2. Listener 链组织结构：单链表

所有 _FutureListener 是以单向链表 结构 串接的：

• 每个 _Future 拥有一个 _resultOrListeners 字段；
• 在未完成状态时，这个字段保存的是 listener 链的头节点；
• 每次调用 .then() 或 .catchError() 都会创建一个 _FutureListener，并通过 _addListener() 加入链头；
• 执行完成后，listener 会被 _removeListeners() 清空。

3. 操作方法
4. _addListener(_FutureListener listener)

• 将 listener 添加到链表头部；
• 如果当前 Future 已完成，则立即派发执行；

2. _prependListeners(_FutureListener? listeners)

• 将一整段 listener 链表接到当前 listener 链的头部；
• 用于链式传播中 listener 的转移，例如在 _chainCoreFutureSync() 中：

final listeners = target._removeListeners();
target._setChained(source);
source._prependListeners(listeners);

3. _removeListeners()

• 将当前 Future 所有 listener 移除并返回（用于调度）；
• 移除后 _resultOrListeners 置为 null 或结果值；

4. __reverseListeners(_FutureListener? listeners)

• 于反转链表顺序；
• 保证按注册顺序依次触发，而不是后注册先触发；

4. 完整流程
5. Future 调用 .then() 注册回调，创建 _FutureListener，加入链表；
6. Future 完成后，调用 _propagateToListeners()：

• 遍历 listener 链；
• 区分状态执行 handleValue / handleError / handleWhenComplete；
• 将回调返回结果赋值到 listener.result；

3. 若返回的是 Future，则触发 _chainCoreFutureSync()，建立链式；

4. _propagateToListeners

static void _propagateToListeners(_Future source, _FutureListener? listeners) {while (true) {if (listeners == null) {if (source._hasError && !source._ignoreError) {source._zone.handleUncaughtError(source._error);}return;}final listener = listeners;listeners = listener._nextListener;// 执行handleXXX回调if (listener.handlesComplete) {listener.handleWhenComplete();} else if (!source._hasError) {listener.handleValue(source._resultOrListeners);} else {listener.handleError(source._error);}// 链式传播或继续下一个 listener}
}

功能：

• 调用合适的回调（handleValue/handleError/handleWhenComplete）
• 把回调结果继续传播给下一个 Future

6. _chainCoreFutureSync

static void _chainCoreFutureSync(_Future source, _Future target) {if (source._isComplete) {target._cloneResult(source);_propagateToListeners(target, target._removeListeners());} else {target._setChained(source);source._prependListeners(target._removeListeners());}
}

功能：

• 如果 source Future 已完成，直接拷贝它的结果。
• 如果 source Future 未完成，把 target 链到 source 上等待其完成。

5. 错误信息管理

• AsyncError：统一封装错误与堆栈信息。
• Zone：隔离执行上下文，管理回调与未捕获异常。
  2.4 AsyncError

class AsyncError {final Object error;final StackTrace stackTrace;
}

标准错误封装，用于 Future 错误状态记录与传播。

2.5 Zone相关

• 所有 Future 回调 (then/catchError/whenComplete) 都在注册时的 Zone 执行。
• Future 完成时如果未捕获错误，通过 Zone 的 handleUncaughtError 抛出。