5.4 KiB
5.4 KiB
系统架构与技术模式
服务拓扑(cmd/ 下多入口,共享 internal/)
| 服务 | 入口 | 职责 |
|---|---|---|
| gateway | cmd/gateway |
主服务:HTTP API(:8081 dev)+ CMPP Server(下家接入)+ Web 静态代理;含长短信聚合/挂起维护(reaper)、调度唤醒扫描 |
| consumer | cmd/consumer |
Kafka 消费:Deferred 事件补全(拦截/落库/审核/路由/分发)、回执(report)消费配对 |
| scheduler | cmd/scheduler |
定时任务调度(与 gateway 的 5s ZSet 扫描协同) |
| business | cmd/business |
业务服务(独立部署形态) |
| migrate | cmd/migrate |
迁移执行器(gormigrate v1~v19;seed-admin 引导超管,密码仅打印一次) |
| reconcile | cmd/reconcile |
对账补偿 |
| 探针/工具 | authprobe cmppbench longsmsprobe probe smppsmoke |
真机验收探针(验收后多数即删,如 probe_longsms) |
分层架构(internal/)
internal/
├── api/http/v1/ # HTTP handler(REST /api/v1/*;命名 <域>_handler.go + <域>_dayNN_test.go)
├── app/ # 应用装配骨架
├── config/ # 配置结构体;viper 加载,GOSMS_ 前缀环境变量覆盖
├── middleware/ # gin 中间件(鉴权/限流含动态账号桶/审计/CORS…)
├── model/entity/ # GORM 实体(雪花主键 SnowflakeModel 公共结构)
├── pkg/ # 内部共享:logger(zap)/metrics(prometheus)/queue(Kafka producer)/cache(freecache)/lock
├── protocol/ # 协议实现:cmpp(客户端+服务端+池)/smpp/sgip/httpadapter
├── repository/ # 数据访问(mysql;migrations.go 集中迁移定义 v1~v19)
├── router/ # 四步路由引擎(账号级 steer 绑定快照)
├── service/ # 业务域:access(cmpp 接入+长短信聚合)/account/audit/auth/balance/channel/interceptor/openapi/report/router/send/template/uplink
└── util/ # SmsLength/SmsLengthUCS2 计费口径等纯函数
核心数据流
下行主链(受理→下发→回执)
- 受理快路径
send.SubmitFast(Day 63):Validate(内存)→ holdFastLua Redis 哨兵预扣(欠费=唯一同步拒)→ DetailID 雪花预生成 → EmitSubmit 投 Deferred Kafka 事件(task.ID=0,零 DB 写)。 - 消费侧补全
send/consumer.handleDeferred:拦截链判定(命中→明细终态 5+退费)→ task INSERT 补建(uk_task_no 冲突=重投,已分流 audit≠0 跳过 Route)→ 明细落库+拦截回执桥 → 全拦任务终态 → 审核 Route → claim/dispatch。 - 下发:ChannelDispatcher(router 选路)→ protocol/cmpp 池连接 SubmitViaLink 真链路;MsgID 口径=DetailID 雪花(与回执 Deliver msg_id 同口径)。
- 回执 report 域:Kafka 消费回执 → pair(配对)→ 明细终态 → 退费/统计;UNKNOWN 挂起窗 72h;compensator 补偿。
入向长短信(Day 71 挂起制,当前语义)
- 片聚合:组 ID=首片雪花,N 片 Resp 复用;完整性优先——72h 窗内不齐=不提交/不推终态/不扣费;到期不齐=reaper 建失败终态(task
LP+组IDuk 幂等/detail id=组ID status=3 fee=0LSM:NOTCMPL)+UNDELIV 经 Kafka cmpp-deliver 回环推下家。 - 持久化:迁移 v19
longsms_pending表(一行一未齐组,首片 INSERT/续片 UPDATE/到齐 DELETE);启动 restore 回内存;reaper 1min 扫描每轮≤500 行;组上限 16384 超限拒绝。
计费口径(Day 70 根修)
- fee≡上游真实拆分片数;分流优先级
FeeSegments>0 直接采信 > UCS2 编码按 SmsLengthUCS2 > 默认 SmsLength(GBK);CMPP MsgFmt 透传至受理计费点。
关键技术模式
- 幂等三锚:task_no uk / detail pk(雪花) / OnConflict DoNothing——重复扫描、重投、并发路径至多一次生效。
- 雪花生成的 MsgID/DetailID 全链统一,回执配对键跨重启一致。
- 每分区 worker 池(Day 65):WorkersPerPartition+连续前缀有序 Mark,at-least-once 等价;
done容量≥2w+2。 - 延迟关联三段式查询(Day 64):窄 Count → 窄列分页 Pluck id →
id IN回表全宽 JOIN(明细页 82s→645ms);无 start_time 缺省 5 天窗。 - 配置注入:SystemLimits(grouper.window 等)注入 service 构造函数,测试可直接调;
config.dev.yaml默认,环境变量GOSMS_(层级_连接)覆盖任意键。 - 迁移:gormigrate 集中于
repository/mysql/migrations.go(末块 v19);不走 entity tag 加索引(SnowflakeModel 公共结构避免波及全部雪花表)。 - 降级策略:DB 写失败 Warn 降级继续内存聚合;Redis 故障 DB 直查降级;producer 降级时 push=nil 只落失败记录。
- 前端模式:Vue3 setup + pinia + vue-router;msw Mock/real 双模式(
VITE_API_MODE,.env.development.localgitignore 持久化 real);样式三件套 tokens/ep-theme/shell(token 化禁原子类);ProTable 组件(骨架/空态/密度/列显隐/分页)。 - 测试模式:单测用 sqlite(glebarez)或 miniredis;
<域>_dayNN_test.go按验收日命名;集成测试go test -tags=integration ./test/integration/...(真实中间件);e2e Playwright(web/tests)。
命名与代码约定
- 后端 handler:
internal/api/http/v1/<域>_handler.go;错误码 ISC-xxx(ISC_CN 字典前端 tooltip)。 - 前端视图:
web/src/views/<域>/<页>/index.vue;语义类前缀(sc-/rec-/audit-/ce- 等)替代原子类;tailwind 已移除。 - 日志:结构化字段(如
cmpp_longsms_expire_fail/cmpp_deliver_pushed),trace_id 贯穿(runbook SOP 定位入口)。