
前言
买菜时,我们可以先写好一张清单,再一项一项检查;也可以边走边看,找到需要的东西就记下来。两种方式都能得到一张清单,但做事的时机不同:前者先准备结果,后者需要某一项时才处理某一项。
Dart 里的 Iterable 就像"可以逐项查看的清单"。它不一定是一张已经准备好的 List,也可能是一套等到有人读取时才计算的规则。sync* 生成器则能把这套规则写成"每次交出一个值"的函数。
理解这一点后,where、map、take 为什么可以连在一起,为什么只取第一个结果时不用处理全部数据,以及 async* 为什么返回的是 Stream,就都有了清楚的原因。
一、Iterable:可以逐项读取的一组值
1.1 先看定义
Iterable 表示一组可以按顺序逐项读取的值。 这里的"按顺序"是读取方式,不是说它一定支持下标,也不是说它一定能修改。 Iterable
List 是最常见的 Iterable:
dart
void main() {
final names = <String>['林', '周', '吴'];
Iterable<String> readable = names;
print(readable.first); // 林
print(readable.length); // 3
print(readable.join('、')); // 林、周、吴
}
names 的实际类型是 List<String>,但放进 Iterable<String> 变量后,代码只依赖"能够逐项读取"这部分能力。Iterable 没有要求所有实现都提供 []、add 或 remove,所以不能因为某个对象能遍历,就假定它一定是一张可修改的列表。
可以把几种类型先这样区分:
| 类型 | 主要表示什么 | 常见能力 |
|---|---|---|
| Iterable<T> | 可以逐项读取的值 | for-in、first、where、map |
| List<T> | 有顺序、可按位置访问的一组值 | []、add、remove |
| Set<T> | 不重复的一组值 | 查找和逐项读取,不能按下标取值 |
| Stream<T> | 随时间到来的异步值 | 异步监听、暂停、取消 |
把类型写成 Iterable<T>,是在表达"调用者只需要逐项读取"。 如果调用者确实需要按下标修改,才应该让它看到 List<T> 或更具体的接口。
1.2 for-in 是怎样读取的
for-in 不是一次把所有值变成另一张列表,而是通过迭代器逐项取得:
dart
void main() {
final names = <String>['林', '周', '吴'];
for (final name in names) {
print('读取:$name');
}
}
可以把它理解成三个动作:
- 取得这组值的迭代器;
- 询问还有没有下一项;
- 有就取出这一项,执行循环体,然后继续询问。
大多数时候不需要手写迭代器。这里写出底层概念,是为了说明 Iterable 的重点是"怎样逐项提供值",而不是"内部一定存着一张数组"。
二、惰性 Iterable:调用方法不等于马上算完
2.1 map 先保存规则
惰性 Iterable 会先保存处理规则,等到真正读取时才执行规则。 where、map、take、skip 等常用操作通常会返回惰性 Iterable。
dart
void main() {
final numbers = <int>[1, 2, 3];
final doubled = numbers.map((number) {
print('计算 $number');
return number * 2;
});
print('已经创建 doubled');
print(doubled.first);
}
输出顺序是:
text
已经创建 doubled
计算 1
2
创建 doubled 时,没有打印"计算 1"。直到读取 doubled.first,Dart 才从 numbers 取第一项,执行转换,并在得到第一个结果后停止。
这和下面的写法不同:
dart
void main() {
final numbers = <int>[1, 2, 3];
final doubled = numbers.map((number) {
print('计算 $number');
return number * 2;
}).toList();
print('已经创建 doubled');
print(doubled.first);
}
这里 toList() 必须创建一张完整的新列表,所以会先计算 1、2、3,然后才打印"已经创建 doubled"。
map 不负责把结果装进新列表;它负责描述"每个输入怎样变成一个输出"。 需要完整结果时再调用 toList(),可以明确表达这个需求。
2.2 惰性不等于缓存
惰性 Iterable 通常不会自动记住上一次遍历的结果。每次重新遍历,都可能重新执行处理函数:
dart
void main() {
final numbers = <int>[1, 2, 3];
final doubled = numbers.map((number) {
print('计算 $number');
return number * 2;
});
print(doubled.first);
print(doubled.last);
}
第一次读取 first 至少需要计算到 1。第二次读取 last 又要从头找到最后一项,因此可能再次计算 1、2、3。不要把发送请求、写文件或修改外部变量等有副作用的操作随便放进惰性转换里,再假定它只会执行一次。
如果结果需要重复使用,可以主动物化:
dart
void main() {
final numbers = <int>[1, 2, 3];
final doubled = numbers.map((number) => number * 2).toList();
print(doubled); // [2, 4, 6]
}
此时转换在 toList() 处完成,后续读取 doubled 不会再次调用 map 的转换函数;代价是保存完整结果,需要相应内存。

2.3 输入改变时也要看实现
惰性操作通常会在遍历时读取来源。因此,如果来源是一张后来还能修改的列表,重新遍历时可能看到新的内容:
dart
void main() {
final numbers = <int>[1, 2];
final doubled = numbers.map((number) => number * 2);
numbers.add(3);
print(doubled.toList()); // [2, 4, 6]
}
这里没有在创建 doubled 时复制 numbers。需要固定快照时,应该在合适的时机调用 toList();需要跟随来源变化时,才保留惰性关系。关键是明确数据应该"固定下来"还是"读取时再看"。
三、把处理步骤连起来:where、map、take 和 skip
3.1 每一步分别做什么
处理一批数据时,常见的四个操作可以这样记:
- where:留下满足条件的项;
- map:把每一项转换成另一种结果;
- take:最多取前几项;
- skip:跳过前几项,再读取后面的内容。
dart
void main() {
final prices = <int>[8, 15, 23, 31, 42];
final labels = prices
.where((price) => price >= 20)
.map((price) => '价格:$price 元')
.take(2);
print(labels.toList()); // [价格:23 元, 价格:31 元]
}
这里的顺序不是装饰:
- 先检查价格是否至少为 20;
- 对留下的价格生成文字;
- 只取前两条;
- toList() 把最终结果保存成列表。
如果把 take(2) 放在 where 前面,就会先只看 8 和 15,之后没有符合条件的项,结果会变成空列表。链式调用中,前一步输出的是什么,决定后一步能看到什么。
3.2 为什么只处理到 31
这条链是惰性的。为了得到前两条符合条件的结果,程序会读取 8、15、23、31;得到第二条后,take(2) 就结束了,不需要再读取 42。
可以把它看成一条传送带:
text
8 ──> where:丢弃 ──> 不再进入后面
15 ─> where:丢弃 ──> 不再进入后面
23 ─> where:保留 ──> map ──> take:第 1 条
31 ─> where:保留 ──> map ──> take:第 2 条 ──> 停止
42 ─> 尚未读取

这不是说所有操作都能提前停止。last 需要知道最后一项,toList() 需要完整结果,length 通常也需要遍历全部来源。是否能少读数据,取决于链中最终的操作和每个步骤的语义。
3.3 skip 只改变开始位置
dart
void main() {
final names = <String>['林', '周', '吴', '郑'];
final later = names.skip(2);
print(later.toList()); // [吴, 郑]
}
skip(2) 不会把前两项删除,也不会修改 names。它只是在遍历这个结果时,先跳过两个值。
类似地,take(2) 也不会修改来源。Iterable 的链式方法通常返回新的读取视图;如果需要改变 List,本身应使用 List 的修改方法,不能把 where 或 skip 当成删除操作。
四、哪些操作会真正遍历来源
4.1 读取一个值和读取全部值
惰性只是延后计算,不是永远不计算。下面这些操作会触发读取:
- first、single 等需要找到特定结果的操作;
- last、length 等通常要继续看到后面的内容;
- toList()、toSet() 等需要生成完整集合的操作;
- for-in、forEach() 等逐项执行的操作;
- join()、reduce() 等需要综合多个值的操作。
dart
void main() {
final values = <int>[4, 7, 9];
final even = values.where((value) {
print('检查 $value');
return value.isEven;
});
print(even.first);
}
输出只检查 4,就得到第一个偶数。若把最后一行改成 print(even.toList());,三个值都会被检查。
single 还会继续检查,确认整个来源只有一个符合条件的值;不能看到第一项就立即结束。遇到空结果或多个结果时,它会抛出异常。选择操作时,要把"我要第一个""我要全部""我要确认只有一个"说清楚。
4.2 多次遍历的边界
同一个惰性结果可以被遍历多次,但每次遍历都可能重新读取来源:
dart
void main() {
final source = <int>[1, 2, 3];
final result = source.map((value) {
print('处理 $value');
return value + 10;
});
print(result.toList());
print(result.toList());
}
两次 toList() 都会触发处理。若转换很耗时,或来源会变化,这一点尤其重要。想要一次计算、多次读取,就在第一次需要时保存 toList() 的结果。
五、用 sync* 写一个同步生成器
5.1 先理解生成器在做什么
生成器函数不是一次性返回一张完整集合,而是按规则逐个交出值。 同步生成器使用 sync*,返回类型通常是 Iterable<T>。 生成器函数
dart
Iterable<int> countdown(int start) sync* {
for (var value = start; value >= 1; value--) {
yield value;
}
}
void main() {
final values = countdown(3);
print(values.first); // 3
print(values.toList()); // [3, 2, 1]
}
yield 可以理解成"先把当前值交出去,调用者需要下一项时再继续"。调用 countdown(3) 得到的是一个 Iterable<int>,函数体不会像普通函数那样立刻执行完整流程。
第一次读取 first 时,函数交出 3 就停下。之后再次遍历 values,生成器会重新开始一轮生成,所以又能得到 3、2、1。生成器结果同样要注意是否重复计算。
5.2 生成器必须能结束
生成器中的循环必须有结束条件,或者调用者必须通过 take 等操作只读取有限项:
dart
Iterable<int> positiveNumbers() sync* {
var value = 1;
while (true) {
yield value++;
}
}
void main() {
final firstFive = positiveNumbers().take(5).toList();
print(firstFive); // [1, 2, 3, 4, 5]
}
如果直接对 positiveNumbers() 调用 toList(),它会一直等待更多值,无法得到完整列表。无限生成器不是错误,但必须搭配明确的停止条件,例如 take(5)。
写 sync* 时要同时回答:第一项是什么?下一项怎样产生?什么时候结束?
5.3 生成器可以表达更复杂的规则
集合 for 适合短小的生成逻辑;当规则需要多个判断、递归或复用其他来源时,生成器更容易读懂:
dart
Iterable<String> availableSeats(
int rowCount,
int seatsPerRow,
) sync* {
for (var row = 1; row <= rowCount; row++) {
for (var seat = 1; seat <= seatsPerRow; seat++) {
yield '$row-$seat';
}
}
}
void main() {
print(availableSeats(2, 3).toList());
// [1-1, 1-2, 1-3, 2-1, 2-2, 2-3]
}
这里没有先创建所有座位的中间列表。每次读取时,生成器计算一个座位并交出它;调用者决定读取一个、几个,还是全部。
六、yield*:把另一组值接到当前生成器后面
6.1 转发一组 Iterable
yield* 会逐项转发另一个 Iterable 的内容。 它不是把整张列表作为一个值交出去:
dart
Iterable<String> languages() sync* {
yield 'Dart';
yield* <String>['Flutter', 'Android'];
yield 'C#';
}
void main() {
print(languages().toList()); // [Dart, Flutter, Android, C#]
}
如果写成 yield <String>['Flutter', 'Android'];,生成器的元素类型就会变成 Object 或 Object? 一类,结果中会出现一张列表作为一项;yield* 表达的是"把里面每一项依次转发"。
yield* 也会保留来源的读取时机,不会为了转发而自动把来源先复制成另一张列表。
6.2 递归生成器需要结束条件
递归生成器适合表达"先给当前值,再生成更小问题"的规则:
dart
Iterable<int> downFrom(int value) sync* {
if (value < 1) {
return;
}
yield value;
yield* downFrom(value - 1);
}
void main() {
print(downFrom(4).toList()); // [4, 3, 2, 1]
}
value 小于 1 时直接结束;否则先交出当前值,再把 value - 1 的结果接在后面。如果忘记结束条件,递归就不会停止,读取结果时会抛出错误或持续消耗资源。
yield* 右侧必须提供与当前生成器元素类型相容的 Iterable。它适合"把另一组同类值接进来",不适合把一张列表当作单个业务对象交出去。
七、同步生成器和异步生成器不是一回事
7.1 sync* 返回 Iterable
同步生成器的每个值,是调用者在当前遍历中请求时交出的:
dart
Iterable<int> syncValues() sync* {
yield 1;
yield 2;
}
void main() {
for (final value in syncValues()) {
print(value);
}
}
它适合已经在内存中,或可以同步计算得到的值。for-in 可以读取它。
7.2 async* 返回 Stream
异步生成器使用 async*,返回 Stream<T>。它可以在 yield 之间等待异步操作:Dart 中的并发模型
dart
Stream<int> asyncValues() async* {
await Future<void>.delayed(const Duration(milliseconds: 10));
yield 1;
await Future<void>.delayed(const Duration(milliseconds: 10));
yield 2;
}
Future<void> main() async {
await for (final value in asyncValues()) {
print(value);
}
}
这里的值不是通过普通 for-in 读取,而是通过 await for 监听。Stream 还涉及事件到达时间、暂停、取消和错误传播等异步行为。
可以用下面的表格记住边界:
| 写法 | 返回类型 | 值什么时候产生 | 读取方式 | 适合场景 |
|---|---|---|---|---|
| 普通函数返回 List<T> | List<T> | 函数返回前通常已构建结果 | 下标、for-in | 需要保存完整结果 |
| 普通函数返回 Iterable<T> | Iterable<T> | 由实现决定 | for-in 等 | 提供逐项读取接口 |
| sync* | Iterable<T> | 遍历请求某项时 | for-in、first 等 | 同步规则生成 |
| async* | Stream<T> | 异步事件准备好时 | await for、监听 | 定时器、文件、网络等 |
async* 不是"更慢的 sync*",Stream 也不是"会等待的 Iterable"。两者的读取协议不同:一个在同步遍历中交值,一个在异步事件流中发值。

7.3 选择哪一种
可以先问三个问题:
- 值是否已经能在当前调用中同步得到?
- 调用者是否只需要逐项读取,还是要等待未来事件?
- 是否需要保存完整结果,还是希望读到需要的数量就停止?
如果答案是"同步、逐项读取、可以按需停止",优先考虑 Iterable 或 sync*。如果值要等待异步操作、可能随时间陆续到来,考虑 Stream 或 async*。如果后续要按下标重复访问,或者需要固定快照,调用 toList() 得到列表。
八、总结
Iterable 描述的是逐项读取能力。List、Set 和许多处理方法都可以提供 Iterable,但 Iterable 本身不承诺下标访问和修改。
where、map、take、skip 通常是惰性的:创建处理链时先保存规则,真正遍历时才计算。first 可能只读到第一个结果,toList() 则会要求完整遍历;多次遍历可能重复计算,想缓存就主动物化。
sync* 用 yield 逐项生成同步值,yield* 把另一组 Iterable 的内容依次转发。生成器要有明确的结束条件,或者由调用者用 take 限制读取范围。
async* 返回 Stream,通过 await for 或监听异步事件。选择 Iterable、列表、生成器还是 Stream,取决于值的产生时间、调用者的读取方式,以及是否需要保存完整结果。
九、测试题
- List<String> 为什么可以赋给 Iterable<String>?赋值以后,为什么不能只凭 Iterable 类型调用 add 和下标写入?
- 创建
numbers.map(...)时,转换函数是否已经执行?什么操作会让它开始执行? - 为什么对同一个惰性 Iterable 调用两次 toList(),转换函数可能执行两次?怎样得到一次计算、多次读取的结果?
where(...).map(...).take(2)中,如果把 take(2) 放到 where 前面,结果为什么可能不同?- 对
values.where(...)使用 first 和 toList(),它们读取来源的范围有什么区别? - sync* 函数中的 yield 与普通函数中的 return 有什么不同?调用生成器函数时,函数体是否一定立即执行完?
- 无限生成器为什么可以定义?直接调用 toList() 会发生什么?怎样安全地读取前五项?
yield <String>['Flutter', 'Android']与yield* <String>['Flutter', 'Android']的结果结构有什么区别?- sync* 和 async* 分别返回什么类型?它们对应的遍历方式为什么不同?
- 一个数据源需要等待网络响应并陆续产生结果,另一个数据源是内存中的整数计算。分别应该考虑 async*/Stream 和 sync*/Iterable 的哪一种?为什么?