你在屏幕上看到 AI「正在输入」的光标时，有没有想过：这几个字节是怎样跨越千山万水，在屏幕上一个个「蹦」出来的？当 ChatGPT、Kimi、Claude 们用流式的方式「打字」给你看时，这种近乎人类的交互体验背后，藏着一个不起眼却至关重要的技术——Server-Sent Events（SSE）。它不像 WebSocket 那样大名鼎鼎，却在 AI 时代成为了事实上的标准。诚然，在 ASP.NET Core 中实现一个「能工作」的 SSE 接口，仅仅需要十分钟。但是，如果要实现一个「好用」的 SSE 接口——支持事件抽象、复用性好、能优雅地取消，你需要多久呢？本文将为你拆解这个挑战，展示如何整个设计从「能用」走向「好用」。
当 AI 开始「思考」
试想这样一个场景：用户向 Agent 提问「讲一个关于小狐狸的故事」。传统的 HTTP 请求-响应模式下，服务器需要等待大语言模型生成完整回答后，再能将结果返回给用户。这意味着用户可能要盯着屏幕等待十几秒后，才能看到完整的答案。但是，在真实的产品体验中，我们期望看到的是：Agent 首先展示它的「思考过程」——它如何理解用户意图、如何规划回答策略；然后是工具调用的实时反馈——搜索资料、查询数据库；最后才是回答内容的逐字输出。这种「实时可见」的体验，远比「等待-呈现」的模式更加自然和引人入胜。
SSE 正是实现这种体验的关键技术，它基于 HTTP 协议，允许服务器主动向客户端推送数据，相比 WebSocket 更加轻量，且能复用现有的 HTTP 基础设施。对于 LLM 流式输出这类场景，SSE 几乎是完美的选择。
第一阶段：最朴素的实现
一切的开始，是一段朴实无华的代码。博主直接在控制器中拼接 SSE 格式的字符串，然后写入响应流：
[HttpGet("chat")]
public async Task ChatStream(CancellationToken cancellationToken) {
Response.ContentType = "text/event-stream; charset=utf-8";
Response.Headers["Cache-Control"] = "no-cache";
Response.Headers["Connection"] = "keep-alive";
foreach (var chunk in GenerateText()) {
string message = $"data: {JsonConvert.SerializeObject(new { text = chunk })}\n\n";
await Response.WriteAsync(message, Encoding.UTF8, cancellationToken);
await Response.Body.FlushAsync(cancellationToken);
}
}
这种写法虽然「能用」，但是存在明显的问题：字符串拼接逻辑散落在各处，维护成本高；如果要发送不同类型的事件（如消息开始、文本增量、工具调用、思维链、消息结束），代码将会变得难以维护。
第二阶段：引入事件抽象
既然 SSE 支持多种事件类型（message、thinking_delta、tool_use 等），博主决定先把这部分抽象出来。
首先是定义事件模型，参考 Anthropic Messages API 的设计：
public interface ISseEvent { string Type { get; } }
public class MessageStartEvent : ISseEvent {
public string Type => "message_start";
public MessageMetadata Message { get; set; } = new();
}
public class ContentBlockDeltaEvent : ISseEvent {
public string Type => "content_block_delta";
public int Index { get; set; }
public ContentBlockDelta Delta { get; set; } = new();
}
然后是 SSE 响应的配置和写入扩展方法：
public static class StreamingExtensions {
public static void ConfigureSseResponse(this HttpResponse response) {
if (response.HasStarted) return;
response.ContentType = "text/event-stream; charset=utf-8";
response.Headers["Cache-Control"] = "no-cache";
response.Headers["Connection"] = "keep-alive";
}
public static async Task WriteSseEventAsync<TEvent>(
this HttpResponse response, TEvent @event, CancellationToken ct = default)
where TEvent : ISseEvent {
var sb = new StringBuilder();
sb.Append($"event: {@event.Type}\n\n");
var json = JsonSerializer.Serialize(@event);
sb.Append($"data: {json}\n\n");
await response.WriteAsync(sb.ToString(), Encoding.UTF8, ct);
await response.Body.FlushAsync(ct);
}
}
现在，控制器代码变成了这样：
[HttpGet("chat")]
public async Task ChatStream(CancellationToken cancellationToken) {
Response.ConfigureSseResponse();
await Response.WriteSseEventAsync(new MessageStartEvent { Message = new() { Id = "1" } }, cancellationToken);
// ... 逐个写入事件
}
代码整洁了一些，但是问题依然存在：控制器不仅要处理业务逻辑，而且要关心 SSE 输出细节，甚至需要特别注意响应头配置的时机。
第三阶段：结合 IAsyncEnumerable
当博主想要用 yield return 来组织事件流时，发现 async 方法不支持 yield return，幸运的是，C# 8.0 引入的 IAsyncEnumerable 完美解决了这个问题：
[HttpPost("chat")]
public async IAsyncEnumerable<ISseEvent> ChatStream([FromBody] ChatRequest request) {
Response.ConfigureSseResponse();
yield return evt.MessageStart("MiniMax-M2.1");
yield return evt.ThinkingBlockStart(0);
// ... 业务逻辑
}
这段代码看起来非常优雅，yield return 让事件的组织变得清晰。但是，这里有一个隐藏的陷阱：
直接返回
IAsyncEnumerable时，ASP.NET Core 默认会将其序列化为 JSON 数组，而不是流式输出。
这是因为输出格式化器（Output Formatters）默认将 IAsyncEnumerable<T> 视为普通对象，等待整个枚举完成后再一次性发送。这与 SSE「边产生边发送」的特性完全相悖，会导致接口返回 406 或直接返回 JSON。
第四阶段：多方案探索
面对这个问题，博主开始探索各种解决方案。第一种方案是不用 [ApiController]，绕过默认格式化行为，让框架把 IAsyncEnumerable 当作普通流处理。但这意味着，你将会放弃 ApiController 带来的模型绑定等便利。第二种方案则是使用中间件统一处理，自动配置 SSE 响应头、写入 SSE 数据流：
public class SseStreamingMiddleware {
public async Task InvokeAsync(HttpContext context)
{
var endpoint = context.GetEndpoint();
if (endpoint?.Metadata?.GetMetadata<SseStreamingAttribute>() == null)
{
await _next(context);
return;
}
context.Response.ConfigureSseResponse();
await _next(context);
}
}
然而，现实给了博主当头一棒。ASP.NET Core 的中间件管道顺序是：
Request → AuthMiddleware → ... → Controller → Response
AuthorizationMiddleware 在认证过程中会访问 Response 对象。当我们期望在后续中间件中修改响应头时，框架已经处于「敏感」状态。中间件方案的问题在于它工作在「底层」的请求管道层面，不适合处理控制器级别的返回值序列化。
博主再次尝试过使用 ActionFilter 来处理 SSE 输出，可它同样面临着响应头配置时机的问题。Filter 在控制器 Action 执行前后运行，遗憾的是，响应头一旦发送就无法修改。回到 ASP.NET Core 的应用层来思考。控制器的返回值，最终都会转化为 IActionResult，那么在 IActionResult.ExecuteResultAsync 中处理 SSE 输出，这不就完美了吗？
public class SseResult : IActionResult {
private readonly IAsyncEnumerable<ISseEvent> _events;
public SseResult(IAsyncEnumerable<ISseEvent> events) => _events = events;
public async Task ExecuteResultAsync(ActionContext context) {
context.HttpContext.Response.ConfigureSseResponse();
await foreach (var @event in _events.WithCancellation(context.HttpContext.RequestAborted)) {
await context.HttpContext.Response.WriteSseEventAsync(@event, context.HttpContext.RequestAborted);
}
}
}
// 扩展方法
public static class SseResultExtensions {
public static SseResult SseStream(this IAsyncEnumerable<ISseEvent> events)
=> new SseResult(events);
}
此时，控制器代码变得简洁而优雅：
[HttpPost("chat")]
public IActionResult Chat([FromBody] ChatRequest request)
=> ChatAsync().SseStream();
private async IAsyncEnumerable<ISseEvent> ChatAsync([EnumeratorCancellation] CancellationToken ct = default) {
yield return evt.MessageStart("MiniMax-M2.1");
// ... 业务逻辑
}
所以，为什么 IActionResult 方案可行呢？这个方案的成功在于它找到了正确的「执行时机」：
Request → Filters → Controller Action → IActionResult.ExecuteResultAsync → Response
首先，ExecuteResultAsync 在控制器 Action 执行完毕后、响应提交前执行，这个时机配置响应头完全没问题。其次，IActionResult 是 ASP.NET Core 的原生模式，框架对它有完善支持，无需与中间件管道「较劲」。
横向对比
| 维度 | 手写字符串 | 事件抽象 | 纯 IAsyncEnumerable | 中间件方案 | SseResult 方案 |
|---|---|---|---|---|---|
| 实现复杂度 | 低 | 低 | 低 | 中 | 低 |
| 事件抽象 | 无 | 有 | 有 | 有 | 有 |
| 代码复用性 | 差 | 差 | 差 | 中 | 好 |
| 响应头配置 | 需注意时机 | 需注意时机 | 需注意时机 | 可能有冲突 | 完美时机 |
| 推荐场景 | 快速原型 | 快速原型 | 学习研究 | 特定需求 | 正式项目 |
从一次实践到一种设计哲学
完成 SSE 流式响应的重构后，博主开始思考更深层的问题：这仅仅是一次技术选型，还是一种设计哲学？在 LLM Agent 的设计中，流式输出远不止「逐字地显示回答」这么简单。
一个完整的 Agent 交互通常包含三个阶段，而这三个阶段，对应着 SSE 的三种核心事件类型：
| 阶段 | 描述 | SSE 事件类型 |
|---|---|---|
| 思考可见 | Agent 展示「思考过程」——如何理解问题、如何规划解决路径，用户全程「旁观」 | thinking_delta |
| 工具调用反馈 | Agent 调用外部工具时，实时展示：「正在搜索资料…」「找到 3 条结果…」 | tool_use / tool_result |
| 答案逐字输出 | 最终答案逐字呈现，配合前端光标动画，创造「AI 正在打字」的真实感 | text_delta |
当然，在「Interleaved Thinking」机制下，ReAct 范式变成了模型的一部分，思考和工具调用交替进行，SSE 事件无疑会更加复杂，这篇文章恰恰是在思考如何应对这种复杂性。
完成 SSE 重构后，博主意识到这其实是事件驱动架构在客户端-服务器交互中的一次实践。Agent 的每一个「动作」都转化为一个事件，客户端接收并渲染这些事件，构建完整的交互体验。这种设计的好处显而易见：
- 可扩展性：添加新的事件类型，只需定义新的
ISseEvent实现 - 可观测性：每个事件都是独立的日志单元
- 前端友好：思考、工具、文本可以分别渲染在不同区域
为什么简单的事情会变得复杂？因为我们需要理解框架的设计哲学，理解各个组件的职责边界。
- 中间件是请求/响应层面的抽象，适合做全局性的预处理/后处理
- IActionResult是应用返回层面的抽象，适合处理控制器的返回值
- 我们要解决的是「控制器返回值的处理」，自然应该在
IActionResult这个抽象层次上解决
写在最后
完成这次 SSE 流式响应的重构，博主最大的收获不是代码本身，而是在正确的抽象层次上解决问题这一思维方式的转变。技术的世界里有太多「看起来可行」但实际行不通的方案。我们需要理解框架的设计哲学，理解各个组件的职责边界，从而找到真正优雅的解决方案。当然，技术从来都不是孤立存在的。当我们谈论 SSE 时，谈论的其实是人与机器之间那条无形的纽带。流式响应让 AI 不再是一个黑箱——它「思考」时你看得见，它「行动」时你看得见，它「回答」时你依然看得见。这种透明性背后，是当前时代人机交互的一个缩影。Agent 的时代已悄然来临，SSE 流式响应不过是冰山一角。一个优秀的 Agent 系统还需要考虑如何组织工具、如何做决策规划、如何处理错误、如何支持多轮对话……每一个话题都是一座值得攀登的山峰。希望这篇博客，不只是帮助你解决了一个技术问题，而是为你打开了一扇窗——透过这扇窗，你会看到更多关于「如何让机器更懂人类」的思考。模型在进步，思考亦然。愿你保持好奇，愿你永不止步。
延伸阅读：
参考资源：
