ASP.NET Core Minimal API中实现SSE(Server-Sent Events)的正确方式

在ASP.NET Core开发中，Server-Sent Events(SSE)是一种实现服务器向客户端推送数据的有效技术。本文将详细介绍如何在Minimal API中正确实现SSE功能，特别是解决返回内容类型(content-type)被自动设置为application/json的问题。

问题背景

当开发者尝试在Minimal API中返回IAsyncEnumerable类型以实现SSE时，经常会遇到一个常见问题：尽管在代码中明确设置了响应头Content-Type为"text/event-stream"，但最终响应头仍被自动覆盖为"application/json"。

这种问题的根源在于ASP.NET Core框架内部处理机制。框架默认会将IAsyncEnumerable类型的返回值序列化为JSON格式，并自动设置相应的Content-Type头。

解决方案

要正确实现SSE功能，我们需要使用Results.Json方法并显式指定内容类型。以下是具体实现方式：

endpointRouteBuilder.MapGet("api/v1/jobs/{jobId}/status/stream", (
    Guid jobId,
    CancellationToken cancellationToken) =>
{
    var sseStream = GetStatusStream(cancellationToken);
    return Results.Json(sseStream, contentType: "text/event-stream");
});

private async IAsyncEnumerable<JobStatus> GetStatusStream(
    [EnumeratorCancellation] CancellationToken cancellationToken)
{
    for (int i = 0; i < 10; i++)
    {
        await Task.Delay(500, cancellationToken);
        yield return new JobStatus(10, i + 1);
    }
}

技术细节解析

1. Results.Json方法：这是ASP.NET Core Minimal API提供的一个强大工具，它允许开发者完全控制响应的序列化行为，包括内容类型、状态码等。

2. 内容类型指定：通过contentType参数显式设置为"text/event-stream"，确保客户端能正确识别SSE流。

3. 异步流处理：IAsyncEnumerable提供了高效的异步数据流处理能力，特别适合SSE这种需要持续推送数据的场景。

与传统Controller方式的对比

在传统的Controller方式中，可以直接设置Response.Headers.ContentType，这种方式在Minimal API中不适用，因为：

1. Minimal API的设计哲学是更简洁、更声明式的编程模型
2. 框架对返回值的处理流程不同
3. 内部中间件对响应头的处理顺序有差异

最佳实践建议

1. 对于SSE实现，始终使用Results.Json并显式设置内容类型
2. 考虑添加适当的响应缓存控制头，如"Cache-Control: no-cache"
3. 实现适当的心跳机制，保持连接活跃
4. 处理客户端断开连接的情况，及时释放资源

总结

在ASP.NET Core Minimal API中实现SSE功能时，开发者需要特别注意内容类型的设置方式。通过使用Results.Json方法并显式指定内容类型，可以确保SSE功能正常工作，避免框架自动行为带来的问题。这种方法既保持了Minimal API的简洁性，又提供了足够的灵活性来处理特殊场景。