sdk
/
wt-game
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

no message

Browse Source
tags/v0.0.2
zhuxianglong 2 months ago
parent afc205d9ac
commit 53c554a55a
1 changed files with 142 additions and 145 deletions
Show Stats Download Patch File Download Diff File

287
sdk/README.md
Unescape Escape View File

@ -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
type SDK struct {
SecretKey string // 秘钥
}
```
#### 初始化 SDK
##### 1.3 单例实例化
使用 `NewOrderPayment` 函数初始化订单支付 SDK 实例。该函数采用单例模式，确保同一密钥对应的 SDK 实例唯一。
```go
func NewOrderPayment(secretKey string) *SDK
```
- **功能**: 初始化并返回一个SDK单例实例。
- **参数**:
- `secretKey` (string): 用于签名的密钥。
- **返回值**: `*SDK` 类型的单例实例。
// 导入 SDK 包
import "gitea.weitiangame.com/sdk/wt-game/sdk"
##### 1.4 生成签名
```go
func (s *SDK) SignParam(order *Order) (string, error)
// 初始化 SDK 实例
sdkInstance := sdk.NewOrderPayment("your_secret_key")
```
- **功能**: 为提供的 `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`
- **功能**: 获取排序后的参数键列表，排除 `sign` 和 `-` 键。
- **参数**: `params` (map[string]string): 参数映射。
- **返回值**: `[]string` 类型的排序键列表。
---
#### 2. 订单退款SDK (`sdk_refund.go`)
##### 2.1 结构体定义
创建 `Order` 结构体实例并设置相关字段，然后调用 `SignParam` 方法生成签名。
```go
type OrderRefund struct {
OutTradeNo string // 订单号
RoleId string // 角色ID
Status string // 订单状态
RefundFee string // 退款金额
Timestamp string // 时间戳
// 创建 Order 实例
order := &sdk.Order{
Uid: "12345",
BsTradeNo: "TRADE20231010001",
Role: "Player",
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 {
SecretKey string // 密钥
// 生成签名
sign, err := sdkInstance.SignParam(order)
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
package main
@ -142,37 +72,72 @@ import (
)
func main() {
// 初始化SDK实例
// 初始化 SDK 实例
sdkInstance := sdk.NewOrderPayment("your_secret_key")
// 创建订单对象
// 创建 Order 实例
order := &sdk.Order{
Uid: "12345",
BsTradeNo: "BT12345",
BsTradeNo: "TRADE20231010001",
Role: "Player",
RoleId: "R001",
ServerId: "S001",
GoodsName: "Game Coin",
OutTradeNo: "OT12345",
Body: "Purchase Game Coin",
RoleId: "67890",
ServerId: "1",
GoodsName: "Diamond",
OutTradeNo: "OUT20231010001",
Body: "Purchase Diamond",
CpExtraInfo: "extra_info",
TradeState: "SUCCESS",
TotalFee: "100",
PayFee: "95",
PayTime: "20231030120000",
PayTime: "20231010120000",
}
// 生成签名
sign, err := sdkInstance.SignParam(order)
if err != nil {
fmt.Println("签名生成失败:", err)
fmt.Println("生成签名失败:", err)
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
package main
@ -183,21 +148,22 @@ import (
)
func main() {
// 初始化SDK实例
refundSdk := sdk.NewRefundSDK("your_secret_key")
// 创建退款订单对象
refundOrder := &sdk.OrderRefund{
OutTradeNo: "OT12345",
RoleId: "R001",
Status: "REFUNDED",
RefundFee: "95",
Timestamp: "20231030120000",
// 初始化 SDK 实例
refundSdkInstance := sdk.NewRefundSDK("your_secret_key")
// 创建 OrderRefund 实例
orderRefund := &sdk.OrderRefund{
OutTradeNo: "OUT20231010001",
RoleId: "67890",
Status: "SUCCESS",
RefundFee: "10",
Timestamp: "20231010120000",
}
// 生成签名
sign := refundSdk.SignParam(refundOrder)
fmt.Println("生成的签名:", sign)
sign := refundSdkInstance.SignParam(orderRefund)
fmt.Println("签名:", sign)
}
```
@ -205,15 +171,46 @@ func main() {
### 注意事项
1. **单例模式**: 两个SDK都使用了单例模式，确保在应用程序中只有一个实例。
2. **线程安全**: 初始化SDK实例时使用了 `sync.Once`，确保线程安全。
3. **签名生成**: 签名生成过程中要注意参数的顺序和拼接方式，确保与服务端一致。
4. **密钥保管**: 保证密钥的安全，不要硬编码在代码中，建议从配置文件或环境变量中读取。
1. **密钥保管**：请确保密钥的安全性，不要将密钥泄露给他人。
2. **参数格式**：确保传入的参数格式正确，特别是时间戳和金额字段。
3. **签名一致性**：在进行签名验证时，确保签名生成的参数和顺序与对方系统一致。
---
## 附录
### 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://golang.org/pkg/strings/)
- [Go 语言排序](https://golang.org/pkg/sort/)
- [Go 语言单例模式](https://www.runoob.com/w3cnote/go-singleton-pattern.html)
- [Go 语言字符串拼接](https://www.runoob.com/go/go-strings-concat.html)
- [Go 语言排序](https://www.runoob.com/go/go-slices-sort.html)
Write Preview
Loading…
Cancel
Save