流式 API 设计关注增量数据传输、重连与语义事件的定义，是实现低感知延迟体验的关键。本文总结面向前端消费的流式 API 设计要点与示例。
设计目标
- 支持增量消费：客户端可以逐块解析并渲染数据，降低首次可视延迟。
- 可恢复性：在网络中断时支持断点续传或局部重试。
协议与格式
- 选择合适的传输协议（SSE、WebSocket、HTTP/2/3 stream），并采用易解析的分块格式（JSON Lines、protobuf 切片）。
事件语义与版本控制
- 为每个事件定义类型、版本与幂等 ID，便于合并、重放与去重。
示例（JSON Lines SSE）
HTTP/1.1 200 OK
Content-Type: text/event-stream
data: {"type":"chunk","id":1,"payload":{...}}
data: {"type":"chunk","id":2,"payload":{...}}
data: {"type":"done"}
实践建议
- 合理划分 chunk 粒度，平衡每次传输延迟与解析开销。
- 在边缘或代理层处理连接保活与速率限制，防止后端被瞬时流量击穿。
结语
良好的流式 API 不仅能改善用户体验，还能提高系统弹性；通过明确事件语义、幂等设计与恢复策略，可以保证在不稳定网络环境下稳定工作。
初步纲要
- 主题简介
- 背景与动机
- 核心概念
- 实践案例
- 进一步扩展
相关链接
⚠️ 本文为占位内容，后续将补充完整版本。