.NET 7 Web API中yield return与返回集合的IEnumerable<T>差异

在.NET 7的Web API端点中，当返回类型为IEnumerable<T>时，使用yield return和直接返回已填充的集合（比如List<T>）存在诸多实际差异，以下是对比两种实现的示例代码：

using Microsoft.AspNetCore.Mvc;
using Microsoft.Data.SqlClient;
using System.Data;

namespace YieldTest.Controllers;

[ApiController]
[Route("[controller]")]
public class UsersController : ControllerBase
{
    [HttpGet("yield-return")]
    public IEnumerable<UserData> YieldReturn()
    {
        using var connection = new SqlConnection(connectionString);
        using var command = new SqlCommand(query, connection);
        connection.Open();

        using var reader = command.ExecuteReader();

        while (reader.Read())
            yield return new(
                 reader.GetString("Username"),
                 reader.GetString("EMail")
             );
    }

    [HttpGet("return-collection")]
    public IEnumerable<UserData> ReturnCollection()
    {
        using var connection = new SqlConnection(connectionString);
        using var command = new SqlCommand(query, connection);
        connection.Open();

        using var reader = command.ExecuteReader();

        var users = new List<UserData>();
        while (reader.Read())
            users.Add(new(
                reader.GetString("Username"),
                reader.GetString("EMail")
            ));

        return users;
    }

    const string query = "SELECT Username, EMail FROM Users";
    const string connectionString = "Data Source=.;Initial Catalog=[db];User Id=[user];Password=[pwd];";
}

public record UserData(
    string Username,
    string Email
);

核心差异分析 #

内存占用 #

• 返回集合：必须先将所有查询结果加载到List<T>中，内存会一次性持有整个结果集。如果数据集庞大，容易造成高内存占用，甚至触发内存不足异常（OOM）。
• yield return：采用**延迟执行（懒加载）**机制，每次仅生成一个UserData实例，内存中始终只保留当前处理的单个对象，内存占用更平缓，适合大数据量场景。

数据库连接生命周期 #

• 返回集合：数据库连接会在整个结果集加载完成后，随着using块结束而释放。若数据量极大，连接持有时间会显著变长，可能耗尽数据库连接池资源，影响其他请求。
• yield return：ASP.NET Core会在序列化过程中逐个枚举元素，这意味着数据库连接会在整个序列化周期内保持打开状态。虽然示例中using块会确保连接最终释放，但持有时间仍远长于返回集合的场景，同样存在连接池耗尽风险。

响应发送时机 #

• 返回集合：必须等待所有数据加载完成后，才会向客户端发送完整响应，客户端需等待全量数据准备完毕才能开始接收，延迟较高。
• yield return：ASP.NET Core的序列化器（如System.Text.Json）支持流式序列化，会逐个序列化并发送元素，客户端可以逐步接收数据，大幅减少等待时间，提升用户体验。

异常处理 #

• 返回集合：异常会在数据加载阶段抛出（如数据库查询失败），此时尚未向客户端发送响应，框架能直接返回标准的500错误。
• yield return：异常可能在序列化过程中触发（如枚举某条数据时出错），此时可能已向客户端发送了部分响应，导致客户端收到不完整的JSON数据，无法获得标准错误反馈。

性能与复用性 #

• 返回集合：一次性加载全量数据，适合小数据集场景，序列化时直接遍历内存集合，速度更快；返回的List<T>支持多次枚举，调用方可重复遍历结果。
• yield return：适合大数据集，避免内存压力，但逐个枚举会增加序列化过程中的IO交互，整体吞吐量略低；返回的迭代器不支持重复使用，多次枚举会重新执行整个方法逻辑（包括重新连接数据库、重新查询），可能引发意外的重复查询。

内容的提问来源于stack exchange，提问作者Jouni Kantola