ASP.NET Core 中 Minimal API 实现 SSE 的技术实践

在 ASP.NET Core 开发中，Server-Sent Events (SSE) 是一种实现服务器向客户端推送数据的轻量级技术。本文将深入探讨如何在 ASP.NET Core 的 Minimal API 中正确实现 SSE 功能，并解决开发过程中可能遇到的内容类型设置问题。

技术背景

SSE 是一种基于 HTTP 的服务器推送技术，它允许服务器单向地向客户端发送事件流。与 WebSocket 不同，SSE 仅支持服务器到客户端的单向通信，但实现更简单，适用于需要服务器推送但不需要双向通信的场景。

在 ASP.NET Core 中，传统控制器方式实现 SSE 相对直接，通过设置 Response.Headers.ContentType = "text/event-stream" 即可。但在 Minimal API 中，这一过程会遇到一些特殊挑战。

问题现象

当开发者尝试在 Minimal API 中返回 IAsyncEnumerable<T> 来实现 SSE 时，会遇到内容类型被强制设置为 application/json; utf-8 的问题。这是因为 Minimal API 的底层机制会自动处理响应序列化，覆盖了手动设置的内容类型。

解决方案

经过技术验证，正确的实现方式应使用 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");
});

这种方法既保持了 Minimal API 的简洁性，又正确设置了 SSE 所需的内容类型。

实现细节

完整的 SSE 实现示例：

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);
    }
}

public record JobStatus(int TotalTasksCount, int CompletedTasksCount);

技术对比

与传统控制器方式相比，Minimal API 的 SSE 实现有以下特点：

1. 代码更加简洁，路由和处理逻辑集中在一处
2. 需要显式使用 Results.Json 方法来设置内容类型
3. 保持了 Minimal API 的轻量级特性
4. 仍然支持异步流式传输

最佳实践

在实际开发中，建议：

1. 为 SSE 端点添加明确的路由前缀，如 /sse/
2. 考虑添加 CORS 策略以支持跨域访问
3. 实现适当的心跳机制保持连接活跃
4. 添加错误处理和连接状态监控

总结

ASP.NET Core 的 Minimal API 提供了实现 SSE 的高效方式，虽然与控制器方式略有不同，但通过正确使用 Results.Json 方法可以完美解决内容类型设置问题。这种实现方式既保持了代码的简洁性，又确保了功能的完整性，是轻量级服务器推送场景的理想选择。