Azure Function流式返回踩坑实录：为什么你的SSE数据被当成了普通Response？

Azure Function流式返回实战：从SSE协议规范到浏览器EventStream的完整解析

最近在帮一个做实时数据仪表盘的团队做技术方案，他们需要在Azure Function里实现一个流式推送的API，将后端处理的数据实时推送到前端大屏上。团队里一位经验丰富的后端工程师按照官方文档写了一个看似标准的流式响应，但前端同事调用时却发现数据没有像预期那样出现在浏览器的EventStream面板里，而是被当成了普通的HTTP响应体。这个问题困扰了他们整整两天，直到我们坐下来逐行检查协议规范，才发现问题出在一个极其细微但又至关重要的格式细节上。

如果你也在使用Azure Functions、AWS Lambda或者任何支持流式响应的无服务器框架，并且希望实现Server-Sent Events（SSE）这样的实时数据推送，那么这篇文章可能会帮你避开我们踩过的那些坑。我们将从SSE协议的核心规范讲起，深入分析为什么浏览器会“误解”你的流式响应，并提供一套完整的、经过生产环境验证的解决方案。

1. 理解Server-Sent Events：不仅仅是“流式返回”

很多人第一次接触SSE时，会简单地认为它就是一种“服务器可以持续向客户端发送数据”的技术。这种理解虽然没错，但过于笼统，容易忽略SSE作为一项正式协议所要求的严格规范。实际上，SSE是W3C标准的一部分，它定义了一套完整的、基于HTTP的事件流格式。

1.1 SSE协议的核心要素

SSE协议的核心在于其特定的数据格式。一个合法的SSE响应必须遵循以下结构：

• 事件行：以event:开头的行，用于定义事件类型（可选）
• 数据行：以data:开头的行，这是实际要传输的数据内容（必需）
• ID行：以id:开头的行，用于设置事件的ID，便于客户端断线重连时恢复（可选）
• 重试行：以retry:开头的行，指定客户端连接断开后的重试时间（可选）
• 注释行：以:开头的行，会被客户端忽略，可用于发送心跳（可选）

最重要的是，每个事件（无论是单个字段还是多个字段的组合）都必须以两个换行符（\n\n）结束。这是协议规定的分隔符，告诉浏览器“一个完整的事件已经发送完毕”。

注意：很多开发者在这里犯的第一个错误是只用一个换行符，或者使用\r\n。虽然某些浏览器可能宽容处理，但严格遵循\n\n才能确保跨浏览器兼容性。

1.2 浏览器如何识别SSE响应

当浏览器接收到一个HTTP响应时，它会检查响应头中的Content-Type。如果看到text/event-stream，浏览器就会启动SSE处理引擎，而不是将响应体当作普通文本或JSON来处理。

但是，仅仅设置正确的Content-Type还不够。浏览器还会检查实际的数据流是否符合SSE格式规范。如果数据流不符合规范，浏览器可能会“降级”处理，将数据当作普通响应体显示在Network面板的Response标签页中，而不是在EventStream标签页中。

以下是一个典型的错误示例与正确示例的对比：

# 错误示例：缺少data:前缀和正确的分隔符
def generate_stream():
    for i in range(5):
        yield f"Message {i}\n"  # 缺少data:前缀，分隔符也不对

# 正确示例：符合SSE规范
def generate_stream():
    for i in range(5):
        yield f"data: Message {i}\n\n"  # 有data:前缀，以\n\n结束

在实际调试中，你可以通过浏览器的开发者工具来验证：

1. 打开Network面板
2. 找到你的SSE请求
3. 查看响应头是否包含Content-Type: text/event-stream
4. 如果响应符合规范，你会看到EventStream标签页；否则只有Response标签页

2. Azure Function中的SSE实现：常见陷阱与解决方案

在Azure Function中实现SSE，你可能会遇到一些特定于平台或框架的挑战。下面我们通过一个完整的示例来展示正确的实现方式，并分析常见的错误模式。

2.1 基础实现：从简单示例开始

让我们先看一个最基本的Azure Function SSE实现：

import azure.functions as func
import json
import time

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@app.route(route="sse_basic", methods=["GET"])
def sse_basic(req: func.HttpRequest) -> func.HttpResponse:
    """最基本的SSE实现示例"""
    
    def event_generator():
        # 发送5个事件，每个事件间隔1秒
        for i in range(1, 6):
            # 构建符合SSE格式的事件
            event_data = f"data: Event {i} at {time.time()}\n\n"
            yield event_data.encode('utf-8')  # 注意：需要编码为bytes
            time.sleep(1)
        
        # 发送结束事件
        yield "data: [DONE]\n\n".encode('utf-8')
    
    # 创建流式响应
    return func.HttpResponse(
        body=event_generator(),
        status_code=200,
        headers={
            "Content-Type": "text/event-stream",
            "Cache-Control": "no-cache",
            "Connection": "keep-alive",
            "Access-Control-Allow-Origin": "*"  # 根据实际情况调整CORS
        },
        mimetype="text/event-stream"
    )

这个实现看起来很简单，但已经包含了几个关键点：

1. 正确的Content-Type头：必须设置为text/event-stream
2. 正确的数据格式：每个事件都以data:开头，以\n\n结尾
3. 编码处理：在Azure Function中，yield返回的应该是bytes类型
4. 连接保持：设置Connection: keep-alive确保连接不会过早关闭

2.2 进阶：处理结构化数据（JSON）

在实际应用中，我们通常需要发送结构化的数据，而不仅仅是纯文本。这时就需要将JSON数据嵌入到SSE格式中：

@app.route(route="sse_json", methods=["GET"])
def sse_json(req: func.HttpRequest) -> func.HttpResponse:
    """发送JSON格式数据的SSE实现"""
    
    def event_generator():
        import json as json_module
        
        # 示例：发送用户状态更新
        users = [
            {"id": 1, "name": "Alice", "status": "online", "timestamp": time.time()},
            {"id": 2, "name": "Bob", "status": "away", "timestamp": time.time()},
            {"id": 3, "name": "Charlie", "status": "offline", "timestamp": time.time()}
        ]
        
        for user in users:
            # 将JSON对象转换为字符串
            json_str = json_module.dumps(user)