C#异步流核心是IAsyncEnumerable<T>+yield return+async方法，因Task<IEnumerable<T>>会阻塞等待全量加载，导致内存暴涨和延迟高，而IAsyncEnumerable<T>支持逐项异步生成与消费，内存恒定且天然支持取消。
直接说结论： C# 中实现异步流处理，核心是 IAsyncEnumerable<T> + yield return + async 方法，不是 Task<IEnumerable<T>>，也不是手动包装 Stream。用错类型会导致阻塞、内存暴涨或编译报错。
为什么不能用 Task<IEnumerable<T>> 替代 IAsyncEnumerable<T>
这是最常踩的坑：把“异步获取一批数据”误当成“异步流”。Task<IEnumerable<T>> 会等全部数据加载完才返回整个集合，失去流式优势；而 IAsyncEnumerable<T> 允许逐项生成、逐项消费，内存恒定，且支持自然取消。
- 典型错误现象：
OutOfMemoryException处理百万行 CSV 或数据库游标时 - 实际场景：读取大文件分块解析、监听实时日志管道、分页调用 API 流式聚合
- 性能影响：前者延迟高、GC 压力大；后者可控制每批次大小（如
await foreach内部自动 await 每次MoveNextAsync）
如何正确声明和返回 IAsyncEnumerable<T>
必须用 async 修饰符 + yield return，且返回类型严格为 IAsyncEnumerable<T>（不是 AsyncEnumerable<T>，后者是内部类型）。
- 编译器会把含
yield return的async方法编译为状态机，生成真正的异步迭代器 - 禁止在普通
Task方法里 new 一个AsyncEnumerable<T>—— 没有公开构造函数，也不该手动构造 - 示例正确写法：
async IAsyncEnumerable<string> ReadLinesAsync(string path, CancellationToken ct = default) { await using var fs = File.OpenRead(path); await using var reader = new StreamReader(fs); string line; while ((line = await reader.ReadLineAsync(ct)) != null) { yield return line; // 关键：yield return 必须在 async 迭代器方法内 } }
消费端必须用 await foreach，不能用普通 foreach
await foreach 是 C# 8.0+ 引入的专用语法，它隐式调用 GetAsyncEnumerator 并处理 DisposeAsync。用普通 foreach 会编译失败（CS8411）。
- 错误写法：
foreach (var item in source)→ 报错：error CS8411: 'await foreach' requires a suitable public instance or extension method 'GetAsyncEnumerator' - 正确写法：
await foreach (var line in ReadLinesAsync("log.txt")) { Process(line); } - 注意：若需提前退出或取消，传入
CancellationToken到迭代器方法，并在yield return前检查ct.ThrowIfCancellationRequested()
常见兼容性陷阱和绕过方案
.NET Standard 2.1 是 IAsyncEnumerable<T> 的最低目标框架；.NET Core 3.0+ / .NET 5+ 原生支持。但旧项目升级时容易漏掉关键配置。
- 现象：明明用了
async IAsyncEnumerable<T>，却提示CS0246: The type or namespace name 'IAsyncEnumerable<T>' could not be found - 原因：项目未设
<TargetFramework>netcoreapp3.0</TargetFramework>或更高，或缺失<PackageReference Include="System.Threading.Tasks.Extensions" Version="4.5.4" />（仅限 .NET Framework 4.7.2+ 项目） - VS 版本要求：必须 Visual Studio 2019 16.3+（含 C# 8.0 支持），旧版即使装了 SDK 也无法识别
await foreach - 不推荐降级方案：用
IObservable<T>或自定义Channel<T>模拟 —— 复杂度陡增，且失去语言级取消和结构化异常传播
真正难的不是写对语法，而是判断哪些场景**必须**用 IAsyncEnumerable<T>：当数据源本身是“拉取式”且耗时不可控（比如网络流、DB cursor、传感器采样），又不能全量缓存时，才值得引入这套机制。否则，一个 Task<List<T>> 更简单直接。
