2.2 KiB
Gateway 接入契约
元数据
- Owner：IoT Gateway 适配维护人
- 实现：
internal/gateway/ - 核验日期：2026-08-07
- 证据：
internal/gateway/client.go、crypto.go、card_status.go、flow_card.go、device.go
当前实际使用范围
Gateway 是运营商流量卡、实名、停复机、限速和设备信息的统一封装入口。具体路径、请求字段和响应字段以同目录详细协议与 internal/gateway/*.go 的实际调用交集为准；文档中出现但代码未调用的接口不视为系统能力。
配置、认证与报文
配置键为 gateway.base_url、gateway.app_id、gateway.app_secret、gateway.timeout。业务参数先包装为 {"params": ...}，使用 AppSecret 做 AES-128-ECB 加密；外层请求含 appId、data、sign、timestamp，签名使用 MD5。HTTP 方法统一为 POST，内容类型为 application/json;charset=utf-8。HTTP 200 且 Gateway code=200 才算成功，data 再按具体能力解码。
超时、重试与幂等
客户端默认超时 60 秒；生效配置可覆盖。默认最多重试 2 次，即最多 3 次尝试，退避为 100ms、200ms，更多重试时封顶 300ms。仅客户端超时、连接和 DNS 等网络级错误重试；用户 Context 取消、HTTP 非 200、响应解析失败和 Gateway 业务码失败不重试。每次尝试重新生成时间戳与签名。
查询天然只读；停复机、限速等写操作的幂等和状态条件由调用它的业务 Service 承担，Gateway 客户端本身不提供幂等键。
安全、错误与验证
AppSecret、加密前业务数据、完整身份标识不得写入本文或普通日志；当前客户端存在请求结构日志，运行环境必须依赖日志脱敏策略。Gateway 错误映射为项目 CodeGatewayError、CodeGatewayTimeout 或 CodeGatewayInvalidResp。
可复现静态证据：internal/gateway/client.go、internal/gateway/crypto.go 及同目录能力文件。真实写操作可能改变卡或设备状态，本次只允许静态核对和隔离账号只读验证，不调用生产写接口。
协议、路径、认证、成功码、超时或重试分类变化时更新本文。