notifyx —— 多通道通知分发
把"要通知某人"这件事,从"用哪个通道发"里拆开。 调用方只描述 给谁、说什么;分发器决定 走哪几条通道、 以及 某条通道挂了怎么办。
功能
notifyx 解决的是"通知通道各自为政、失败语义没统一"这件事:
- 通道抽象:
Channel接口 ——Name()+Send(ctx, Recipient, Message) error。 自定义通道就是实现两个方法(示例里有一个logChannel)。 - 一次通知多通道:
Dispatcher按注册顺序逐条投递,收件人 / 内容只描述一次。 - 失败隔离:单条通道失败不牵连其它通道,失败收进
Result.Failed(map,一个通道对一条错误)。 - panic 隔离:每条通道的调用都
recover,panic 记成该通道 failed。 - 组合投递器
Fanout:站内信(记录)+ 额外交付通道(送达)拼在一起, 它实现了inbox.Notifier—— 装配处把它塞进原来inboxMgr的位置, 所有既有的站内信投递自动多出一条通道,调用方一行都不用改。
不解决什么:
- 不认识审批 / 站内信的业务语义 —— 只认
Recipient+Message; - 不做投递幂等;
- 不做权限判定。
配置
yaml 侧
该包自身无 yaml 配置块。 它没有 notifyx: 段。
生产装配在 cmd/server 里,读的是 email: 块(邮件通道要发件地址和站点外链前缀):
email:
provider: "" # "" / console / smtp / aliyun
from: "" # 发件邮箱(缺省取 smtp.username / aliyun.account_name)
from_name: Admin Console
base_url: "" # 站点外链前缀 —— 邮件里的链接要拼成绝对地址
timeout: 30 # 单次发送超时(秒)
⚠️ email.provider 为空串 = 这条通道不存在(不是"配好了但关着")。
此时 buildNotifierDispatcher 一个通道都不注册,Fanout 就只剩站内信。
"配置了但没生效"比"没配"更难查 —— 运维看着 yaml 里有 email 段,以为在发邮件。
代码侧(构造选项)
d := notifyx.NewDispatcher(channels ...Channel) // 可预置通道
d.Register(c) // 运行时注册(同名覆盖)
fanout := notifyx.NewFanout(inner, d, resolver) // 额外交付异步(生产)
fanout := notifyx.NewSyncFanout(inner, d, resolver) // 同步(只给测试用)
inner:inbox.Notifier(站内信那一份,必填)dispatcher:*notifyx.Dispatcher(额外交付通道,可空 = 只有站内信)resolver:notifyx.Resolver(UserID → Recipient,可空 = 不投递)
使用方法
只用分发器(纯多通道)
d := notifyx.NewDispatcher(
&logChannel{name: "email"},
&logChannel{name: "sms"},
)
res := d.Dispatch(ctx, notifyx.Recipient{
UserID: 1001,
Email: "zhangwei@example.com",
Phone: "13800001234",
}, notifyx.Message{
Title: "您有一条新的审批待办",
Content: "请在 24 小时内处理",
Link: "/approval/8801",
RefType: "approval",
RefID: 8801,
})
res.Delivered // []string 成功投递的通道名
res.Skipped // []string 收件人不适用(比如没邮箱)
res.Failed // map[string]error 失败通道 → 错误
res.OK() // bool 至少有一条通道投递成功
res.Err() // error 所有失败用 errors.Join 汇总
自定义通道
type logChannel struct{ name string }
func (c *logChannel) Name() string { return c.name }
func (c *logChannel) Send(ctx context.Context, r notifyx.Recipient, m notifyx.Message) error {
// 没有邮箱 = skipped,不算失败
if r.Email == "" {
return fmt.Errorf("%w: 用户 %d 没填邮箱", notifyx.ErrSkip, r.UserID)
}
return nil
}
⚠️ 用 errors.Is(err, notifyx.ErrSkip) 判跳过,不要用 == ——
通道实现可能在 ErrSkip 上再包一层(带上下文),== 会漏判,把"跳过"记成"失败"。
组合投递器(站内信 + 邮件)
notifier := notifyx.NewFanout(
inboxMgr, // 站内信(记录)
buildNotifierDispatcher(emailSender, cfg.Email), // 额外交付(送达)
notifyx.NewDBResolver(db), // UserID → 联系方式
)
// 装配进 Registry:InboxNotifier: notifier —— 业务侧照旧调 Notify
DBResolver 从 sys_user 读 email / phone,并做格式校验:
不像邮箱的值一律当"没有邮箱",不像手机号(11 位 / 1 开头 / 全数字)的值一律当"没有手机号"。
注意事项
- ⚠️ 两个方向的失败语义是相反的,别混:
- 站内信是"记录":写库失败 ⇒
Notify返 error,业务层据此决定是否回滚主事务; - 额外交付是"送达":邮件 / 推送失败 ⇒ 只记 Warn 日志,不返 error。 审批单已经落库,不该因为"邮件没发出去"让审批失败。 两者混成一个返回值,调用方就没法区分"没发出去"和"发出去但没收到"。
- 站内信是"记录":写库失败 ⇒
- ⚠️ "没有某个联系方式"是 skipped,不是 failed —— 后台账号大量不填邮箱,那是常态。
记成 failed 会让"投递成功率"这个指标永远掉。
⚠️ 但"通道自己没配好"是 failed,不是 skipped:邮件通道
from为空返的是 普通 error(不是ErrSkip),因为 skip 会让"配错了却没人发现"。 这就是 email 通道内部两种"没发出去"方向相反的地方。 - ⚠️ 分发器里目前只有邮件一条通道 —— 推送通道(
pushx)故意没挂: 推送要的是设备令牌(APNs device token / 厂商 registration id),全仓没有那张登记册, 挂上去每条通知都会 skip,看着像"接上了"其实没发。pushx的 sender 走registry.PushSender交给业务侧,登记册落地后再接。 - ⚠️ 异步投递必须脱离请求 ctx。
Fanout.deliverExtra用context.WithoutCancel(ctx)+ 独立 30s deadline:请求超时后 ctx 已经死了, 拿它发邮件必然失败,表现是"审批成功了但收件人没收到邮件"。 ⚠️ 30s 不是随便取的 —— 站内信是写库 3s 够,邮件要跟外网 SMTP 握手 + 传输, 3s 会把正常投递判成超时。 - ⚠️
NewSyncFanout只给测试用。同步投递会把一次 SMTP 往返挂在调用方的关键路径上, 而调用方可能正处在 HTTP 请求里。 - ⚠️ 分发是串行的,不是并发。三个理由:通知不是热路径;串行时
Result的通道顺序 = 注册顺序,可复现(并发时每次都不一样,排查时对不上);邮件(SMTP)本身有连接成本, 并发发反而更容易被对方限流。 - ⚠️
Register同名通道直接覆盖,不并存。重复注册会让Result里的通道名出现两次, 排查时根本分不清是哪一次投递。 - ⚠️
Result.Failed是 map 不是 slice —— 多个通道可能同时失败, map 才能一个通道对一条错误;slice 只能记"有失败",查不出是哪条。Result.Err()用errors.Join汇总,多个失败都要看得见,只留最后一个是丢信息。 - ⚠️ 邮件正文是 HTML,内容来自业务 —— 一律
html.EscapeString转义。 不转义的话,标题里一个<script>就会在邮件客户端里执行 (邮件客户端会禁脚本,但 HTML 注入照样能改样式、伪造钓鱼链接)。 - ⚠️ 邮件里的相对链接是死的。收件人的邮件客户端不知道"当前站点"是哪个,
点
/approval/123会被解析成本地文件路径。baseURL没配时:绝对链接照用, 相对链接丢掉(好过给一个点不开的链接)。 - ⚠️ 站内信批量是"要么全成要么全败"(inbox 侧一个事务), 额外交付是逐条尽力而为 —— 一封邮件发不出去不该让另外十九封也不发。
- ⚠️
notifyx.Message不重复定义站内信字段。Title/Content/Link/RefType/RefID的语义跟inbox.Message完全一致,重复一份就是漂移的起点。Fanout的做法是直接复用inbox.Message,只搬有对应语义的字段 ——inbox里的MsgType/SenderID/ExpiredAt在"投递"这一层没有对应物。