在Swift并发模型中，AsyncSequence提供了一种以for-await方式消费异步产生值的统一接口。当我们需要把一个同步或异步序列里的每一个元素，都转换成一个独立的异步序列，并且希望把这些子序列里产生的值合并到同一个遍历流程中时，AsyncThrowingFlatMapSequence就派上了用场。它是标准库通过AsyncSequence协议扩展提供的扁平映射能力，专门处理可能抛出错误的映射函数。
AsyncSequence与扁平映射的基本机制
AsyncSequence的核心是定义了一个异步迭代器，调用方通过for try await逐步获取元素。普通的map操作会把每个元素转换成一个新值，但转换函数如果是异步的且返回另一个AsyncSequence，直接map会得到“序列的序列”，遍历起来十分麻烦。此时就需要展平操作：把内层序列的值逐个抽取出来，在外层序列的维度上依次暴露。
AsyncThrowingFlatMapSequence正是为此设计。它的构造通常来自这样的调用链：某个基础AsyncSequence调用flatMap方法，传入一个(Element) async throws -> some AsyncSequence的闭包。系统会返回一个AsyncThrowingFlatMapSequence实例，它在被迭代时，先取出外层的一个元素，执行闭包得到内层序列，然后把内层序列迭代完，再继续下一个外层元素。由于闭包标记了throws，整个展平序列在迭代中遇到任何错误都会直接抛出给外层消费者。
这种设计相比传统的Combine框架或回调嵌套，优势在于取消了隐式状态机。开发者不需要手动维护一组进行中的任务数组，也不需要在回调里拼接结果。下面是一个将数字序列映射为延迟 emitting 的异步序列并展平的最小示例：
import Foundation
struct NumberDelaySequence: AsyncSequence {
typealias Element = Int
let base: Int
func makeAsyncIterator() -> Iterator {
Iterator(base: base)
}
struct Iterator: AsyncIteratorProtocol {
let base: Int
var count = 0
mutating func next() async -> Int? {
if count >= 3 { return nil }
try? await Task.sleep(nanoseconds: 100_000_000)
let val = base * 10 + count
count += 1
return val
}
}
}
let source = [1, 2].async
let flattened = source.flatMap { n in
NumberDelaySequence(base: n)
}
for try await val in flattened {
print(val)
}
上面的代码里，source是两个整数的异步序列，flatMap之后每个整数生成一个发射三个值的子序列。最终打印出来的是1开头的三个值和2开头的三个值顺序相连。注意这里虽然示例闭包没抛错，但flatMap返回类型依然兼容错误传递。
错误处理与任务取消的传播路径
AsyncThrowingFlatMapSequence名字里的Throwing不是装饰，它意味着映射闭包可以抛错，且内层异步序列的迭代过程抛出的任何错误，都会中断整个展平序列的遍历。这和同步序列的flatMap不同，后者如果遇到错误通常需要在闭包内部捕获。在异步场景，如果某个内层序列因为网络失败而抛出，外层的for try await会接收到该错误并跳出循环，未开始的后续外层元素不再处理。
从结构化并发视角看，展平序列在迭代内层序列时，迭代器内部会持有当前内层任务的引用。当外部Task被取消，例如用户离开页面触发了Task.cancel()，正在sleep或等待IO的内层序列会收到取消信号，next()方法应当抛出CancellationError或提前返回nil。由于AsyncThrowingFlatMapSequence本身建立在Swift并发原语上，取消可以自然沿调用栈向上传递，不需要开发者写额外的超时清理逻辑。
为了演示错误传播，我们看一段故意让第二个元素映射失败的逻辑：
enum DemoError: Error { case boom }
let badSource = [1, 2, 3].async
let badFlatten = badSource.flatMap { n -> AsyncThrowingStream<Int, Error> in
if n == 2 {
return AsyncThrowingStream { throw DemoError.boom }
}
return AsyncThrowingStream { c in
c.yield(n)
c.finish()
}
}
do {
for try await v in badFlatten {
print(v)
}
} catch {
print("捕获到错误: (error)")
}
运行后控制台会先输出1，随后在迭代到第二个外层元素时立即进入catch块，数字3永远不会被处理。这种 Fail-fast 特性在批量拉取接口时非常有用：只要有一个关键子任务失败，整体批次即刻终止，避免产生半成品数据。
背压表现与内存占用对比
很多开发者担心展平操作会把所有内层序列同时启动，导致内存暴涨。实际上AsyncThrowingFlatMapSequence采用的是“顺序展平”策略：它一次只迭代一个外层元素对应的内层序列，内层没迭代完不会去取下一个外层元素，也不会并发启动所有子序列。这天然形成了一种背压，消费者处理得慢，源序列和被映射出的子序列都会暂停前进。
这与使用TaskGroup手动并发收集结果形成鲜明对比。如果在TaskGroup里为每个元素spawn一个子任务并把结果存入数组，那么所有异步序列会真正并行，内存中同时存在的未完成任务数等于元素个数。下面的表格列出了两者差异：
| 方案 | 并发度 | 错误行为 | 取消传播 |
|---|---|---|---|
| AsyncThrowingFlatMapSequence | 顺序展平，单内层活跃 | 首次错误即终止 | 自动沿迭代器 |
| TaskGroup手动收集 | 全部并行 | 可单独忽略部分错误 | 需显式监听 |
如果你的业务要求“所有子任务并行且容错”，那么就不该用flatMap，而应选TaskGroup。但若业务是“依次处理每个元素的附属流，且任一失败则全停”，AsyncThrowingFlatMapSequence既省代码又安全。理解这一点，才能在Swift并发编程里正确选型，而不是盲目追求高并发。
最后补充一点使用细节：由于展平序列是惰性求值的，映射闭包只有在外层元素被迭代到时才会执行。因此如果闭包内部捕获了大对象，要注意它的生命周期会延续到对应内层序列迭代结束。合理设计闭包捕获列表，可以减少不必要的引用持有，让异步序列在长时间运行中更平稳。
AsyncSequenceAsyncThrowingFlatMapSequence异步序列展平修改时间：2026-08-14 18:33:33