|
|
@ -1,137 +1,67 @@
|
|
|
|
### SDK 调用文档
|
|
|
|
## SDK 使用操作文档
|
|
|
|
|
|
|
|
|
|
|
|
本文档详细说明了如何使用两个SDK文件中的功能:一个是用于订单支付签名生成的SDK,另一个是用于订单退款签名生成的SDK。我们将分别介绍这两个SDK的使用方法。
|
|
|
|
### 概述
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
该 SDK 提供了订单支付和订单退款的签名生成功能。通过传入相应的订单信息和密钥,可以生成用于验证的签名。
|
|
|
|
|
|
|
|
|
|
|
|
#### 1. 订单支付SDK (`sdk_payment.go`)
|
|
|
|
### 目录
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1 结构体定义
|
|
|
|
1. [订单支付 SDK](#订单支付-sdk)
|
|
|
|
|
|
|
|
1. [初始化 SDK](#初始化-sdk)
|
|
|
|
|
|
|
|
2. [生成签名](#生成签名)
|
|
|
|
|
|
|
|
3. [示例代码](#示例代码)
|
|
|
|
|
|
|
|
2. [订单退款 SDK](#订单退款-sdk)
|
|
|
|
|
|
|
|
1. [初始化 SDK](#初始化-sdk-1)
|
|
|
|
|
|
|
|
2. [生成签名](#生成签名-1)
|
|
|
|
|
|
|
|
3. [示例代码](#示例代码-1)
|
|
|
|
|
|
|
|
3. [注意事项](#注意事项)
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
---
|
|
|
|
type Order struct {
|
|
|
|
|
|
|
|
Uid string // 用户ID
|
|
|
|
|
|
|
|
BsTradeNo string // 交易编号
|
|
|
|
|
|
|
|
Role string // 用户角色
|
|
|
|
|
|
|
|
RoleId string // 角色ID
|
|
|
|
|
|
|
|
ServerId string // 服务器ID
|
|
|
|
|
|
|
|
GoodsName string // 商品名称
|
|
|
|
|
|
|
|
OutTradeNo string // 外部交易编号
|
|
|
|
|
|
|
|
Body string // 商品描述
|
|
|
|
|
|
|
|
CpExtraInfo string // 扩展信息
|
|
|
|
|
|
|
|
TradeState string // 交易状态
|
|
|
|
|
|
|
|
TotalFee string // 总费用
|
|
|
|
|
|
|
|
PayFee string // 支付费用
|
|
|
|
|
|
|
|
PayTime string // 支付时间
|
|
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.2 SDK 结构体
|
|
|
|
### 订单支付 SDK
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
#### 初始化 SDK
|
|
|
|
type SDK struct {
|
|
|
|
|
|
|
|
SecretKey string // 秘钥
|
|
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.3 单例实例化
|
|
|
|
使用 `NewOrderPayment` 函数初始化订单支付 SDK 实例。该函数采用单例模式,确保同一密钥对应的 SDK 实例唯一。
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
```go
|
|
|
|
func NewOrderPayment(secretKey string) *SDK
|
|
|
|
// 导入 SDK 包
|
|
|
|
```
|
|
|
|
import "gitea.weitiangame.com/sdk/wt-game/sdk"
|
|
|
|
|
|
|
|
|
|
|
|
- **功能**: 初始化并返回一个SDK单例实例。
|
|
|
|
|
|
|
|
- **参数**:
|
|
|
|
|
|
|
|
- `secretKey` (string): 用于签名的密钥。
|
|
|
|
|
|
|
|
- **返回值**: `*SDK` 类型的单例实例。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.4 生成签名
|
|
|
|
// 初始化 SDK 实例
|
|
|
|
|
|
|
|
sdkInstance := sdk.NewOrderPayment("your_secret_key")
|
|
|
|
```go
|
|
|
|
|
|
|
|
func (s *SDK) SignParam(order *Order) (string, error)
|
|
|
|
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
- **功能**: 为提供的 `Order` 对象生成签名。
|
|
|
|
#### 生成签名
|
|
|
|
- **参数**:
|
|
|
|
|
|
|
|
- `order` (*Order): 包含订单信息的结构体指针。
|
|
|
|
|
|
|
|
- **返回值**:
|
|
|
|
|
|
|
|
- `string`: 生成的签名字符串。
|
|
|
|
|
|
|
|
- `error`: 可能返回的错误,当前实现中总是返回 `nil`。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.5 内部方法
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `createParamMap(order *Order) map[string]string`
|
|
|
|
|
|
|
|
- **功能**: 创建一个包含订单参数的映射,排除 `sign` 和 `-` 键。
|
|
|
|
|
|
|
|
- **返回值**: `map[string]string` 类型的参数映射。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `BuildSignString(params map[string]string) string`
|
|
|
|
|
|
|
|
- **功能**: 按字典顺序排序参数并生成签名字符串。
|
|
|
|
|
|
|
|
- **参数**: `params` (map[string]string): 参数映射。
|
|
|
|
|
|
|
|
- **返回值**: 拼接后的签名字符串。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `getSortedKeys(params map[string]string) []string`
|
|
|
|
创建 `Order` 结构体实例并设置相关字段,然后调用 `SignParam` 方法生成签名。
|
|
|
|
- **功能**: 获取排序后的参数键列表,排除 `sign` 和 `-` 键。
|
|
|
|
|
|
|
|
- **参数**: `params` (map[string]string): 参数映射。
|
|
|
|
|
|
|
|
- **返回值**: `[]string` 类型的排序键列表。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### 2. 订单退款SDK (`sdk_refund.go`)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 2.1 结构体定义
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
```go
|
|
|
|
type OrderRefund struct {
|
|
|
|
// 创建 Order 实例
|
|
|
|
OutTradeNo string // 订单号
|
|
|
|
order := &sdk.Order{
|
|
|
|
RoleId string // 角色ID
|
|
|
|
Uid: "12345",
|
|
|
|
Status string // 订单状态
|
|
|
|
BsTradeNo: "TRADE20231010001",
|
|
|
|
RefundFee string // 退款金额
|
|
|
|
Role: "Player",
|
|
|
|
Timestamp string // 时间戳
|
|
|
|
RoleId: "67890",
|
|
|
|
|
|
|
|
ServerId: "1",
|
|
|
|
|
|
|
|
GoodsName: "Diamond",
|
|
|
|
|
|
|
|
OutTradeNo: "OUT20231010001",
|
|
|
|
|
|
|
|
Body: "Purchase Diamond",
|
|
|
|
|
|
|
|
CpExtraInfo: "extra_info",
|
|
|
|
|
|
|
|
TradeState: "SUCCESS",
|
|
|
|
|
|
|
|
TotalFee: "100",
|
|
|
|
|
|
|
|
PayFee: "95",
|
|
|
|
|
|
|
|
PayTime: "20231010120000",
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 2.2 SDK 结构体
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
// 生成签名
|
|
|
|
type RefundSDK struct {
|
|
|
|
sign, err := sdkInstance.SignParam(order)
|
|
|
|
SecretKey string // 密钥
|
|
|
|
if err != nil {
|
|
|
|
|
|
|
|
// 处理错误
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
##### 2.3 单例实例化
|
|
|
|
#### 示例代码
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
|
|
|
func NewRefundSDK(secretKey string) *RefundSDK
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- **功能**: 初始化并返回一个 RefundSDK 单例实例。
|
|
|
|
|
|
|
|
- **参数**:
|
|
|
|
|
|
|
|
- `secretKey` (string): 用于签名的密钥。
|
|
|
|
|
|
|
|
- **返回值**: `*RefundSDK` 类型的单例实例。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 2.4 生成签名
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
|
|
|
func (sdk *RefundSDK) SignParam(order *OrderRefund) string
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- **功能**: 为提供的 `OrderRefund` 对象生成签名。
|
|
|
|
|
|
|
|
- **参数**:
|
|
|
|
|
|
|
|
- `order` (*OrderRefund): 包含退款信息的结构体指针。
|
|
|
|
|
|
|
|
- **返回值**: `string` 类型的签名字符串(大写形式)。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 2.5 内部方法
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `createFormUrl(order *OrderRefund) string`
|
|
|
|
|
|
|
|
- **功能**: 生成用于签名的参数字符串。
|
|
|
|
|
|
|
|
- **参数**: `order` (*OrderRefund): 包含退款信息的结构体指针。
|
|
|
|
|
|
|
|
- **返回值**: 拼接后的参数字符串。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 示例代码
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### 1. 订单支付SDK 使用示例
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
```go
|
|
|
|
package main
|
|
|
|
package main
|
|
|
@ -142,37 +72,72 @@ import (
|
|
|
|
)
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
|
|
func main() {
|
|
|
|
func main() {
|
|
|
|
// 初始化SDK实例
|
|
|
|
// 初始化 SDK 实例
|
|
|
|
sdkInstance := sdk.NewOrderPayment("your_secret_key")
|
|
|
|
sdkInstance := sdk.NewOrderPayment("your_secret_key")
|
|
|
|
|
|
|
|
|
|
|
|
// 创建订单对象
|
|
|
|
// 创建 Order 实例
|
|
|
|
order := &sdk.Order{
|
|
|
|
order := &sdk.Order{
|
|
|
|
Uid: "12345",
|
|
|
|
Uid: "12345",
|
|
|
|
BsTradeNo: "BT12345",
|
|
|
|
BsTradeNo: "TRADE20231010001",
|
|
|
|
Role: "Player",
|
|
|
|
Role: "Player",
|
|
|
|
RoleId: "R001",
|
|
|
|
RoleId: "67890",
|
|
|
|
ServerId: "S001",
|
|
|
|
ServerId: "1",
|
|
|
|
GoodsName: "Game Coin",
|
|
|
|
GoodsName: "Diamond",
|
|
|
|
OutTradeNo: "OT12345",
|
|
|
|
OutTradeNo: "OUT20231010001",
|
|
|
|
Body: "Purchase Game Coin",
|
|
|
|
Body: "Purchase Diamond",
|
|
|
|
CpExtraInfo: "extra_info",
|
|
|
|
CpExtraInfo: "extra_info",
|
|
|
|
TradeState: "SUCCESS",
|
|
|
|
TradeState: "SUCCESS",
|
|
|
|
TotalFee: "100",
|
|
|
|
TotalFee: "100",
|
|
|
|
PayFee: "95",
|
|
|
|
PayFee: "95",
|
|
|
|
PayTime: "20231030120000",
|
|
|
|
PayTime: "20231010120000",
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
// 生成签名
|
|
|
|
// 生成签名
|
|
|
|
sign, err := sdkInstance.SignParam(order)
|
|
|
|
sign, err := sdkInstance.SignParam(order)
|
|
|
|
if err != nil {
|
|
|
|
if err != nil {
|
|
|
|
fmt.Println("签名生成失败:", err)
|
|
|
|
fmt.Println("生成签名失败:", err)
|
|
|
|
return
|
|
|
|
return
|
|
|
|
}
|
|
|
|
}
|
|
|
|
fmt.Println("生成的签名:", sign)
|
|
|
|
|
|
|
|
|
|
|
|
fmt.Println("签名:", sign)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### 2. 订单退款SDK 使用示例
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 订单退款 SDK
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### 初始化 SDK
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
使用 `NewRefundSDK` 函数初始化订单退款 SDK 实例。该函数采用单例模式,确保同一密钥对应的 SDK 实例唯一。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
|
|
|
// 导入 SDK 包
|
|
|
|
|
|
|
|
import "gitea.weitiangame.com/sdk/wt-game/sdk"
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// 初始化 SDK 实例
|
|
|
|
|
|
|
|
refundSdkInstance := sdk.NewRefundSDK("your_secret_key")
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### 生成签名
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
创建 `OrderRefund` 结构体实例并设置相关字段,然后调用 `SignParam` 方法生成签名。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
|
|
|
// 创建 OrderRefund 实例
|
|
|
|
|
|
|
|
orderRefund := &sdk.OrderRefund{
|
|
|
|
|
|
|
|
OutTradeNo: "OUT20231010001",
|
|
|
|
|
|
|
|
RoleId: "67890",
|
|
|
|
|
|
|
|
Status: "SUCCESS",
|
|
|
|
|
|
|
|
RefundFee: "10",
|
|
|
|
|
|
|
|
Timestamp: "20231010120000",
|
|
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// 生成签名
|
|
|
|
|
|
|
|
sign := refundSdkInstance.SignParam(orderRefund)
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### 示例代码
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
```go
|
|
|
|
package main
|
|
|
|
package main
|
|
|
@ -183,21 +148,22 @@ import (
|
|
|
|
)
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
|
|
func main() {
|
|
|
|
func main() {
|
|
|
|
// 初始化SDK实例
|
|
|
|
// 初始化 SDK 实例
|
|
|
|
refundSdk := sdk.NewRefundSDK("your_secret_key")
|
|
|
|
refundSdkInstance := sdk.NewRefundSDK("your_secret_key")
|
|
|
|
|
|
|
|
|
|
|
|
// 创建退款订单对象
|
|
|
|
// 创建 OrderRefund 实例
|
|
|
|
refundOrder := &sdk.OrderRefund{
|
|
|
|
orderRefund := &sdk.OrderRefund{
|
|
|
|
OutTradeNo: "OT12345",
|
|
|
|
OutTradeNo: "OUT20231010001",
|
|
|
|
RoleId: "R001",
|
|
|
|
RoleId: "67890",
|
|
|
|
Status: "REFUNDED",
|
|
|
|
Status: "SUCCESS",
|
|
|
|
RefundFee: "95",
|
|
|
|
RefundFee: "10",
|
|
|
|
Timestamp: "20231030120000",
|
|
|
|
Timestamp: "20231010120000",
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
// 生成签名
|
|
|
|
// 生成签名
|
|
|
|
sign := refundSdk.SignParam(refundOrder)
|
|
|
|
sign := refundSdkInstance.SignParam(orderRefund)
|
|
|
|
fmt.Println("生成的签名:", sign)
|
|
|
|
|
|
|
|
|
|
|
|
fmt.Println("签名:", sign)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
@ -205,15 +171,46 @@ func main() {
|
|
|
|
|
|
|
|
|
|
|
|
### 注意事项
|
|
|
|
### 注意事项
|
|
|
|
|
|
|
|
|
|
|
|
1. **单例模式**: 两个SDK都使用了单例模式,确保在应用程序中只有一个实例。
|
|
|
|
1. **密钥保管**:请确保密钥的安全性,不要将密钥泄露给他人。
|
|
|
|
2. **线程安全**: 初始化SDK实例时使用了 `sync.Once`,确保线程安全。
|
|
|
|
2. **参数格式**:确保传入的参数格式正确,特别是时间戳和金额字段。
|
|
|
|
3. **签名生成**: 签名生成过程中要注意参数的顺序和拼接方式,确保与服务端一致。
|
|
|
|
3. **签名一致性**:在进行签名验证时,确保签名生成的参数和顺序与对方系统一致。
|
|
|
|
4. **密钥保管**: 保证密钥的安全,不要硬编码在代码中,建议从配置文件或环境变量中读取。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 附录
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Order 结构体字段说明
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 字段名 | 说明 |
|
|
|
|
|
|
|
|
|-----------------|--------------------------|
|
|
|
|
|
|
|
|
| Uid | 用户ID |
|
|
|
|
|
|
|
|
| BsTradeNo | 交易编号 |
|
|
|
|
|
|
|
|
| Role | 用户角色 |
|
|
|
|
|
|
|
|
| RoleId | 角色ID |
|
|
|
|
|
|
|
|
| ServerId | 服务器ID |
|
|
|
|
|
|
|
|
| GoodsName | 商品名称 |
|
|
|
|
|
|
|
|
| OutTradeNo | 外部交易编号 |
|
|
|
|
|
|
|
|
| Body | 商品描述 |
|
|
|
|
|
|
|
|
| CpExtraInfo | 扩展信息 |
|
|
|
|
|
|
|
|
| TradeState | 交易状态 |
|
|
|
|
|
|
|
|
| TotalFee | 总费用 |
|
|
|
|
|
|
|
|
| PayFee | 支付费用 |
|
|
|
|
|
|
|
|
| PayTime | 支付时间 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### OrderRefund 结构体字段说明
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 字段名 | 说明 |
|
|
|
|
|
|
|
|
|-------------|----------------|
|
|
|
|
|
|
|
|
| OutTradeNo | 订单号 |
|
|
|
|
|
|
|
|
| RoleId | 角色ID |
|
|
|
|
|
|
|
|
| Status | 订单状态 |
|
|
|
|
|
|
|
|
| RefundFee | 退款金额 |
|
|
|
|
|
|
|
|
| Timestamp | 时间戳 |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
### 参考资料
|
|
|
|
## 参考资料
|
|
|
|
|
|
|
|
|
|
|
|
- [Go 语言 sync.Once 包](https://golang.org/pkg/sync/#Once)
|
|
|
|
- [Go 语言单例模式](https://www.runoob.com/w3cnote/go-singleton-pattern.html)
|
|
|
|
- [Go 语言字符串拼接](https://golang.org/pkg/strings/)
|
|
|
|
- [Go 语言字符串拼接](https://www.runoob.com/go/go-strings-concat.html)
|
|
|
|
- [Go 语言排序](https://golang.org/pkg/sort/)
|
|
|
|
- [Go 语言排序](https://www.runoob.com/go/go-slices-sort.html)
|