huang
4856a88d41
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 43s
5.5 KiB
5.5 KiB
提案：Gateway API 统一封装
Why
当前项目需要调用外部 Gateway API 来实现物联网卡和设备的生命周期管理功能（状态查询、停复机、设备控制等）。Gateway API 具有以下特点：
- 复杂的认证机制：需要 AES-128-ECB 加密 + MD5 签名
- 多个接口：14 个 API（流量卡 7 个 + 设备 7 个）
- 多场景调用：Handler 层业务逻辑 + Asynq 定时任务批量同步
- 缺乏统一封装：调用逻辑分散，加密签名重复实现
本变更旨在封装 Gateway API 为统一的能力模块，提供类型安全的接口、统一的错误处理和配置管理，供 Service 层和 Asynq 任务调用。
What Changes
1. Gateway 客户端封装
- 新增
internal/gateway/包，提供 Gateway API 的统一封装 - 实现 AES-128-ECB 加密 + MD5 签名机制
- 封装 14 个 API 接口（流量卡 7 个 + 设备 7 个）
- 提供类型安全的请求/响应结构体
2. 配置集成
- 在
pkg/config/config.go中添加GatewayConfig配置结构 - 支持环境变量配置：
JUNHONG_GATEWAY_BASE_URL、JUNHONG_GATEWAY_APP_ID、JUNHONG_GATEWAY_APP_SECRET - 配置项包括：BaseURL、AppID、AppSecret、Timeout
3. 错误处理
- 在
pkg/errors/codes.go中定义 Gateway 相关错误码（1110-1119） - 统一错误处理：加密失败、签名失败、请求超时、响应格式错误
4. 依赖注入
- 在
internal/bootstrap/中初始化 Gateway 客户端 - 注入到需要调用 Gateway API 的 Service
5. 测试覆盖
- 单元测试：加密/签名函数验证
- 集成测试：实际调用 Gateway API 验证
Capabilities
New Capabilities
gateway-client: Gateway API 统一客户端，提供 14 个接口的类型安全封装gateway-crypto: AES-128-ECB 加密 + MD5 签名工具函数
Modified Capabilities
config-management: 添加 Gateway 配置支持error-handling: 添加 Gateway 相关错误码dependency-injection: 在 bootstrap 中初始化 Gateway 客户端
Impact
代码变更
| 文件/目录 | 变更类型 | 说明 |
|---|---|---|
internal/gateway/client.go |
新增 | Gateway 客户端主体（Client 结构体 + doRequest） |
internal/gateway/crypto.go |
新增 | AES 加密 + MD5 签名函数 |
internal/gateway/flow_card.go |
新增 | 流量卡 7 个 API 方法封装 |
internal/gateway/device.go |
新增 | 设备 7 个 API 方法封装 |
internal/gateway/models.go |
新增 | 请求/响应 DTO 定义 |
internal/gateway/client_test.go |
新增 | 单元测试和集成测试 |
pkg/config/config.go |
修改 | 添加 GatewayConfig 结构体 |
pkg/errors/codes.go |
修改 | 添加 Gateway 错误码（1110-1119） |
internal/bootstrap/bootstrap.go |
修改 | 初始化 Gateway 客户端 |
Gateway API 接口列表
流量卡 API（7个）：
/flow-card/status- 流量卡状态查询/flow-card/flow- 流量使用查询/flow-card/realname-status- 实名认证状态查询/flow-card/cardStop- 流量卡停机/flow-card/cardStart- 流量卡复机/flow-card/realname-link- 获取实名认证跳转链接/flow-card/batch-query- 批量查询（未来扩展）
设备 API（7个）：
/device/info- 获取设备信息/device/slot-info- 获取设备卡槽信息/device/speed-limit- 设置设备限速/device/wifi- 设置设备 WiFi/device/switch-card- 设备切换卡/device/reset- 设备恢复出厂设置/device/reboot- 设备重启
配置变更
新增环境变量：
JUNHONG_GATEWAY_BASE_URL=https://lplan.whjhft.com/openapi
JUNHONG_GATEWAY_APP_ID=60bgt1X8i7AvXqkd
JUNHONG_GATEWAY_APP_SECRET=BZeQttaZQt0i73moF
JUNHONG_GATEWAY_TIMEOUT=30
依赖
- 无新增外部依赖
- 使用标准库：
crypto/aes、crypto/md5、encoding/base64、net/http
预期收益
| 指标 | 变更前 | 变更后 |
|---|---|---|
| Gateway 调用代码重复 | 每次调用重复加密签名 | 统一封装，零重复 |
| 错误处理一致性 | 不一致 | 统一错误码 |
| 类型安全 | 手动序列化，易出错 | 强类型 DTO，编译时检查 |
| 测试覆盖率 | 0% | 90%+ |
| 配置管理 | 硬编码 | 统一配置 |
风险与缓解
| 风险 | 影响 | 缓解措施 |
|---|---|---|
| AES-ECB 模式安全性 | 低（外部系统要求） | 文档注明，无法改变 |
| 签名算法兼容性 | 中（签名不匹配导致认证失败） | 先实现端到端测试验证签名 |
| Gateway 响应格式变更 | 中（解析失败） | 统一错误处理，兼容性版本 |
后续计划
-
阶段 1（本次变更）：
- 实现 Gateway 客户端基础封装
- 支持同步模式（14 个接口）
- 集成到 Service 层
-
阶段 2（未来优化）：
- 实现异步模式回调接口
- 添加批量查询接口
- 实现请求重试和超时控制
-
阶段 3（性能优化）：
- 添加响应缓存（Redis）
- 实现请求限流（防止 Gateway 过载）
- 监控和告警集成
验收标准
- Gateway 客户端成功调用所有 14 个 API 接口
- 加密/签名验证通过（与 Gateway 文档一致）
- 错误处理覆盖所有异常场景（网络错误、响应格式错误等）
- 单元测试覆盖率 ≥ 90%
- 集成测试验证真实 Gateway API 调用
- 配置通过环境变量成功加载
- 文档完整（API 文档、使用示例、错误码说明）