inbox —— 站内信 + 通知中心
业务模块(审批、订单、系统通知……)要给某个用户发一条站内信时, 只依赖一个接口:
Notifier.Notify(ctx, Message)—— 不依赖具体实现、 不依赖 DB、不依赖 Redis。 通知中心那一侧(列表 / 未读数 / 标已读)也在这里。
功能
inbox 提供四件事:
- 投递:
Notifier接口(Notify/NotifyBatch)。 业务模块依赖接口而不是Manager,换存储(比如换成 MQ)时业务代码一行不用改。 - 通知中心查询:
Manager.List/UnreadCount/MarkRead/MarkAllRead/Delete。 - 未读变更信号:投递 / 标已读之后,经 push 推
push:user:<id>频道, 前端 SSE 实时刷角标。Redis 不可用 ⇒ 推送静默丢弃,前端轮询unread-count兜底。 - 防 IDOR:
List/MarkRead/MarkAllRead/Delete全部带user_id条件 —— 不属于自己的那条返 nil(不报错,也不动)。
不解决什么:
- 不做投递幂等(见「注意事项」第 1 条 —— 同一业务事件调两次
Notify会写两条); - 不做权限判定(RBAC 码挂在 handler 上,不在这个包里);
- 不做离线推送(App 侧离线通知是 pushx);
- 不做多通道分发(那层是 notifyx)。
配置
yaml 侧
该包无 yaml 配置。 没有 inbox: 块,也没有任何配置项 —— 它只有一个 *gorm.DB 依赖,
表 sys_inbox_message 由 GORM AutoMigrate 建(internal/migrate/migrate.go 里注册了
&model.InboxMessage{})。示例里手写 DDL,是因为框架示例不许 import internal/model。
代码侧(构造选项)
mgr := inbox.New(db) // 唯一构造函数,没有 opts
生产上由 cmd/server 装配(inboxMgr := inbox.New(db)),
业务模块拿的是 registry.InboxNotifier(inbox.Notifier 接口)。
使用方法
投递
// 业务模块依赖的是 Notifier 接口,不是 Manager
var notifier inbox.Notifier = mgr
err := notifier.Notify(ctx, inbox.Message{
UserID: userID,
MsgType: "biz",
Title: "订单确认单待确认",
Content: "您的订单已生成,请在 7 天内确认。",
Link: "/order/confirm/20260301",
RefType: "order",
RefID: 20260301,
SenderID: 1,
})
批量投递(同事务,失败整批回滚;msgs 里允许不同 UserID):
err := notifier.NotifyBatch(ctx, []inbox.Message{
{UserID: userID, MsgType: "system", Title: "系统公告", Content: "本周六 02:00-04:00 系统维护。"},
{UserID: userID, MsgType: "notice", Title: "费用提醒", Content: "第三季度账单将于 10 月 15 日开始计收。"},
})
未读数 / 列表
n, err := mgr.UnreadCount(ctx, userID, "") // 全部未读;msgType 非空则按类型过滤
views, total, err := mgr.List(ctx, inbox.ListFilter{
UserID: userID,
MsgType: "biz", // 空 = 全部
OnlyUnread: false,
Page: 1,
Size: 20,
})
⚠️ 角标数字以 UnreadCount 为准,推送里只带 delta(信号)。
标已读 / 删除
err := mgr.MarkRead(ctx, userID, msgID) // 幂等:已读的不报错
affected, err := mgr.MarkAllRead(ctx, userID, "") // 返回影响条数
err := mgr.Delete(ctx, userID, msgID) // 防 IDOR:只能删自己的
wire 契约
List 返回 []inbox.MessageView(id / ref_id / sender_id 是 string,
read_at 未读为 null)。完整字段说明见 框架约定 §4。
注意事项
- ⚠️ 投递侧没有幂等键。
inbox.Message里没有去重字段,同一个业务事件调两次Notify会写两条。要"同一事件只发一次"得靠调用方自己带业务键去重 (或走 idempotentx 的幂等键)。包里唯一的幂等是 标已读:已读再标一次返 nil、不动数据。 - ⚠️
Message.Validate()里的"默认 system"是无效的。它的签名是值接收者func (m Message) Validate() error,函数体里的m.MsgType = "system"改的是副本, 调用方看不到 ——Notify里msg原样落库,msg_type是空串而不是"system"。 后果:按msg_type过滤(ListFilter.MsgType/UnreadCount的 msgType 参数) 永远筛不到这些消息。要按类型分类,调用方必须自己填MsgType。 - ⚠️ 推的 delta 恒为 +1,连"标已读"也是 +1。
publishUnread不区分方向, 因为并发投递 / 标已读会让 delta 累加漂移。所以前端必须重拉unread-count拿绝对值, 拿 delta 做 +1/-1 会在标已读之后让角标反而上涨。 前端useEventStream.refreshUnread就是这么做的。 - ⚠️ 动作完成后前端要自己拉一次角标,不等广播。广播是"状态变了"的信号,
不是"当前状态";连接建立之前发生的事件收不到。
InboxBell在markRead/markAllRead之后都直接调了一次refreshUnread()。 - ⚠️ 雪花 ID 在应用侧生成,不能交给 DB 自增。
BaseModel.ID的 tag 是primaryKey;autoIncrement:false,列是bigint unsigned且没有 AUTO_INCREMENT —— MySQL 严格模式下直接报 1364「Field 'id' doesn't have a default value」,一条都投不出去; 非严格模式更糟:全部写成id=0,而MarkRead(userID, 0)会把这个人的所有消息 一起标成已读。newRow是Notify/NotifyBatch唯一共用的地方,别在别处再抄一份 map。 - ⚠️
List扫[]model.InboxMessage而不是 map。GORM 的软删除作用域、model.Time的时间归一化、uint64的 string tag 三件事都只在 typed 扫描下才生效 —— 早先返回[]map[string]any时,wire 上是裸数字 ID(JS 的 2^53 会静默截断), 时间格式还出现了"本地时间带纳秒"和"UTC 秒级"两种。 - ⚠️ 两个方向的失败处理是相反的,刻意的:DB 写失败 ⇒ 返 error(业务层决定是否回滚主事务); Redis 不可用 ⇒ 推送静默丢弃(只是少了实时性,前端轮询兜底)。
- ⚠️ 列表过滤掉已过期,但保留已读;未读判定是
read_at IS NULL, 不是"比时间戳" —— 未读没有时间戳可比。 - ⚠️
RefID/SenderID为 0 时输出空串,不是"0"—— 0 的含义是"无关联 / 系统发的"。