小节二:SSE 到底是什么——理解 text/event-stream、event:、data: 和长连接

SSE 本质还是 HTTP。

它不像 WebSocket 那样切换成另一套协议。

客户端发起请求。

服务端返回:

Content-Type: text/event-stream

然后不马上关闭连接。

而是持续发送:

event: progress
data: {"message":"正在读取项目..."}

event: progress
data: {"message":"发现 app.py"}

event: completed
data: {"status":"completed"}

每个事件之间用空行分隔。

SSE 看起来只是几行文本,但它真正有价值的地方在于:一个 HTTP 响应可以连续承载很多个有边界的事件。服务端每产生一条进度,就格式化一条并立即发送,不需要等整个 Run 完成。

图片[1]-小节二:SSE 到底是什么——理解 text/event-stream、event:、data: 和长连接-大赛人网

后面加入 id:、retry:、heartbeat 和断线续传,本质上都还是围绕这条持续事件流补可靠性,而不是重新发明一套传输协议。

最基础 SSE 格式

event: progress
data: hello

注意最后有两个换行。

这代表,一个事件结束。

event: 是什么?

表示事件类型。

例如:

progress
tool
failed
completed

前端可以按类型处理。

data: 是什么?

真正数据。

最常见放 JSON:

{
  "run_id": "run_xxx",
  "message": "正在运行测试"
}

为什么推荐 JSON?

因为后面事件会越来越结构化。

例如:

{
  "run_id": "run_xxx",
  "step": 4,
  "type": "tool",
  "message": "正在运行测试",
  "status": "running"
}

前端很好处理。

这里有个格式细节很容易忽略:SSE 的每一个物理数据行都必须以 data: 开头。如果直接把带换行的文本拼进响应,第二行就不再属于这个字段。最省心的做法,是把 payload 编码成单行 JSON,并把格式化集中到一个函数里,不在每个接口里手拼字符串。

id:、retry: 与断线续传

只发送 event: 和 data:,我们已经能看到实时进度;要把它做成可恢复的事件流,还需要两个字段:

前端很好处理。

这里有个格式细节很容易忽略:SSE 的每一个物理数据行都必须以 data: 开头。如果直接把带换行的文本拼进响应,第二行就不再属于这个字段。最省心的做法,是把 payload 编码成单行 JSON,并把格式化集中到一个函数里,不在每个接口里手拼字符串。

id:、retry: 与断线续传
只发送 event: 和 data:,我们已经能看到实时进度;要把它做成可恢复的事件流,还需要两个字段:

id: 是业务事件的单调递增游标。浏览器断线重连时,EventSource 会把最后收到的 ID 放进 Last-Event-ID 请求头,服务端据此补发后续事件。retry: 是建议的重连等待时间,单位是毫秒,不是服务器强制超时。

有三个边界值得提前记住:

  • ID 必须来自可恢复的事件日志,不能只用当前进程里的数组下标。
  • heartbeat 不是业务进度,不要给它分配可恢复事件 ID。
  • 网络重试可能让最后一条事件重复到达,所以前端要按 ID 去重,让处理逻辑具备幂等性。SSE 能提供的是至少一次式的恢复体验,不是凭空得到“绝不重复”的承诺。

还有一个安全细节:event:、id: 这些协议字段不能直接拼接用户输入,否则换行符可能注入新的 SSE 字段。事件名最好使用服务端 allowlist,例如 run.progress、run.completed,payload 再统一做 JSON 编码。

一个最小 Flask SSE Demo

from __future__ import annotations
import json
import time

from flask import (
    Flask,
    Response,
)


app = Flask(__name__)


@app.get("/api/v1/demo/stream")
def demo_stream():

    def generate():
        events = [
            "正在读取项目...",
            "发现 app.py...",
            "正在运行测试...",
            "发现 ImportError...",
            "正在检查依赖...",
        ]

        for index, message in enumerate(
            events,
            start=1,
        ):
            payload = {
                "step": index,
                "message": message,
            }

            yield (
                "event: progress\n"
                "data: "
                + json.dumps(
                    payload,
                    ensure_ascii=False,
                )
                + "\n\n"
            )

            time.sleep(1)

        yield (
            "event: completed\n"
            "data: "
            + json.dumps(
                {
                    "status": "completed"
                },
                ensure_ascii=False,
            )
            + "\n\n"
        )

    return Response(
        generate(),
        mimetype="text/event-stream",
    )


if __name__ == "__main__":
    app.run(
        host="127.0.0.1",
        port=5000,
        debug=False,
        threaded=True,
    )

运行:

python3 app.py

测试:

curl -N \
  http://127.0.0.1:5000/api/v1/demo/stream

这里 -N 很重要。

它让 curl 不缓冲输出。

你会逐条看到:

event: progress
data: ...

event: progress
data: ...

而不是等全部结束再一起显示。

为什么 Flask 要用 generator?

因为:

yield

每产生一条内容,服务器就可以逐步写入响应。

不是:

return all_events

一次性返回。

这个 generator 就是 Streaming 的核心。

© 版权声明
THE END
喜欢就支持一下吧
点赞13 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容