push —— 服务端事件推送通道(SSE 的传输层地基)
后台要在权限变更、任务跑完、字典改了之后立刻刷新界面。 SSE(而不是 WebSocket)是因为它走普通 HTTP,浏览器自带断线重连, 而且是单向的 —— 这个场景本来就只需要服务端 → 客户端。
功能
push 是 SSE 的传输层地基,只做三件事:
- 订阅 / 发布:
Publish(ctx, topics, ev)投递、Subscribe(ctx, topics)订阅。 传输层是Transport接口,当前只有 Redis pub/sub 一个实现在跑 (NewRedisTransport)。留接口的唯一理由是将来换 WebSocket 时新增一个实现即可, 业务侧的Publish调用一行都不用改。 - topic 命名空间:
TopicPerm/TopicJob/TopicApproval/TopicDict/TopicUser(userID)。一条 SSE 连接承载全部 topic,前端不能自选订阅范围 (服务端按 RBAC 算,见internal/api/handler/v1/event.go)。 - 慢消费者背压:每条连接一个 64 格缓冲,满了丢最旧而不是阻塞,
并补一条
lag事件告诉前端"你漏了,去补拉"。
三条设计(包注释里的原话):
- 事件是信号,不是数据。payload 里没有业务正文,前端收到后重新调 REST 拿最新状态。 这样推送不扩大数据可见范围,也不会产生"REST DTO 一份、推送 payload 一份"的双份契约漂移。
- 单路径投递。Redis pub/sub 是唯一通道,没有"进程内 Hub + Redis"双投递 —— 双投递会让同实例的连接收到两份事件(长列表页反复重拉), 而且这个 bug 只在单实例部署下出现,多实例部署恰好正常。
- 不静默。Redis 不可用时
/events会发degraded事件让前端切轮询。
不解决什么:不鉴权(订阅范围由 handler 判)、不做消息持久化(Redis pub/sub 不补发)、 不推 App 离线消息(那是 pushx)。
配置
yaml 侧
该包自身无 yaml 配置块 —— 没有 push: 段。
它依赖的是 redis: 块(Redis pub/sub 是唯一通道):
redis:
addr: 127.0.0.1:6379
password: ${REDIS_PASSWORD}
db: 0
pool_size: 50
min_idle_conns: 10
dial_timeout: 5s
read_timeout: 3s
write_timeout: 3s
⚠️ 别把 push: 段(那是 pushx 的 App 推送)和本包搞混 ——
两个都叫"推送",但通道、投递对象、失败语义完全不同。
代码侧(构造选项)
push.InitRedis(rdb) // 用 redis.Client 构造默认传输层
push.Init(transport) // 注入任意 Transport 实现
push.NewRedisTransport(rdb) // 显式构造 redis 传输层
InitRedis(nil) 直接 return(不覆盖已注入的传输层);Init(nil) 显式清空。
使用方法
装配(启动期一次)
push.InitRedis(repository.GetRedis())
if push.Available() {
logger.L().Info("push transport ready")
}
发布(业务侧)
push.Publish(ctx, []string{push.TopicUser(userID)}, push.Event{
Topic: push.TopicUser(userID),
Event: push.EventInboxUnread,
Payload: inbox.UnreadEvent{UserID: userID, Delta: +1},
})
⚠️ Publish 永不返回错误 —— 推送是尽力而为的旁路,
投递方是"刚写完库的请求"或"cronx 刚跑完任务的 goroutine",
不该因为"推送没发出去"就让主流程失败。失败只记 Warn 日志。
多 topic 一次投递(pipeline 发,一次 RTT):
push.Publish(ctx, []string{push.TopicPerm, push.TopicJob}, push.Event{
Topic: push.TopicJob,
Event: push.EventJobFinished,
Payload: push.JobPayload{JobKey: "framework.job_history_purge", Status: "success", DurationMs: 12},
})
订阅
evs, cancel := push.Subscribe(ctx, []string{push.TopicPerm})
defer cancel()
for ev := range evs {
// ev.Topic / ev.Event / ev.Payload / ev.At
}
事件名与 payload 对照
| 事件名常量 | wire 上的名字 | payload 类型 | 含义 |
|---|---|---|---|
EventConnected |
connected |
{topics, degraded} |
连接建立 |
EventDegraded |
degraded |
{reason, retry_ms} |
Redis 不可用,前端切轮询 |
EventLag |
lag |
{dropped} |
本连接被丢过事件,前端补拉 |
EventPermChanged |
perm_changed |
permnotify.Message |
权限变了 |
EventJobFinished / EventJobFailed |
job.finished / job.failed |
push.JobPayload |
定时任务状态 |
EventInboxUnread |
inbox.unread |
inbox.UnreadEvent |
站内信未读数变了 |
EventApprovalTodo / EventApprovalDone |
approval.todo / approval.done |
push.ApprovalPayload |
待办 / 办完了 |
EventDictChanged |
dict.changed |
push.DictChangedPayload |
某个字典组被改了 |
注意事项
- ⚠️ 消费者缓冲长度必须读
len(c.out),不能自己维护计数。 原实现有个n int字段,靠deliver里的n++/n--维护"缓冲里有多少条", 但消费端把事件读走时没有任何人会通知这个计数 —— 读走的那一端是 SSE handler / 浏览器,它们只管<-evs,不会回调 consumer。 于是n只增不减:一个跟得上的消费端(正常情况!)在第 64 条事件上就走进"丢最旧"分支, 而那时缓冲早被读空了 ——<-c.out于是永久阻塞,pump 的 goroutine 卡死, 这条 SSE 连接从此再收不到任何事件,而且没有任何报错。 症状极隐蔽:心跳还在发(那是 handler 另一个 goroutine 写的),连接看起来是活的, 但页面就是不再刷新。心跳 25s 一跳、job 事件每分钟一条 ⇒ 一个开着后台的标签页 几小时内必然踩到。(commitf6d4225修的就是这个。) - ⚠️ 缓冲的最后一格永久留给
lag。数据事件上限恒为connBuffer-1(63), 任何时刻缓冲里至少有 1 格空位,lag一定塞得进去。 否则数据事件把缓冲占满后lag永远挤不进去 ⇒ 前端不知道自己漏了 ⇒ 页面停在旧状态且无任何提示("不静默"直接失效)。 - ⚠️ 慢消费者策略是"丢最旧"不是阻塞。丢一条旧的代价是"这次刷新看到稍旧的状态", 下一个事件立刻纠正;阻塞整个订阅循环的代价是该实例所有 SSE 连接都停摆。 两者差三个数量级。丢最新更糟:页面永远停在最老的状态,而那个状态再也等不到后续事件纠正。
- ⚠️ 持续过载时
lag事件自己也会随队头轮换出队 —— 这是有意接受的: 前端已经落后到读什么都不对,再补一条"你漏了"毫无意义;等它追上来、下一次再丢事件时lag会重新生成。所以前端不能只靠lag—— 连接建立时前端就应当主动拉一次全量。 - ⚠️
Subscribe在 Redis 不可用时返 nil channel,不返 error。 返回 error 会让前端看到"连接失败"然后无限重连 —— 而那永远也不会成功。/eventshandler 据此发degraded事件并主动断开,让EventSource按 服务端给的retry:60000慢速重试。 - ⚠️ Redis pub/sub 不补发。
Subscribe内部必须等一次订阅确认 (ps.Receive)—— 跳过这步,Subscribe返回后到 Redis 真正生效之间有一个窗口, 这期间发布的事件会永久丢失。 - ⚠️ 事件名不许改。前端
useEventStream.ts的EVENT常量按名字订阅, 改名等于让所有已发版的前端收不到事件,而症状是"字典改了不生效" / "权限变了不刷新", 不报错、很难归因。 - ⚠️ payload 不带业务正文。
JobPayload刻意不含Error正文、ApprovalPayload不含驳回意见、DictChangedPayload只带group_code。 收到的人自己回查 —— 那是按权限过滤过的地方。 - ⚠️ 事件是广播 ⇒ 角标必须重拉 total,不能 ±1。同一 topic 上既有"分给我的"
也有"我发起的",前端根本判不出"这条该动谁的角标";而且 delta 在并发下会漂移。
前端
refreshUnread/refreshApprovalTodo都是一律重拉。 - ⚠️ 订阅范围是建连那一刻的快照。权限变了之后老连接上仍挂着已经不属于自己的 topic,
所以收到
perm_changed后必须重建连接(useEventStream里延迟 500ms 重连), 让服务端重判subscribableTopics。 - ⚠️
TopicPerm的频道名故意不带push:前缀。perm:invalidate:all是迁移前就存在的, 保留它意味着本模块接管订阅端时发布端一行都不用改,没有"双写 / 双订阅"的迁移窗口。
相关
- 源码:
internal/pkg/push/ - 可运行示例:
examples/push/main.go——go run ./examples/push - 权限失效广播(本包的一个生产者)→ permnotify
- 站内信未读信号(另一个生产者)→ inbox
- Redis 连接配置 → cachex