smsaudit —— 短信发送审计:发了什么、发给谁、成没成
"这条验证码到底发出去了没有""用户说没收到短信,到底是服务商拒了还是我们根本没发" —— 每次发送都要留痕:手机号、场景、验证码、provider、成没成、耗时多少、上游 request_id。
功能
smsaudit 解决一件事:把"每一次短信发送的完整轨迹"变成可查的表。
能力:
- 装饰器接入(推荐) ——
smsaudit.Wrap(realSender)包一层,发送结果自动落审计, 耗时也由装饰器量,业务代码一行不用改。 - 手工记录 —— 不走装饰器时用
smsaudit.Record(ctx, smsaudit.SendLog{...})。 - 失败也落库 ——
Success=false+ErrorMsg+ 服务商返回的原文。 - 异步攒批 —— 100 条或 5s 落一次库,单次插入按 50 条分片。
- ctx 上下文自动带 —— principal / request_id / trace_id / ip / user_agent。
不解决:
- 不拦发送 —— 限流在 smslimit,模板审核在 smstpl。
- 不负责选服务商 —— 那是 msn;本包只是给 sender 包一层。
- 不做脱敏 ——
phone和code都明文入库(产品要求:用户报"收到的不是这个"时能 反查)。代价是这张表本身就是敏感数据,查询接口要收权限。
配置
代码侧(没有构造选项)
smsaudit 是包级单例:
| 符号 | 说明 |
|---|---|
smsaudit.Init(db *gorm.DB) |
启动期调一次(sync.Once 包着)。db == nil ⇒ 打一条 Warn(smsaudit: db is nil, recorder disabled)并保持关闭(不起后台 loop) |
smsaudit.Shutdown() |
退出前调一次,等最后一批 flush 完。幂等 |
smsaudit.Wrap(inner msn.Sender) msn.Sender |
装饰器。装配期包一层即可 |
攒批参数是包内常量,不可配:defaultBatchSize = 100、defaultFlushInterval = 5s、
defaultRetryTimes = 3、单次插入分片 CreateInBatches(batch, 50)。
yaml 侧(audit: 块)
configs/config.example.yaml 里确实有一个 audit: 块:
audit:
batch_size: 100
flush_interval: 5000 # ms(整数不带单位 —— 写成 "5s" 会让整份配置反序列化失败)
queue_size: 10000
⚠️ 这三个键本包不读。config.AuditConfig(internal/config/crypto.go)定义了它们,
但全仓零消费方 —— 三个审计包的攒批参数都写死在包内常量里。改 yaml 不生效。
使用方法
装配(装饰器,推荐)
真实 sender 的构造在 cmd/server/main.go 的 6.5 步,smsaudit.Wrap 是最后一步:
rawSmsSender := buildSmsSender(cfg.SMS, ccSvc.ResolveSMSConfig, smsTplRuntime.Guard())
smsSender := smsaudit.Wrap(rawSmsSender) // 装饰:计时 + 写审计
装配期包一层,再把 smsSender 传给任何要发短信的地方(它仍是 msn.Sender 接口)。
装饰器包一层就够,业务侧还是只认 msn.Sender:
var sender msn.Sender = smsaudit.Wrap(real)
err := sender.Send(ctx, "13800001234", "123456", "login")
手工记录
smsaudit.Record(ctx, smsaudit.SendLog{
Phone: "13800001234",
Scene: "login",
Code: "123456",
Provider: "aliyun",
Success: true,
CostMs: 234,
})
SendLog 字段
| 字段 | 类型 | 说明 |
|---|---|---|
Phone |
string |
手机号(明文入库) |
Scene |
string |
业务场景(login / reset_password / ...) |
Code |
string |
验证码(明文入库,供反查) |
Provider |
string |
aliyun / console |
Success |
bool |
成没成 |
ErrorMsg |
string |
失败原文 |
CostMs |
int |
下发耗时(ms) |
UpstreamReqID |
string |
上游 request_id(阿里云那边给的) |
完整可运行示例
examples/smsaudit/main.go —— go run ./examples/smsaudit
示例里用一个假 sender 演示"成功 / 失败"两条路径,手写 DDL 建表(框架示例不许 import 业务模型)。
注意事项
- ⚠️ ctx key 已统一到 piiaudit(2026-11-01 修的坑)。本包原来自己定义了一套私有
ctxKeyRequestID{}/ctxKeyTraceID{},而全仓唯一注入这两样东西的地方是internal/api/middleware/trace.go,它用的是 piiaudit 的 key (piiaudit.InjectRequestID/InjectIP/InjectUA)。两套 key 谁也读不到谁 ⇒sys_sms_send_log.request_id/trace_id在生产里恒为空;ip / user_agent 更是 从来没读过(表里有那两列,兄弟包 cryptaudit 一直在读同一套 key)。 现在本包的InjectRequestID/InjectTraceID/InjectIP/InjectUA全部转发给 piiaudit,读写同一套 key。 ⚠️ 自建包不要另起一套 ctx key —— 全仓只有middleware/trace.go一处注入, 键名对不上就全空,而且是静默全空。 - ⚠️
Shutdown()幂等是后补的。兄弟包 piiaudit / cryptaudit 在 M100 就改成幂等了, 本包漏了,2026-11-01 才补(原来第二次调用close已关闭的 channel → panic)。 幂等的sync.Once放在Recorder上而不是包级变量 —— 每个 Recorder 各自 只关一次,换global也不会误伤别的实例。 - ⚠️ 装饰器不吞错误。底层
Send返什么错,装饰器原样往上抛 —— 审计只是旁路, 不是替业务做决定。 - ⚠️ 装饰器会额外打一条 Warn(
sms send failed),里面带 明文 phone。 审计表里手机号明文是有意的(合规要求能反查),但日志里最好打码 —— 别让完整手机号 跟着日志跑到 ELK 里。 - ⚠️ 装饰器不填
UpstreamReqID。阿里云返回的上游 request_id 装饰器拿不到,那一列 会是空串;需要它就得自己Record手工填。 - ⚠️ 别 wrapper of wrapper。包两次就会同一次发送记两条。
- ⚠️
code(验证码)也明文入库。sys_sms_send_log.code存的是真实下发的值 —— 这是"用户报收到的不是这个"时唯一的反查依据,但也意味着这张表里有明文验证码。 别给它开放导出接口。 - ⚠️ 本包不记角色。
SysSmsSendLog没有role_code列(extractFromCtx也不取RoleCode),查"谁发的"只有user_id/identity_id;兄弟包 piiaudit / cryptaudit 是有role_code的。 - ⚠️ 落库是异步的。
Record只往内存缓冲里塞。进程退出前不调Shutdown(),最后 一批(最多 99 条)会丢。 - ⚠️
Shutdown()之后还能Record,但大多数数据不会落库。后台 flush loop 已退出, 不再有 5s 定时 flush;只有攒到 100 条触发append()里的同步 flush 分支才会写下去。 - ⚠️ 忘了
Init⇒Record静默 no-op(if global == nil { return }),连日志都没有。 只有Init(nil)才会打那条 Warn。 - ⚠️
Init只能生效一次(sync.Once包着)。测试里想换个 db 重新Init是无效的, 静默 no-op。三个兄弟包都一样。
相关
- 源码:
internal/pkg/smsaudit/ - 可运行示例:
examples/smsaudit/main.go——go run ./examples/smsaudit - 兄弟包:piiaudit / cryptaudit
- 短信发送链路:msn(sender 抽象)