关于Flutter.await操作符使用详解

一、 简介

flutter中关于wait操作符，堪称神器，但是如果不了解其具体实现原理，就很难巧妙的运用好这个操作符，所以很多人只会简单用来收集多个并发调用的结果。

二、参数介绍

• wait(Iterable futures，{bool eagerError = false, void cleanUp(T successValue)?})
  • Iterable futures 这个参数应该大多数人都知道，而且大多数都只用这一个参数。就是一个Future的数组，你把所有的Future函数都放这个数组里。
  • eagerError 这个参数很少人用，它用于是否需要立即返回error。eagerError为ture时，这个error是futures中任何一个接口发生错误了，就立即获得error。但是不会中断其它futures中未执行完的函数继续执行；当eagerError为false时，会等所有的futures都执行完之后，才会把futures中发生的第一个error发出来。
  • void cleanUp(T successValue)?这是一个Fuction，从命名上看，是清除的意思，不看源码其实很难理解清除什么。这个在实际使用的时候，只有在futures中至少有一个future发生了error才会执行这个方法。这个方法中可以获取到所有执行成功那部分future的value。
• 值得注意的是： Future.wait（）这个操作符中所有futures，当它们发生错误时，只会返回第一个error，也就是超过2个接口报错了，你只能拿到第一个接口的错误。

三、源码解析

1. 源码框架

static Future<List<T>> wait<T>(Iterable<Future<T>> futures,
      {bool eagerError = false, void cleanUp(T successValue)?}) {
    final _Future<List<T>> _future = _Future<List<T>>();
    List<T?>? values; // 一个用于存放value的集合，如果是error,则存null
    int remaining = 0; // 可以理解为futures顺序执行的队列大小。
    late Object error; // 用于存放futures中第一个发生的错误
    late StackTrace stackTrace; // 用于存放这个是和error对应的错误的方法调用栈
    //这是个内部方法，用于处理错误
    void handleError(Object theError, StackTrace theStackTrace) {
      remaining--;
  	  xxx....
  	  //这里省略部分代码
  	  xxx.....
    }

    try {
      for (var future in futures) {//遍历需要调用的方法，给每个future添加then回调。
        int pos = remaining;//把对应的下标记录下来，再下面的then中需要使用
        future.then((T value) {
          remaining--;
          xxx....
  	  	 //这里省略部分代码
  	  	  xxx.....
        }, onError: handleError);
        remaining++;//队列总数+1
      }
      if (remaining == 0) { //futures列表为空或者，直接结束
        return _future.._completeWithValue(<T>[]);
      }
      values = new List<T?>.filled(remaining, null);//初始化一个大小为remaining的数组容器。用于存放所有futures的value
    } catch (e, st) {
     xxx....
     //省略部分代码
     xxx....
    }
    return _future;
  }

1. 从代码大体框架可以看出，首先第一步是按照数组futures中的顺序给每个future添加一个then操作符，并且创建一个values用来存放所有futures中的value。并且声明了两个局部变量error和stackTrace，用于存放futures发生的第一个错误的error以及方法调用栈。
2. 如果futures数组为空，则直接结束这个Future。

2. 内部函数handleError方法的逻辑

 	 void handleError(Object theError, StackTrace theStackTrace) {
      remaining--;
      List<T?>? valueList = values;
      if (valueList != null) {
        if (cleanUp != null) {
          for (var value in valueList) {
            if (value != null) {
              // Ensure errors from cleanUp are uncaught.
              T cleanUpValue = value;
              new Future.sync(() {
                cleanUp(cleanUpValue);
              });
            }
          }
        }
        values = null;
        if (remaining == 0 || eagerError) {
          _future._completeError(theError, theStackTrace);
        } else {
          error = theError;
          stackTrace = theStackTrace;
        }
      } else if (remaining == 0 && !eagerError) {
       //省略部分代码
      }
    }

这部分代码逻辑也很简单清晰。

1. 将所有的values值通过cleanUp的回调发送出去，当所有的values都发送完毕之后，values赋null值，
2. 第二个if以下有3种情况
   a. 如果所有的futures都执行完了，将error抛出去，
   b. eagarError为true时，将发生的error直接输出，
   c. 以上两个条件都满足了，那肯定也error直接抛出去了。
3. 如果不需要futures没有执行完，且不需要立即把error抛出，则将error缓存下来。看到这个地方时，肯定有一个疑问。如果futures中发生第二个错误的时候，也满足eagerError为false并且futures还没执行完时，第二个error信息岂不是会覆盖之前的缓存，这个和之前定义的error只会输出第一个有点相违背呀。继续往下看。

void handleError(Object theError, StackTrace theStackTrace) {
      remaining--;
      List<T?>? valueList = values;
      if (valueList != null) {
       //省略部分代码
      } else if (remaining == 0 && !eagerError) {
        _future._completeError(error, stackTrace);
      }
    }

这里把前面if内的代码屏蔽，这样看着更清晰一点。逻辑很简单，在某种条件下将error信息抛出。具体条件如下：
首先 因为第一个错误发生的时候，在if内部已经将values赋值为null了，所以第二个错误发生的时候，就会走这个else的逻辑了。
其次，这个else中又添加了2个条件。所有的futures没有执行完并且eagerError这个参数为false（也就是不需要立即抛出error）。这不就是恰巧回答了上面那个疑问么。
因此， 当第二个及以后error发生的时候，都被这个handler自己吃掉了，不会再往外抛。

3. then函数中if逻辑

future.then((T value) {
          remaining--;
          List<T?>? valueList = values;
          if (valueList != null) {
            valueList[pos] = value;
            if (remaining == 0) {
              _future._completeWithValue(List<T>.from(valueList));
            }
          } else {
           //省略部分代码
          }
        }, onError: handleError);

这部分逻辑也很清晰，pos在前面描述过，记录了futures的对应位置。就是按照futures的顺序将所有的value添加到values中，没添加完一个就remaining减一，直到remaining为0，则表示所有的future中的value都添加完了，最后把这个values列表通过_completeWithValue下发一个数组。
换个角度说Future.wait().then(value =>{})中获取到的这个value会是个数组，数组里面所有元素的顺序和futures中每个方法的顺序是一样的。

4. then中else的逻辑

future.then((T value) {
          remaining--;
          List<T?>? valueList = values;
          if (valueList != null) {
           //省略部分代码
          } else {
            if (cleanUp != null && value != null) {
              new Future.sync(() {
                cleanUp(value);
              });
            }
            if (remaining == 0 && !eagerError) {
              _future._completeError(error, stackTrace);
            }
          }
        }, onError: handleError);

当这个values为null时，将当前的value通过cleanUp直接输出。也就是在前面提到的，cleanUp回调函数中可以获取到对应future的value。
前面在handlerError中有提到，当future中发生error的时候，如果eagerError为true，则values就会被赋值为null，所以当发生error之后所有的value就不会被缓存了，会直接通过cleanUp的方式往外输出。

如果eagerError为false时，

 if (remaining == 0 && !eagerError) {
     _future._completeError(error, stackTrace);
 }

这段代码就会执行，输出之前缓存的error。

四、结语

1. 参数Iterable futures中所有的future是按顺序执行的
2. 当其中一个或者多个future发生错误时，会根据eagerError参数判断是会否缓存第一个error和它的堆栈信息
   a.eagerError 为ture，发生错误之后就会把之前所有的已经执行完的future的value，通过cleanUp清除，并且在这个回调函数中可以获取到
   b. eagerError 为false，则会把第一个错误的error及相关信息缓存下来。直到所有future执行完了之后，通过clean Up回调输出所有的value，最后输出error及相关信息。
3. 至于所有的future都成功执行之后，才会走then回调。