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: 和长连接-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1625.png)
后面加入 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 的核心。
















请登录后查看评论内容