64 lines
5.4 KiB
Markdown
64 lines
5.4 KiB
Markdown
# 系统架构与技术模式
|
|
|
|
## 服务拓扑(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 计费口径等纯函数
|
|
```
|
|
|
|
## 核心数据流
|
|
|
|
### 下行主链(受理→下发→回执)
|
|
1. **受理快路径 `send.SubmitFast`**(Day 63):Validate(内存)→ holdFastLua Redis 哨兵预扣(欠费=唯一同步拒)→ DetailID 雪花预生成 → EmitSubmit 投 **Deferred Kafka 事件**(task.ID=0,零 DB 写)。
|
|
2. **消费侧补全 `send/consumer.handleDeferred`**:拦截链判定(命中→明细终态 5+退费)→ task INSERT 补建(uk_task_no 冲突=重投,已分流 audit≠0 跳过 Route)→ 明细落库+拦截回执桥 → 全拦任务终态 → 审核 Route → claim/dispatch。
|
|
3. **下发**:ChannelDispatcher(router 选路)→ protocol/cmpp 池连接 SubmitViaLink 真链路;MsgID 口径=**DetailID 雪花**(与回执 Deliver msg_id 同口径)。
|
|
4. **回执 report 域**:Kafka 消费回执 → pair(配对)→ 明细终态 → 退费/统计;UNKNOWN 挂起窗 72h;compensator 补偿。
|
|
|
|
### 入向长短信(Day 71 挂起制,当前语义)
|
|
- 片聚合:组 ID=首片雪花,N 片 Resp 复用;**完整性优先**——72h 窗内不齐=不提交/不推终态/不扣费;到期不齐=reaper 建失败终态(task `LP+组ID` uk 幂等/detail id=组ID status=3 fee=0 `LSM: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.local` gitignore 持久化 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 定位入口)。
|