chore: apply task changes
This commit is contained in:
749
docs/gateway-api-reference.md
Normal file
749
docs/gateway-api-reference.md
Normal file
@@ -0,0 +1,749 @@
|
||||
# Gateway API 参考文档
|
||||
|
||||
## 概述
|
||||
|
||||
本文档提供 Gateway 客户端所有 API 接口的完整参考，包括请求参数、响应格式和使用示例。
|
||||
|
||||
**API 分类**：
|
||||
- 流量卡管理（7 个接口）
|
||||
- 设备管理（7 个接口）
|
||||
|
||||
**基础信息**：
|
||||
- 协议：HTTPS
|
||||
- 请求方法：POST
|
||||
- 内容类型：application/json
|
||||
- 编码方式：UTF-8
|
||||
- 加密方式：AES-128-ECB + Base64
|
||||
- 签名方式：MD5
|
||||
|
||||
---
|
||||
|
||||
## 流量卡管理 API
|
||||
|
||||
### 1. 查询流量卡状态
|
||||
|
||||
查询流量卡的当前状态信息。
|
||||
|
||||
**方法**: `QueryCardStatus`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type CardStatusReq struct {
|
||||
CardNo string `json:"cardNo" validate:"required"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| CardNo | string | ✅ | 流量卡号（ICCID） |
|
||||
|
||||
**响应参数**:
|
||||
```go
|
||||
type CardStatusResp struct {
|
||||
ICCID string `json:"iccid"`
|
||||
CardStatus string `json:"cardStatus"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| ICCID | string | 流量卡 ICCID |
|
||||
| CardStatus | string | 卡状态（准备、正常、停机） |
|
||||
| Extend | string | 扩展字段（广电国网特殊参数） |
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
resp, err := client.QueryCardStatus(ctx, &gateway.CardStatusReq{
|
||||
CardNo: "898608070422D0010269",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Printf("卡状态: %s\n", resp.CardStatus)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 查询流量使用情况
|
||||
|
||||
查询流量卡的流量使用详情。
|
||||
|
||||
**方法**: `QueryFlow`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type FlowQueryReq struct {
|
||||
CardNo string `json:"cardNo" validate:"required"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| CardNo | string | ✅ | 流量卡号（ICCID） |
|
||||
|
||||
**响应参数**:
|
||||
```go
|
||||
type FlowUsageResp struct {
|
||||
UsedFlow int64 `json:"usedFlow"`
|
||||
Unit string `json:"unit"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| UsedFlow | int64 | 已用流量 |
|
||||
| Unit | string | 流量单位（MB） |
|
||||
| Extend | string | 扩展字段 |
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
resp, err := client.QueryFlow(ctx, &gateway.FlowQueryReq{
|
||||
CardNo: "898608070422D0010269",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Printf("已用流量: %d %s\n", resp.UsedFlow, resp.Unit)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 查询实名认证状态
|
||||
|
||||
查询流量卡的实名认证状态。
|
||||
|
||||
**方法**: `QueryRealnameStatus`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type CardStatusReq struct {
|
||||
CardNo string `json:"cardNo" validate:"required"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| CardNo | string | ✅ | 流量卡号（ICCID） |
|
||||
|
||||
**响应参数**:
|
||||
```go
|
||||
type RealnameStatusResp struct {
|
||||
Status string `json:"status"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| Status | string | 实名认证状态 |
|
||||
| Extend | string | 扩展字段 |
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
resp, err := client.QueryRealnameStatus(ctx, &gateway.CardStatusReq{
|
||||
CardNo: "898608070422D0010269",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Printf("实名状态: %s\n", resp.Status)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 流量卡停机
|
||||
|
||||
对流量卡执行停机操作。
|
||||
|
||||
**方法**: `StopCard`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type CardOperationReq struct {
|
||||
CardNo string `json:"cardNo" validate:"required"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| CardNo | string | ✅ | 流量卡号（ICCID） |
|
||||
| Extend | string | ❌ | 扩展字段（广电国网特殊参数） |
|
||||
|
||||
**响应参数**: 无（成功返回 nil，失败返回 error）
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
err := client.StopCard(ctx, &gateway.CardOperationReq{
|
||||
CardNo: "898608070422D0010269",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Println("停机成功")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 流量卡复机
|
||||
|
||||
对流量卡执行复机操作。
|
||||
|
||||
**方法**: `StartCard`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type CardOperationReq struct {
|
||||
CardNo string `json:"cardNo" validate:"required"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| CardNo | string | ✅ | 流量卡号（ICCID） |
|
||||
| Extend | string | ❌ | 扩展字段 |
|
||||
|
||||
**响应参数**: 无（成功返回 nil，失败返回 error）
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
err := client.StartCard(ctx, &gateway.CardOperationReq{
|
||||
CardNo: "898608070422D0010269",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Println("复机成功")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 获取实名认证跳转链接
|
||||
|
||||
获取流量卡实名认证的跳转链接。
|
||||
|
||||
**方法**: `GetRealnameLink`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type CardStatusReq struct {
|
||||
CardNo string `json:"cardNo" validate:"required"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| CardNo | string | ✅ | 流量卡号（ICCID） |
|
||||
|
||||
**响应参数**:
|
||||
```go
|
||||
type RealnameLinkResp struct {
|
||||
Link string `json:"link"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| Link | string | 实名认证跳转链接（HTTPS URL） |
|
||||
| Extend | string | 扩展字段 |
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
resp, err := client.GetRealnameLink(ctx, &gateway.CardStatusReq{
|
||||
CardNo: "898608070422D0010269",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Printf("实名链接: %s\n", resp.Link)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 批量查询（预留）
|
||||
|
||||
批量查询流量卡信息（暂未实现）。
|
||||
|
||||
**方法**: `BatchQuery`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type BatchQueryReq struct {
|
||||
CardNos []string `json:"cardNos" validate:"required,min=1,max=100"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| CardNos | []string | ✅ | 流量卡号列表（最多100个） |
|
||||
|
||||
**响应参数**:
|
||||
```go
|
||||
type BatchQueryResp struct {
|
||||
Results []CardStatusResp `json:"results"`
|
||||
}
|
||||
```
|
||||
|
||||
**状态**: ⚠️ 暂未实现，调用将返回错误
|
||||
|
||||
---
|
||||
|
||||
## 设备管理 API
|
||||
|
||||
### 1. 获取设备信息
|
||||
|
||||
通过卡号或设备 ID 查询设备的在线状态、信号强度、WiFi 信息等。
|
||||
|
||||
**方法**: `GetDeviceInfo`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type DeviceInfoReq struct {
|
||||
CardNo string `json:"cardNo,omitempty"`
|
||||
DeviceID string `json:"deviceId,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| CardNo | string | 二选一 | 流量卡号（ICCID） |
|
||||
| DeviceID | string | 二选一 | 设备 ID/IMEI |
|
||||
|
||||
**响应参数**:
|
||||
```go
|
||||
type DeviceInfoResp struct {
|
||||
IMEI string `json:"imei"`
|
||||
OnlineStatus int `json:"onlineStatus"`
|
||||
SignalLevel int `json:"signalLevel"`
|
||||
WiFiSSID string `json:"wifiSsid,omitempty"`
|
||||
WiFiEnabled int `json:"wifiEnabled"`
|
||||
UploadSpeed int `json:"uploadSpeed"`
|
||||
DownloadSpeed int `json:"downloadSpeed"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| IMEI | string | 设备 IMEI |
|
||||
| OnlineStatus | int | 在线状态（0:离线, 1:在线） |
|
||||
| SignalLevel | int | 信号强度（0-31） |
|
||||
| WiFiSSID | string | WiFi 名称 |
|
||||
| WiFiEnabled | int | WiFi 启用状态（0:禁用, 1:启用） |
|
||||
| UploadSpeed | int | 上行速率（KB/s） |
|
||||
| DownloadSpeed | int | 下行速率（KB/s） |
|
||||
| Extend | string | 扩展字段 |
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
resp, err := client.GetDeviceInfo(ctx, &gateway.DeviceInfoReq{
|
||||
DeviceID: "123456789012345",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Printf("设备状态: %s, 信号: %d\n",
|
||||
map[int]string{0:"离线", 1:"在线"}[resp.OnlineStatus],
|
||||
resp.SignalLevel,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 获取设备卡槽信息
|
||||
|
||||
查询设备的所有卡槽及其中的卡信息。
|
||||
|
||||
**方法**: `GetSlotInfo`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type DeviceInfoReq struct {
|
||||
CardNo string `json:"cardNo,omitempty"`
|
||||
DeviceID string `json:"deviceId,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| CardNo | string | 二选一 | 流量卡号（ICCID） |
|
||||
| DeviceID | string | 二选一 | 设备 ID/IMEI |
|
||||
|
||||
**响应参数**:
|
||||
```go
|
||||
type SlotInfoResp struct {
|
||||
IMEI string `json:"imei"`
|
||||
Slots []SlotInfo `json:"slots"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
|
||||
type SlotInfo struct {
|
||||
SlotNo int `json:"slotNo"`
|
||||
ICCID string `json:"iccid"`
|
||||
CardStatus string `json:"cardStatus"`
|
||||
IsActive int `json:"isActive"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| IMEI | string | 设备 IMEI |
|
||||
| Slots | []SlotInfo | 卡槽信息列表 |
|
||||
| SlotNo | int | 卡槽编号 |
|
||||
| ICCID | string | 卡槽中的 ICCID |
|
||||
| CardStatus | string | 卡状态（准备、正常、停机） |
|
||||
| IsActive | int | 是否为当前使用的卡槽（0:否, 1:是） |
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
resp, err := client.GetSlotInfo(ctx, &gateway.DeviceInfoReq{
|
||||
DeviceID: "123456789012345",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
for _, slot := range resp.Slots {
|
||||
fmt.Printf("卡槽%d: %s (%s)%s\n",
|
||||
slot.SlotNo,
|
||||
slot.ICCID,
|
||||
slot.CardStatus,
|
||||
map[int]string{0:"", 1:" [当前使用]"}[slot.IsActive],
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 设置设备限速
|
||||
|
||||
设置设备的上行和下行速率限制。
|
||||
|
||||
**方法**: `SetSpeedLimit`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type SpeedLimitReq struct {
|
||||
DeviceID string `json:"deviceId" validate:"required"`
|
||||
UploadSpeed int `json:"uploadSpeed" validate:"required,min=1"`
|
||||
DownloadSpeed int `json:"downloadSpeed" validate:"required,min=1"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| DeviceID | string | ✅ | 设备 ID/IMEI |
|
||||
| UploadSpeed | int | ✅ | 上行速率（KB/s），最小1 |
|
||||
| DownloadSpeed | int | ✅ | 下行速率（KB/s），最小1 |
|
||||
| Extend | string | ❌ | 扩展字段 |
|
||||
|
||||
**响应参数**: 无（成功返回 nil，失败返回 error）
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
err := client.SetSpeedLimit(ctx, &gateway.SpeedLimitReq{
|
||||
DeviceID: "123456789012345",
|
||||
UploadSpeed: 100,
|
||||
DownloadSpeed: 500,
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Println("限速设置成功")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 设置设备 WiFi
|
||||
|
||||
设置设备的 WiFi 名称、密码和启用状态。
|
||||
|
||||
**方法**: `SetWiFi`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type WiFiReq struct {
|
||||
DeviceID string `json:"deviceId" validate:"required"`
|
||||
SSID string `json:"ssid" validate:"required,min=1,max=32"`
|
||||
Password string `json:"password" validate:"required,min=8,max=63"`
|
||||
Enabled int `json:"enabled" validate:"required,oneof=0 1"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| DeviceID | string | ✅ | 设备 ID/IMEI |
|
||||
| SSID | string | ✅ | WiFi 名称（1-32字符） |
|
||||
| Password | string | ✅ | WiFi 密码（8-63字符） |
|
||||
| Enabled | int | ✅ | 启用状态（0:禁用, 1:启用） |
|
||||
| Extend | string | ❌ | 扩展字段 |
|
||||
|
||||
**响应参数**: 无（成功返回 nil，失败返回 error）
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
err := client.SetWiFi(ctx, &gateway.WiFiReq{
|
||||
DeviceID: "123456789012345",
|
||||
SSID: "MyWiFi",
|
||||
Password: "password123",
|
||||
Enabled: 1,
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Println("WiFi设置成功")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 设备切换卡
|
||||
|
||||
切换设备当前使用的卡到指定的目标卡。
|
||||
|
||||
**方法**: `SwitchCard`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type SwitchCardReq struct {
|
||||
DeviceID string `json:"deviceId" validate:"required"`
|
||||
TargetICCID string `json:"targetIccid" validate:"required"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| DeviceID | string | ✅ | 设备 ID/IMEI |
|
||||
| TargetICCID | string | ✅ | 目标卡 ICCID |
|
||||
| Extend | string | ❌ | 扩展字段 |
|
||||
|
||||
**响应参数**: 无（成功返回 nil，失败返回 error）
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
err := client.SwitchCard(ctx, &gateway.SwitchCardReq{
|
||||
DeviceID: "123456789012345",
|
||||
TargetICCID: "898608070422D0010270",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Println("切换卡成功")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 设备恢复出厂设置
|
||||
|
||||
将设备恢复到出厂设置状态。
|
||||
|
||||
**方法**: `ResetDevice`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type DeviceOperationReq struct {
|
||||
DeviceID string `json:"deviceId" validate:"required"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| DeviceID | string | ✅ | 设备 ID/IMEI |
|
||||
| Extend | string | ❌ | 扩展字段 |
|
||||
|
||||
**响应参数**: 无（成功返回 nil，失败返回 error）
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
err := client.ResetDevice(ctx, &gateway.DeviceOperationReq{
|
||||
DeviceID: "123456789012345",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Println("恢复出厂设置成功")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 设备重启
|
||||
|
||||
远程重启设备。
|
||||
|
||||
**方法**: `RebootDevice`
|
||||
|
||||
**请求参数**:
|
||||
```go
|
||||
type DeviceOperationReq struct {
|
||||
DeviceID string `json:"deviceId" validate:"required"`
|
||||
Extend string `json:"extend,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| DeviceID | string | ✅ | 设备 ID/IMEI |
|
||||
| Extend | string | ❌ | 扩展字段 |
|
||||
|
||||
**响应参数**: 无（成功返回 nil，失败返回 error）
|
||||
|
||||
**使用示例**:
|
||||
```go
|
||||
err := client.RebootDevice(ctx, &gateway.DeviceOperationReq{
|
||||
DeviceID: "123456789012345",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
fmt.Println("重启设备成功")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 通用响应结构
|
||||
|
||||
所有 API 的底层响应都遵循统一的 Gateway 响应格式：
|
||||
|
||||
```go
|
||||
type GatewayResponse struct {
|
||||
Code int `json:"code"`
|
||||
Msg string `json:"msg"`
|
||||
Data json.RawMessage `json:"data"`
|
||||
TraceID string `json:"trace_id"`
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| Code | int | 业务状态码（200 = 成功） |
|
||||
| Msg | string | 业务提示信息 |
|
||||
| Data | json.RawMessage | 业务数据（原始 JSON） |
|
||||
| TraceID | string | 链路追踪 ID |
|
||||
|
||||
**成功响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "成功",
|
||||
"data": {
|
||||
"iccid": "898608070422D0010269",
|
||||
"cardStatus": "正常"
|
||||
},
|
||||
"trace_id": "abc123xyz"
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 404,
|
||||
"msg": "卡号不存在",
|
||||
"data": null,
|
||||
"trace_id": "abc123xyz"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误码说明
|
||||
|
||||
### Gateway 业务错误码
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|-------|------|---------|
|
||||
| 200 | 成功 | - |
|
||||
| 400 | 请求参数错误 | 检查请求参数格式和内容 |
|
||||
| 401 | 认证失败 | 检查 AppID 和 AppSecret |
|
||||
| 404 | 资源不存在 | 检查卡号或设备 ID 是否正确 |
|
||||
| 500 | 服务器内部错误 | 联系 Gateway 服务提供方 |
|
||||
|
||||
### 客户端错误码
|
||||
|
||||
客户端封装的统一错误码（`pkg/errors/codes.go`）：
|
||||
|
||||
| 错误码 | 常量 | 说明 |
|
||||
|-------|------|------|
|
||||
| 1110 | CodeGatewayError | Gateway 连接失败 |
|
||||
| 1111 | CodeGatewayTimeout | Gateway 请求超时 |
|
||||
| 1112 | CodeGatewayBusinessError | Gateway 业务错误 |
|
||||
| 1113 | CodeGatewayInvalidResp | Gateway 响应解析失败 |
|
||||
| 1114 | CodeGatewaySignError | Gateway 签名验证失败 |
|
||||
|
||||
---
|
||||
|
||||
## 请求流程
|
||||
|
||||
### 完整请求流程
|
||||
|
||||
```
|
||||
1. 构造业务请求参数
|
||||
↓
|
||||
2. 序列化为 JSON
|
||||
↓
|
||||
3. AES-128-ECB 加密（Base64 编码）
|
||||
↓
|
||||
4. 生成 MD5 签名（参数排序 + appSecret）
|
||||
↓
|
||||
5. 构造最终请求体
|
||||
{
|
||||
"appId": "xxx",
|
||||
"data": "encrypted_base64_string",
|
||||
"sign": "md5_signature",
|
||||
"timestamp": 1706620800000
|
||||
}
|
||||
↓
|
||||
6. POST 请求到 Gateway
|
||||
↓
|
||||
7. 解析响应 JSON
|
||||
↓
|
||||
8. 检查业务状态码
|
||||
↓
|
||||
9. 解密并解析业务数据
|
||||
↓
|
||||
10. 返回结果或错误
|
||||
```
|
||||
|
||||
### 签名算法
|
||||
|
||||
```
|
||||
1. 将请求参数按 key 字母序排序
|
||||
2. 拼接为 key1=value1&key2=value2 格式
|
||||
3. 末尾追加 &appSecret=xxx
|
||||
4. 计算 MD5 哈希
|
||||
5. 转为大写字符串
|
||||
```
|
||||
|
||||
**示例**:
|
||||
```
|
||||
参数: {cardNo: "123", appId: "abc"}
|
||||
排序: appId=abc&cardNo=123
|
||||
追加: appId=abc&cardNo=123&appSecret=secret
|
||||
MD5: D41D8CD98F00B204E9800998ECF8427E
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Gateway 客户端使用指南](./gateway-client-usage.md) - 详细的使用指南和最佳实践
|
||||
- [错误处理指南](./003-error-handling/使用指南.md) - 统一错误处理规范
|
||||
Reference in New Issue
Block a user