在Swift并发编程中，异步序列常用来表示随时间到达的数据流，比如网络响应分块、传感器读数或文件行。迭代这些序列时，除了元素本身，往往还需要知道当前是第几个元素。标准库提供了enumerated()方法，调用后元素被包装为偏移量和值，但带错误场景下的类型名称AsyncThrowingEnumeratedSequence常常被忽视。其实它的职责很明确：为序列元素添加索引，同时不破坏错误传播路径。
一、AsyncSequence的enumerated()做了什么
Swift的AsyncSequence协议为异步迭代提供统一抽象。只要一个类型满足协议要求，就能使用for try await循环逐项消费。许多标准库类型像AsyncStream、AsyncThrowingStream以及文件读取产生的行序列都遵循该协议。调用enumerated()之后，迭代元素会从原来的单个值变成一个元组，元组的第一个成员是从0开始的整数索引，第二个成员是原始值。
这里有一个容易混淆的地方：如果底层序列的迭代器可能抛出错误，enumerated()返回的包装类型就是AsyncThrowingEnumeratedSequence。它并不是一个独立协议，而是一个泛型结构体，内部持有基序列的迭代器。每次消费者请求下一个元素时，它先通过基迭代器获取原始值，如果成功则把当前偏移量与该值组成元组返回，然后把偏移量加一；如果基迭代器抛出错误，该错误会原样继续抛出，不会被包装层捕获或转换成其他错误。
let stream = AsyncStream<String> { continuation in
continuation.yield("apple")
continuation.yield("banana")
continuation.finish()
}
for try await (index, value) in stream.enumerated() {
print("\(index): \(value)")
}
运行这段代码会依次输出0: apple和1: banana。注意索引是偏移量，不是元素本身的某个属性。即使异步序列里已经包含位置信息，enumerated()也会重新从0开始计数。这个设计对有错误处理需求的解析任务很有用，因为行号、记录号之类的逻辑通常与元素在流中的顺序一致。
特别强调，该方法是惰性的。也就是说，索引只在元素真正被请求时才生成，不存在预先构建整个索引数组的情况。异步序列可能无限长或非常庞大，惰性求值可以避免内存浪费。
二、AsyncThrowingEnumeratedSequence的错误传播机制
如果只是简单循环，错误处理看起来和普通AsyncSequence没有差别。但要理解为什么需要一个专门的Throwing枚举类型，需要观察异步迭代器协议。异步迭代器的next()方法通常声明为async throws，这意味着任何异步序列都可能抛出错误。AsyncThrowingEnumeratedSequence的迭代器next()也会调用底层next()，并保持throws签名。因此，错误在枚举层不会被打断。
下面是一个会抛错的异步流。它先产出两个正常元素，然后在第三个元素的位置结束并抛出自定义错误。我们通过enumerated()拿到索引，同时用do/catch捕获错误。
enum LoadError: Error {
case failed
}
func failingStream() -> AsyncThrowingStream<String, Error> {
AsyncThrowingStream { continuation in
continuation.yield("first")
continuation.yield("second")
continuation.finish(throwing: LoadError.failed)
}
}
do {
for try await (index, value) in failingStream().enumerated() {
print("\(index): \(value)")
}
} catch {
print("Caught: \(error)")
}
输出会包含0: first、1: second，随后抛出LoadError.failed，循环终止并进入catch分支。可以看到，索引0和1正常对应前两个元素，错误发生在尝试读取第三个元素时。此时序列的当前偏移量已经增加到2，但由于错误抛出，调用方拿不到该索引对应的值。这个细节很重要：如果你在循环外部记录index，需要在循环内部及时保存，否则错误发生后索引变量可能还未更新到最新值。
另一个常见误区是试图在for try await内部使用try捕获某个元素处理错误，却忽略了序列本身的next错误。比如解析函数validate可能抛出错误，这属于业务错误；而异步读取过程中断则属于序列错误。两者都会终止循环，但来源不同。使用enumerated()时，你仍然要区分try await、try和catch的组合，避免把序列错误吞在循环体内。
如果想把序列错误和元素处理错误统一到行号上下文，可以在外层async throws函数中不捕获，让错误连同当前索引一起抛给更上层。也可以自定义一个ParseError，把底层错误作为关联值保存。
三、实战：带索引解析异步日志行
假设一个日志服务按行读取远程文件，异步序列每产生一行文本。处理过程中需要输出出错行号，那么可以用enumerated()代替手动维护计数器。手动方案通常是在循环外声明一个变量，每次迭代加一。但这种方式容易在continue、break或错误抛出时漏更新，而且如果同一个序列被多个消费者共享，计数可能互相干扰。enumerated()把索引和元素绑定在同一个元组里，索引的正确性由标准库保证。
struct LogParser {
let lines: AsyncThrowingStream<String, Error>
func parse() async throws {
do {
for try await (index, line) in lines.enumerated() {
let lineNumber = index + 1
guard !line.isEmpty else { continue }
try validate(line: line, number: lineNumber)
}
} catch {
throw ParseError.failed(cause: error)
}
}
func validate(line: String, number: Int) throws {
if line.contains("fatal") {
throw ParseError.fatalLine(number)
}
}
}
enum ParseError: Error {
case failed(cause: Error)
case fatalLine(Int)
}
在这个例子里，index是零基偏移，转换为人类习惯的行号需要加一。循环内部使用continue跳过空行，不会影响后续索引，因为enumerated()已经为下一次迭代准备好了递增后的值。validate抛出的错误同样会让循环终止，如果该错误没有被内部捕获，会进入catch块并包装成ParseError.failed。如果需要保留行号，可以定义更具体的错误类型，比如ParseError.fatalLine(Int)，以便调用方知道是哪一行。
这种方式对比手动维护计数器的好处是，代码不需要额外状态，逻辑更紧凑。而且异步序列可能由多个生产者同时写入，手动index变量在并发消费时并不安全。虽然索引是在单一消费循环中顺序递增，但TaskGroup并发场景下，多个任务同时迭代同一个序列通常不被允许或需要额外同步，enumerated()的内部计数器也有类似限制。最稳妥的做法仍是一个任务负责一个序列实例。
如果异步序列不是抛错类型，也可以使用enumerated()，但包装类型可能是AsyncEnumeratedSequence，索引行为一致。本文重点讨论抛错场景，因为错误传播路径容易被忽略。有些开发者会试图在AsyncSequence扩展中自定义一个带索引方法，但标准库已经提供了现成能力，直接使用可以减少测试成本和维护负担。
AsyncSequenceAsyncThrowingEnumeratedSequenceSwift并发修改时间：2026-10-06 12:32:25