Files
junhong_cmp_fiber/.planning/research/STACK.md
2026-03-27 19:04:17 +08:00

14 KiB
Raw Blame History

Stack Research

Domain: IoT 卡管理平台 — SIM 卡全生命周期 + 代理分销 + 分佣结算 Researched: 2026-03-27 Confidence: MEDIUM-HIGH(核心技术栈 HIGH,外围选项 MEDIUM)


结论先行:当前技术栈评估

整体结论:当前技术选型对于该领域是合理的,无需大规模替换。 存在 3 个明确的技术债和 1 个值得关注的升级时机。

组件 当前版本 最新版本 状态 建议
Fiber v2.52.9 v3.1.0 ⚠️ 大版本落后 保持 v2,不升级(见分析)
GORM v1.31.1 v1.31.x ✅ 最新 继续使用
Asynq v0.25.1 v0.26.0 ⚠️ 落后一个版本 可选升级(安全依赖升级)
go-redis v9.7.0 v9.18.0 ⚠️ 落后较多 建议升级(无 API 破坏性变更)
sonic v1.14.2 v1.14.x ✅ 近期版本 继续使用
PowerWeChat v3.4.38 v3.4.38 ✅ 最新 继续使用
Go runtime 1.25.x 1.25.x ✅ 最新 继续使用

核心技术栈

一、HTTP 框架 — Fiber v2(继续坚守)

项目 内容
当前版本 v2.52.9(已是 v2.x 最新)
最新大版本 v3.1.0(2026-02-02 正式发布)
不升级的原因 v3 有重大破坏性变更,迁移成本高,且本项目有大量存量代码

v3 核心破坏性变更(对本项目影响分析):

  1. c.UserContext() 被移除 → Ctx 本身现在实现 context.Context,直接传 c 即可。

    • **影响:**本项目全代码库大量使用 c.UserContext() 传递用户 Context 到 Service/Store 层,这是最大的迁移成本。
    • **估算:**全局搜索 UserContext() 调用点,预估 100+ 处改动。
  2. c.BodyParser() 移除 → 改用 c.Bind().Body()

    • **影响:**所有 Handler 层的请求解析代码需要改写。
  3. 路由注册 Add 方法签名变更 → 影响 internal/routes/registry.go 的统一注册逻辑。

  4. app.Mount() 移除 → 使用 app.Use()。

置信度:HIGH(官方文档 https://docs.gofiber.io/whats_new/ 已确认)

建议: 保持 v2.52.x,待 v2 EOL 公告或下一个重大重构机会再考虑升级。v2 安全维护至少到 2026 年底,风险可控。


二、ORM — GORM v2(继续使用,无更好替代方案)

2026 年 Go ORM 格局:

ORM 定位 适合本项目
GORM 全功能 ORM,code-first,ActiveRecord 风格 ✅ 最适合
sqlc 编译时类型安全,从 SQL 生成 Go 代码 ❌ 需要从头重写所有查询
sqlx SQL 轻量封装,接近原生 database/sql ❌ 需要全部改写,收益有限
ent 图模型 ORM,compile-time type safety ❌ 学习成本高,编译慢,不适合现有代码库

为什么 GORM 对本项目是正确选择:

  • CRUD 密集型应用(卡管理、套餐管理、订单、佣金),GORM 的约定优于配置大幅减少样板代码
  • 软删除、钩子(Hooks)、事务等特性本项目大量依赖
  • 当前 v1.31.x 已是最新,无需升级

GORM 的已知性能问题(针对本项目的建议):

  • 多级代理佣金树查询(最深 7 层)不应使用 GORM Preload,而应使用原生 WITH RECURSIVE CTE
  • 批量导入(ICCID Excel)应使用 db.CreateInBatches() 而非逐行 Create()

置信度:HIGH(多个 2026 年对比文章,主流观点一致)


三、任务队列 — Asynq(继续使用,考虑升级到 v0.26.0)

最新版本: v0.26.0(2026-02-03 发布)

版本 关键变更
v0.25.1(当前) 安全依赖升级 + 增加 RedisUniversalClient 支持
v0.26.0 增加 Task Headers 支持(PR #1070)+ TLS 选项 + 最低 Go 版本升至 1.24

为什么不替换 Asynq: 在 IoT 卡管理场景中,Asynq 的优势:

  • 基于 Redis(与现有基础设施共享,无额外运维成本)
  • 内置定时任务调度(Scheduler)适合轮询任务场景
  • 任务可视化(Asynqmon Web UI)在生产调试中有价值
  • 竞品(Machinery、Watermill)依赖更重,对单节点场景没有额外收益

建议: 升级到 v0.26.0(go get github.com/hibiken/asynq@v0.26.0),主要收益是上游安全依赖修复,API 完全兼容。

置信度:HIGH(GitHub Releases 直接验证)


四、Redis 客户端 — go-redis v9(建议升级)

当前版本: v9.7.0 最新版本: v9.18.0(2026-02-16)

v9.7.0 → v9.18.0 跨越 11 个 patch 版本,均为向后兼容。建议升级原因:

  • 包含若干 bug 修复和性能改进
  • 升级命令:go get github.com/redis/go-redis/v9@v9.18.0

置信度:MEDIUM(pkg.go.dev 直接确认版本)


五、JSON 序列化 — sonic(继续使用)

sonic(bytedance/sonic) 在 2025 年基准测试中仍是 Go 生态最快的 JSON 库:

库 相对速度 适用场景
sonic ~3-4x 快于 std 高并发 API,大 payload(如 Excel 导入响应)
encoding/json v2(Go 1.25 内置) ~1.8x 快于 std 标准库,无需引入依赖
encoding/json(std) 1x 基线 无额外依赖场景

注意: Go 1.25 引入了 encoding/json/v2,性能约为 sonic 的 50%,但消除了历史行为不一致问题。对于本项目,sonic 仍是正确选择:本项目已集成且使用 Fiber 的 sonic 替换,迁移收益不大。

置信度:HIGH(2025-09 Reddit benchmark + Trendyol 生产迁移案例)


领域特有技术栈缺口分析

缺口 1:金融精度问题 ⚠️(重大技术债)

问题描述: IoT 卡管理平台涉及两类精度敏感计算:

  1. 货币金额:钱包余额、佣金金额(差价佣金、一次性佣金)、套餐价格
  2. 流量计费:MB/GB 流量用量计算、按比例退款

当前实现风险:

  • 余额字段使用 int64(存储"分")—— 钱包余额做法正确
  • 但佣金链计算(差价 = 上层价格 - 下层成本)中,如果涉及百分比分佣(如"提成 15%"),用 float64 计算后再转 int64 会有精度损失

标准做法(2025 年行业共识):

选项 A:纯整数(分/厘)存储,避免所有浮点运算
  - 适合固定金额计算
  - 本项目钱包余额已是此做法 ✅
  
选项 B:shopspring/decimal(用于百分比/比例计算)
  - 适合佣金比例计算、退款按比例扣减
  - 7000+ GitHub stars,已是 Go 社区财务计算标准库
  
选项 C:go-money(Rhymond/go-money)
  - 适合多币种场景,本项目不需要

建议: 引入 github.com/shopspring/decimal v1.4.0,仅用于:

  • 佣金比例计算(如方案 I-3:退款按比例扣减代理佣金)
  • 流量按比例计费(方案 E 的流量体系改革)

不需要全局替换 int64 余额字段,仅在需要乘除法的计算环节使用 decimal,最终结果转 int64 存储。

置信度:HIGH(Modern Treasury 官方博客 2025-08 + shopspring/decimal 7286 stars)


缺口 2:多级代理查询性能 ⚠️(架构风险)

问题描述: 本项目代理层级最多 7 层,GetSubordinateShopIDs() 使用 PostgreSQL WITH RECURSIVE CTE 查询,结果缓存 30 分钟。这个架构是正确的。

潜在风险:

  • 佣金链计算时,N 层递归分佣可能退化为 N 次单独 DB 查询(N+1 问题)
  • 7 层 × 每层查询 = 最坏 7 次 DB 往返,而 DB 查询要求 < 50ms

2025 年标准方案: 对于多级分佣树计算,行业标准是一次性将整条链路数据加载到内存,而非逐层查询:

-- 一次性获取完整佣金链(从叶子节点到根节点)
WITH RECURSIVE commission_chain AS (
  SELECT shop_id, parent_id, level, 0 AS depth
  FROM tb_shop WHERE id = $1
  UNION ALL
  SELECT s.shop_id, s.parent_id, s.level, cc.depth + 1
  FROM tb_shop s
  INNER JOIN commission_chain cc ON s.id = cc.parent_id
)
SELECT * FROM commission_chain ORDER BY depth;

当前代码已经有 WITH RECURSIVE 基础,但需要确认佣金计算是否利用了这个能力。

置信度:MEDIUM(基于代码库 PROJECT.md 分析 + PostgreSQL 官方文档)


缺口 3:可观测性 ⚠️(生产上线前需解决)

问题描述: 当前技术栈的可观测性仅有:

  • 应用日志(Zap)
  • 访问日志
  • Asynq 任务状态(via Asynqmon 可选)
  • 健康检查 GET /health

缺失:

  • 没有指标(Metrics)收集
  • 没有链路追踪(Tracing)
  • 没有告警(Alerting)

对于当前阶段(MVP 修复上线): 可以暂时接受,PROJECT.md 的 Out of Scope 已明确 "P2-6 告警通知渠道 — 无关紧要,暂不做"。

但如果平台上线后扩展:

  • 轻量级方案:Prometheus + Grafana(已是 Go 社区标准)
  • 零侵入方案:OpenTelemetry Go SDK(标准化,支持后续接入任意后端)

置信度:MEDIUM(基于 Go 社区 2025 年可观测性实践)


缺口 4(IoT 领域特有):运营商网关客户端 — 无通用标准库

问题描述: 本项目有 internal/gateway/client.go(外部 Gateway 服务 HTTP 客户端)。IoT SIM 卡管理平台通常需要对接:

  • GSMA M2M 标准(SM-DP+/SM-DS for eSIM)
  • 运营商私有 API(中国联通、移动、电信)

2025 年实际情况: 国内运营商 IoT 平台(移动 OneNET、电信 CTWing、联通 Open)均为私有 REST/SOAP API,没有标准化的 Go SDK。

当前项目自研 internal/gateway/client.go 是唯一可行路径,符合行业惯例。

置信度:HIGH(行业调研确认,无通用 Go SDK 存在)


当前栈中已弃用/有问题的依赖

依赖 问题 建议
aws/aws-sdk-go (v1) AWS SDK Go v1 已于 2025-07-31 进入 Maintenance Mode,不再接收功能更新 低优先级,当前对接联通云 OSS,可继续使用;如有大范围重构可迁移到 aws/aws-sdk-go-v2
excelize/v2 无严重问题,版本跟进即可 —

AWS SDK v1 注意: 仅 Maintenance Mode,不是 End of Life,安全补丁仍会发布。迁移到 v2 需要较大代码改动,不建议在当前 MVP 阶段操作。

置信度:MEDIUM(AWS 官方公告,2025-07-31)


可选补充库

以下库不在当前技术栈中,但对特定需求有价值:

库 版本 用途 引入时机
shopspring/decimal v1.4.0 佣金比例计算、退款按比例计算 方案 I(退款)实现时
golang-migrate/migrate v4.18.x 数据库迁移(已在项目使用) — 已用
hibiken/asynqmon latest Asynq 任务可视化 Web UI 生产环境调试时

替代方案对比

类别 当前选择 备选 不替换的理由
HTTP 框架 Fiber v2 Gin, Echo, Chi, Fiber v3 大量存量代码;v3 破坏性变更成本高
ORM GORM sqlc, sqlx, ent 项目已深度集成,CRUD 场景 GORM 是最优解
任务队列 Asynq Machinery, Watermill, Temporal Redis 复用优势;Temporal 对单节点过重
消息队列 无(Asynq 兼任) NATS, Kafka 当前规模不需要独立 MQ
缓存 Redis Memcached Redis 功能更丰富,已是基础设施
数据库 PostgreSQL MySQL, CockroachDB PostgreSQL 的递归 CTE 对层级数据有优势
JSON sonic encoding/json, json/v2 sonic 性能优势在高并发场景显著

版本兼容性注意事项

依赖组合 状态 注意
Fiber v2 + Go 1.25 ✅ 兼容 Fiber v2.52.9 已适配 Go 1.25
Fiber v3 + Go 1.25 ⚠️ 要求 Go 1.25+ v3 以 Go 1.25 为最低版本
Asynq v0.26.0 + Go 1.25 ✅ 兼容 v0.26.0 要求 Go 1.24+,1.25 满足
GORM v1.31.1 + PostgreSQL 14+ ✅ 兼容 —
PowerWeChat v3.4.38 + Go 1.25 ✅ 兼容 官方声明 Go 1.23+

关键技术债总结(优先级排序)

P0:必须在上线前解决

金融精度风险(佣金计算)

  • 检查所有涉及百分比/比例的佣金计算代码,确认没有 float64 中间步骤
  • 方案 I(退款按比例扣减佣金)实现时必须引入 shopspring/decimal

P1:上线后尽快处理

go-redis 版本落后

  • 从 v9.7.0 升级到 v9.18.0,无 API 破坏性变更,安全隐患修复

Asynq 版本落后

  • 从 v0.25.1 升级到 v0.26.0,获得安全修复

P2:中期规划

AWS SDK v1 → v2 迁移(对象存储)

  • 不紧急,v1 仍有安全支持,规划下一个重大重构时处理

Fiber v2 → v3 迁移评估

  • v2 仍在维护,不需要立即升级
  • 建议在明年底(2027)重新评估是否升级

安装/升级命令参考

# 升级 Asynq(推荐)
go get github.com/hibiken/asynq@v0.26.0

# 升级 go-redis(推荐)
go get github.com/redis/go-redis/v9@v9.18.0

# 引入 decimal(P0 佣金精度修复时)
go get github.com/shopspring/decimal@v1.4.0

# 升级所有兼容依赖(谨慎,逐一验证)
go get -u ./...

Sources

来源 内容 置信度
https://docs.gofiber.io/whats_new/ Fiber v3 破坏性变更完整列表 HIGH
https://newreleases.io/project/github/hibiken/asynq/release/v0.26.0 Asynq v0.26.0 发布说明 HIGH
https://pkg.go.dev/github.com/redis/go-redis/v9 go-redis 最新版本 v9.18.0 HIGH
https://reintech.io/blog/sqlc-vs-gorm-vs-sqlx-go-database-libraries-compared-2026 GORM vs sqlc vs sqlx 2026 深度对比 MEDIUM
https://encore.cloud/resources/go-orms Go ORM 2026 对比(GORM/sqlc/ent) MEDIUM
https://pkg.go.dev/github.com/shopspring/decimal@v1.4.0 shopspring/decimal v1.4.0 HIGH
https://www.moderntreasury.com/journal/floats-dont-work-for-storing-cents 金融精度使用整数的行业实践 HIGH
Reddit r/golang 2025-09 JSON benchmark sonic vs std vs json/v2 基准 MEDIUM
https://pkg.go.dev/github.com/ArtisanCloud/PowerWeChat/v3@v3.4.38 PowerWeChat 最新版本确认 HIGH

Stack research for: IoT SIM 卡管理平台(Go + Fiber + GORM + Asynq + PostgreSQL + Redis) Researched: 2026-03-27