github.com/gin-contrib/sse 是 Gin 框架官方组织（gin-contrib）下的一个 Server-Sent Events（SSE）中间件包，用于在 Gin 中快速、规范地实现 单向实时推送（服务端 → 客户端）。

---

✅ 一句话理解

它让你用 Gin 写 SSE 接口像写 JSON 接口一样简单，自动处理 MIME 类型、刷新、事件格式、连接保活等细节。

---

🔍 核心能力

表格

复制

功能	说明
标准事件格式	自动输出 data: …\n\n、event: …\n、id: …\n
流式刷新	每写一条事件立即 Flush()，无需手动调 Flush()
连接保活	内置每 15 s 发送一次注释（:keep-alive\n）防代理超时
错误处理	客户端断开时自动 ctx.Done() 退出循环，不泄露 goroutine
兼容 Gin	直接 c.SSEvent(...)，与 c.JSON 用法一致

---

📦 安装

bash

复制

go get github.com/gin-contrib/sse

---

🚀 最小可运行示例

go

复制

package main

import (
	"net/http"
	"time"

	"github.com/gin-contrib/sse"
	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.GET("/stream", func(c *gin.Context) {
		// 关键：设置必要的 SSE 头
		c.Writer.Header().Set("Content-Type", "text/event-stream")
		c.Writer.Header().Set("Cache-Control", "no-cache")
		c.Writer.Header().Set("Connection", "keep-alive")

		// 每 1 s 推送一次当前时间
		for {
			select {
			case <-c.Request.Context().Done(): // 客户端断开
				return
			default:
				sse.Encode(c.Writer, sse.Event{
					Event: "tick",
					Data:  time.Now().Format("15:04:05"),
					ID:    fmt.Sprintf("%d", time.Now().Unix()),
				})
				c.Writer.Flush()
				time.Sleep(time.Second)
			}
		}
	})

	r.Run(":8080")
}

前端一行代码即可接收：

JavaScript

复制

const es = new EventSource("/stream");
es.addEventListener("tick", e => console.log(e.data));

---

🧩 API 速览

go

复制

// 写单个事件
sse.Encode(w, sse.Event{
    Event: "message", // 可选
    Data:  "hello",
    ID:    "123",     // 可选
    Retry: 5000,      // 可选，浏览器重连间隔(ms)
})

// 写纯数据（等价 event=message）
sse.Encode(w, sse.Event{Data: "plain"})

---

⚠️ 使用注意

1. 必须设置 Content-Type: text/event-stream，否则浏览器不识别 SSE。

2. Nginx 反向代理需加配置：

   nginx

   复制

   proxy_buffering off;
   proxy_cache off;

3. SSE 是单向（服务端→客户端），如需双向请用 WebSocket。

4. HTTP/2 支持良好，但 HTTP/1.1 仍受浏览器“同域 6 连接”限制。

---

📚 与 gin.Context 的封装（可选）

社区常见写法：

go

复制

func (c *gin.Context) SendEvent(event, data string) {
    _ = sse.Encode(c.Writer, sse.Event{Event: event, Data: data})
    c.Writer.Flush()
}

---

✅ 总结一句话

gin-contrib/sse = Gin 的 SSE 官方外挂，帮你把“长连接 + 事件流”封装成几行代码，写推送接口再也不用自己拼 data: 字符串。