Documentation
¶
Overview ¶
Package sse 提供 Server-Sent Events 流式响应支持，典型用于 AI 对话/LLM 流式输出。
断连契约（C3 收尾，重要）： 框架侧的消费循环（Stream/StreamText/StreamChunks/StreamWithID）已监听 c.Request.Context()， 客户端断连即退出，消费端不泄漏 goroutine。但框架无法单方面停止上游生产者（LLM 流）—— 生产者（向 ch 发送数据的一方）必须自行监听同一 ctx 并在取消时停止生产，否则：
- 上游 LLM 流在客户端已断开后仍持续运行（浪费算力/费用）；
- 生产者向已无人消费的 ch 发送可能阻塞（无界 ch）或丢弃（有界 ch）。
推荐写法：生产者 goroutine 内 select { case <-ctx.Done(): return; case ...: ch <- token }， 其中 ctx 取自请求的 c.Request.Context()（Stream 系列内部用的就是它）。
Index ¶
- Variables
- func SSE() gin.HandlerFunc
- func StreamChunks(c *gin.Context, ch <-chan string) error
- func StreamText(c *gin.Context, ch <-chan string) error
- func StreamWithID(c *gin.Context, messageID string, ch <-chan string) error
- type SSEWriter
- func (w *SSEWriter) KeepAlive() error
- func (w *SSEWriter) Stream(event string, ch <-chan any) error
- func (w *SSEWriter) WriteDone() error
- func (w *SSEWriter) WriteError(err error) error
- func (w *SSEWriter) WriteEvent(event, data string) error
- func (w *SSEWriter) WriteJSON(event string, data any) error
- func (w *SSEWriter) WriteMessage(data string) error
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidEventName = errors.New("sse: event name must not contain CR or LF")
Functions ¶
func StreamChunks ¶
StreamChunks 流式发送文本块（带增量标记）
func StreamText ¶
StreamText 流式发送文本（适用于 AI 对话场景）
消费循环含 ctx.Done 分支（C3a 修复）：客户端断连即退出。 生产者（ch 的发送方）也应监听 c.Request.Context()，以便消费端早退后停止上游 LLM 流； 若生产者忽略 ctx，本函数仍会因 ctx.Done 退出（消费端不泄漏），但上游生产者可能继续运行 直到其自身完成或 channel 阻塞——调用方有责任在 ctx 取消时停止生产。
Types ¶
type SSEWriter ¶
type SSEWriter struct {
// contains filtered or unexported fields
}
SSEWriter SSE 写入器
func (*SSEWriter) KeepAlive ¶
KeepAlive 发送保持连接的心跳。
用 SSE 注释行（": ping\n\n"）而非 data 行（N6 修复）：data 行（含空 data）会触发 客户端 onmessage 回调，注释行仅维持连接不产生消息事件，更符合心跳语义。
func (*SSEWriter) Stream ¶
Stream 流式发送数据
消费循环含 ctx.Done 分支（C3a 修复）：客户端断连（c.Request.Context 取消）时立即退出， 不再仅靠 channel 关闭或写错误退出。配合 WriteJSON 的写错误传播（C3b），断连即停。 ctx 为 nil 时回退到 context.Background()（防御外部未走 NewSSEWriter 构造的 nil panic）。
func (*SSEWriter) WriteEvent ¶
WriteEvent 写入 SSE 事件 格式: event: <event>\ndata: <data>\n\n
写错误向上传播（C3b 修复）：旧实现丢弃 fmt.Fprintf 错误且恒 return nil， 导致客户端断连后 Stream 守卫永不触发、消费循环不退出、上游 LLM 流持续运行。
func (*SSEWriter) WriteMessage ¶
WriteMessage 写入消息（无事件类型） 格式: data: <data>\n\n
Source Files