From 53c554a55a3b9ca481a1186538472d45ac4c7922 Mon Sep 17 00:00:00 2001 From: zhuxianglong <56494565@qq.com> Date: Thu, 16 Jan 2025 16:41:53 +0800 Subject: [PATCH] no message --- sdk/README.md | 287 +++++++++++++++++++++++++++++----------------------------- 1 file changed, 142 insertions(+), 145 deletions(-) diff --git a/sdk/README.md b/sdk/README.md index eb6d477..72865df 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -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/) \ No newline at end of file +- [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) \ No newline at end of file