for-await-of 是 ES2018 引入的用于遍历异步可迭代对象的语法，要求目标实现 Symbol.asyncIterator 方法并返回符合异步迭代器协议的 Promise-returning next() 方法，支持 ReadableStream、AsyncGenerator 等，按顺序 await 每次迭代，不可直接用于普通数组或 Promise。
for-await-of 是 JavaScript 中专门用于遍历异步可迭代对象（如 AsyncIterator）的语法，它让处理流式异步数据（比如 ReadableStream、async generator 返回的对象）变得简洁自然。它的核心规范基于 ECMAScript 2018（ES9），要求被遍历的目标必须实现 @@asyncIterator 方法。
必须满足异步可迭代协议
要被 for-await-of 正确消费，对象必须提供 Symbol.asyncIterator 方法，该方法需返回一个符合异步迭代器协议的对象：即拥有 next() 方法，且该方法返回 Promise，Promise 的 resolve 值为 { value, done } 形式。
- 常见原生支持类型：AsyncGenerator 函数返回值、ReadableStream（浏览器和 Node.js 16.5+）、某些数据库驱动的查询游标（如 pg.Cursor）
- 普通 Promise、Array、普通 Generator 不支持直接用于 for-await-of；数组需先转为 async iterable（例如通过 async function* 包装）
- 若对象只有 Symbol.iterator 而无 Symbol.asyncIterator，for-await-of 会抛出 TypeError：“is not async iterable”
语法结构与执行逻辑
其写法与 for-of 类似，但内部自动 await 每次 next() 调用的结果，按顺序等待每个 Promise 解决后再继续下一轮。
- 基本形式：for await (const item of asyncIterable) { ... }
- 每次循环前，引擎调用 asyncIterable[Symbol.asyncIterator]().next()
- await 该 next() 返回的 Promise，解构出 value 并赋给 item，若 done 为 true 则退出循环
- 支持 break、continue、return；遇到 throw 或未捕获异常会终止迭代并沿作用域向上抛出
错误处理与资源清理
异步迭代可能中途失败（如网络中断、流取消），因此需结合 try/catch 和 finally（或显式 return）确保资源释放。
立即学习“Java免费学习笔记（深入）”；
- 在循环内捕获单个项的错误：用 try/catch 包裹循环体
- 捕获整个迭代过程错误（如初始 asyncIterator 抛错、某次 next() 拒绝）：将整个 for-await-of 放入 try/catch
- 需要清理（如关闭流）时，使用 finally 块，或利用 async generator 的 return() 方法（若目标支持）
- 注意：for-await-of 不会自动调用 return()；如需保证 cleanup，建议用封装好的工具函数或显式控制
与普通 for-of 和 Promise.all 的区别
它不是 Promise.all 的替代品，也不等价于手动链式 await。
- for-await-of 是顺序等待：前一项完成才取下一项，适合流式、内存敏感或有依赖关系的场景
- Promise.all 是并发执行所有 Promise，适合独立、可并行的任务，但会一次性加载全部结果到内存
- 手动 await 配合 while 循环也能实现类似效果，但 for-await-of 更声明式、更安全（自动处理 done、兼容迭代器协议）
