Merge pull request #33 from wechatpay-apiv3/gen_payments_and_refund

生成国内退款服务接口 `refunddomestic`

.gitignore

@@ -9,4 +9,5 @@
 
 # Other
 .openapi-generator
+.openapi-generator-ignore
 .DS_Store

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.2.2] - 2021-07-09
+
+### Added
+
++ 微信支付境内退款（refunddomestic）接口SDK
+
+### Changed
+
++ `BREAKING CHANGE` 将现有接口SDK中的整型参数统一为`int64`。受影响接口包括:
+  <details>
+  <summary>Click to expand!</summary>
+
+    + payments/app
+    + payments/h5
+    + payments/jsapi
+    + payments/native
+  </details>
+
 ## [0.2.1] - 2021-06-25
 
 ### Added

README.md

@@ -3,7 +3,7 @@
 
 ## 版本信息
 
-版本号：`v0.2.1`
+版本号：`v0.2.2`
 
 版本功能：
 1. 支持微信支付 API v3 请求签名与应答验签能力的 HTTP Client: `core.Client`，该 HTTP Client 在执行请求时将自动携带身份认证信息，并检查应答的微信支付签名。
@@ -13,11 +13,55 @@
     - 微信核心支付4种常用支付接口（JSAPI支付, APP支付，H5支付，Native支付）的SDK。特别的，为【JSAPI支付】与【APP支付】提供了自动构建拉起支付所需签名的接口。
 	- 微信支付4种文件上传接口的SDK
 	- 微信支付证书下载接口的SDK
+    - 微信支付境内退款接口的SDK
 	- 更多API跟进中
 
 兼容性：
 本版本为测试版本，因为接口重命名/代码结构调整等原因，与之前版本存在不兼容的情况。
 
+### 重大更新（Breaking Change）
+版本 `v0.2.2` 中我们包含了一个重大更新内容：将现有接口SDK中的整型参数统一为`int64`。
+这一行为的目的是规范SDK中对整型参数的实现，避免因为未来可能的`int32 -> int64`的字段升级导致大规模兼容性问题。
+
+此次升级会导致 `payments` 下4个API接口的SDK的兼容性问题，建议开发者以如下方式对自己的代码进行更新。
+#### SDK整型参数统一为`int64`代码修复步骤
+##### 1. 升级依赖
+1. 在你的模块目录下执行 `go get -u github.com/wechatpay-apiv3/wechatpay-go@v0.2.2` 升级依赖。
+2. （正常情况下该步骤会自动完成）修改模块 `go.mod` 文件中依赖的 `github.com/wechatpay-apiv3/wechatpay-go` 至 `v0.2.2`版本。
+##### 2. 定位需要修改的代码
+在项目根目录下执行`go build ./...`可以递归检查代码中的编译错误，即可快速定位到需要修改的代码。
+##### 3. 对请求构建代码进行更新
+对于请求 `payments` 接口的数据，可以在设置参数时使用`int64(xxx)`进行类型转换。当然也可以将请求链路上的类型从`int32`更新为`int64`。
+```go
+req := jsapi.PrepayRequest{}
+// 升级前
+req.Amount = &jsapi.Amount{
+	Currency: core.String("CNY"),
+	Total:    &totalInt32,
+}
+// 升级后
+totalInt64 := int64(totalInt32)
+req.Amount = &jsapi.Amount{
+	Currency: core.String("CNY"),
+	Total:    &totalInt64,
+}
+```
+##### 4. 对应答处理代码进行更新
+对于应答结果的处理，我们不建议将返回结果中的`int64`强制类型转换为`int32`，而是建议将后续处理链路中的类型从`int32`更新为`int64`。
+这样变更可能会更复杂，但是安全性更好，避免因为数据溢出导致错误。
+```go
+// 升级前
+func GetTransactionTotal(resp *payments.Transaction) int32 {
+	return *resp.Amount.Total
+}
+// 升级后
+func GetTransactionTotal(resp *payments.Transaction) int64 {
+	return *resp.Amount.Total
+}
+```
+##### 5. 更新你的测试用例代码并测试
+如果你有针对 `payments` 编写测试用例，你可能需要对测试用例代码进行更新，并重新测试确保一切正常。
+
 ## 快速开始
 ### 安装
 #### 1、使用 Go Modules 管理你的项目（如果项目目录下存在`go.mod`文件的话说明你的项目已经使用 Go Modules 进行管理）
@@ -30,14 +74,14 @@ go mod init
 在 `go.mod` 文件中加入对本SDK的依赖：
 ```
 require (
-    github.com/wechatpay-apiv3/wechatpay-go v0.2.1
+    github.com/wechatpay-apiv3/wechatpay-go v0.2.2
 )
 ```
 并使用`go mod tidy`进行下载。
 
 也可以直接在项目目录中执行： 
 ```shell
-go get -u github.com/wechatpay-apiv3/wechatpay-go@v0.2.1
+go get -u github.com/wechatpay-apiv3/wechatpay-go@v0.2.2
 ```
 来自动完成`go.mod`的修改与SDK的下载。
 
@@ -420,7 +464,7 @@ func NewCustomClient(ctx context.Context, mchID string) (*core.Client, error) {
 
 首先使用 `go` 指令下载命令行工具
 ```shell
-go get -u github.com/wechatpay-apiv3/wechatpay-go/cmd/wechatpay_download_certs@v0.2.1
+go get -u github.com/wechatpay-apiv3/wechatpay-go/cmd/wechatpay_download_certs@v0.2.2
 ```
 然后执行 `wechatpay_download_certs` 即可下载平台证书到当前目录
 ```shell

core/consts/const.go

@@ -11,7 +11,7 @@ const (
 
 // SDK 相关信息
 const (
-	Version         = "0.2.1"                      // SDK 版本
+	Version         = "0.2.2"                      // SDK 版本
 	UserAgentFormat = "WechatPay-Go/%s (%s) GO/%s" // UserAgent中的信息
 )
 

core/error.go

@@ -43,6 +43,9 @@ func (e *APIError) Error() string {
 	return buf.String()
 }
 
+// IsAPIError 判断当前 error 是否为特定 Code 的 *APIError
+//
+// 类型为其他 error 或 Code 不匹配时均返回 false
 func IsAPIError(err error, code string) bool {
 	if ne, ok := err.(*APIError); ok {
 		return ne.Code == code

docs/payments/PromotionDetail.md

@@ -8,11 +8,11 @@
 **Name** | **string** | 优惠名称  | [可选] 
 **Scope** | **string** | GLOBAL：全场代金券；SINGLE：单品优惠  | [可选] 
 **Type** | **string** | CASH：充值；NOCASH：预充值。  | [可选] 
-**Amount** | **int32** | 优惠券面额  | [可选] 
+**Amount** | **int64** | 优惠券面额  | [可选] 
 **StockId** | **string** | 活动ID，批次ID  | [可选] 
-**WechatpayContribute** | **int32** | 单位为分  | [可选] 
-**MerchantContribute** | **int32** | 单位为分  | [可选] 
-**OtherContribute** | **int32** | 单位为分  | [可选] 
+**WechatpayContribute** | **int64** | 单位为分  | [可选] 
+**MerchantContribute** | **int64** | 单位为分  | [可选] 
+**OtherContribute** | **int64** | 单位为分  | [可选] 
 **Currency** | **string** | CNY：人民币，境内商户号仅支持人民币。  | [可选] 
 **GoodsDetail** | [**[]PromotionGoodsDetail**](PromotionGoodsDetail.md) |  | [可选] 
 

docs/payments/PromotionGoodsDetail.md

@@ -5,9 +5,9 @@
 名称 | 类型 | 描述 | 补充说明
 ------------ | ------------- | ------------- | -------------
 **GoodsId** | **string** | 商品编码  | 
-**Quantity** | **int32** | 商品数量  | 
-**UnitPrice** | **int32** | 商品价格  | 
-**DiscountAmount** | **int32** | 商品优惠金额  | 
+**Quantity** | **int64** | 商品数量  | 
+**UnitPrice** | **int64** | 商品价格  | 
+**DiscountAmount** | **int64** | 商品优惠金额  | 
 **GoodsRemark** | **string** | 商品备注  | [可选] 
 
 [\[返回类型列表\]](README.md#类型列表)

docs/payments/README.md

@@ -11,7 +11,10 @@
 
 ## 接口列表
 
-详见子模块接口列表
+所有URI均基于微信支付 API 地址：*https://api.mch.weixin.qq.com*
+
+服务名 | 方法名 | HTTP 请求 | 描述
+------------ | ------------- | ------------- | -------------
 
 
 ## 类型列表

docs/payments/TransactionAmount.md

@@ -6,8 +6,8 @@
 ------------ | ------------- | ------------- | -------------
 **Currency** | **string** |  | [可选] 
 **PayerCurrency** | **string** |  | [可选] 
-**PayerTotal** | **int32** |  | [可选] 
-**Total** | **int32** |  | [可选] 
+**PayerTotal** | **int64** |  | [可选] 
+**Total** | **int64** |  | [可选] 
 
 [\[返回类型列表\]](README.md#类型列表)
 [\[返回接口列表\]](README.md#接口列表)

docs/payments/app/Amount.md

@@ -4,7 +4,7 @@
 
 名称 | 类型 | 描述 | 补充说明
 ------------ | ------------- | ------------- | -------------
-**Total** | **int32** | 订单总金额，单位为分  | 
+**Total** | **int64** | 订单总金额，单位为分  | 
 **Currency** | **string** | CNY：人民币，境内商户号仅支持人民币。  | [可选] 
 
 [\[返回类型列表\]](README.md#类型列表)

docs/payments/app/AppApi.md

@@ -112,15 +112,15 @@ func main() {
 			SupportFapiao: core.Bool(false),
 			Amount: &app.Amount{
 				Currency: core.String("CNY"),
-				Total:    core.Int32(100),
+				Total:    core.Int64(100),
 			},
 			Detail: &app.Detail{
-				CostPrice: core.Int32(608800),
+				CostPrice: core.Int64(608800),
 				GoodsDetail: []app.GoodsDetail{app.GoodsDetail{
 					GoodsName:        core.String("iPhoneX 256G"),
 					MerchantGoodsId:  core.String("ABC"),
-					Quantity:         core.Int32(1),
-					UnitPrice:        core.Int32(828800),
+					Quantity:         core.Int64(1),
+					UnitPrice:        core.Int64(828800),
 					WechatpayGoodsId: core.String("1001"),
 				}},
 				InvoiceId: core.String("wx123"),

docs/payments/app/Detail.md

@@ -6,7 +6,7 @@
 
 名称 | 类型 | 描述 | 补充说明
 ------------ | ------------- | ------------- | -------------
-**CostPrice** | **int32** | 1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等，则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。  | [可选] 
+**CostPrice** | **int64** | 1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等，则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。  | [可选] 
 **InvoiceId** | **string** | 商家小票ID。  | [可选] 
 **GoodsDetail** | [**[]GoodsDetail**](GoodsDetail.md) |  | [可选] 
 

docs/payments/app/GoodsDetail.md

@@ -7,8 +7,8 @@
 **MerchantGoodsId** | **string** | 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成。  | 
 **WechatpayGoodsId** | **string** | 微信支付定义的统一商品编号（没有可不传）。  | [可选] 
 **GoodsName** | **string** | 商品的实际名称。  | [可选] 
-**Quantity** | **int32** | 用户购买的数量。  | 
-**UnitPrice** | **int32** | 商品单价，单位为分。  | 
+**Quantity** | **int64** | 用户购买的数量。  | 
+**UnitPrice** | **int64** | 商品单价，单位为分。  | 
 
 [\[返回类型列表\]](README.md#类型列表)
 [\[返回接口列表\]](README.md#接口列表)

docs/payments/h5/Amount.md

@@ -4,7 +4,7 @@
 
 名称 | 类型 | 描述 | 补充说明
 ------------ | ------------- | ------------- | -------------
-**Total** | **int32** | 订单总金额，单位为分  | 
+**Total** | **int64** | 订单总金额，单位为分  | 
 **Currency** | **string** | CNY：人民币，境内商户号仅支持人民币。  | [可选] 
 
 [\[返回类型列表\]](README.md#类型列表)

docs/payments/h5/Detail.md

@@ -6,7 +6,7 @@
 
 名称 | 类型 | 描述 | 补充说明
 ------------ | ------------- | ------------- | -------------
-**CostPrice** | **int32** | 1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等，则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。  | [可选] 
+**CostPrice** | **int64** | 1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等，则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。  | [可选] 
 **InvoiceId** | **string** | 商家小票ID。  | [可选] 
 **GoodsDetail** | [**[]GoodsDetail**](GoodsDetail.md) |  | [可选] 
 

docs/payments/h5/GoodsDetail.md

@@ -7,8 +7,8 @@
 **MerchantGoodsId** | **string** | 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成。  | 
 **WechatpayGoodsId** | **string** | 微信支付定义的统一商品编号（没有可不传）。  | [可选] 
 **GoodsName** | **string** | 商品的实际名称。  | [可选] 
-**Quantity** | **int32** | 用户购买的数量。  | 
-**UnitPrice** | **int32** | 商品单价，单位为分。  | 
+**Quantity** | **int64** | 用户购买的数量。  | 
+**UnitPrice** | **int64** | 商品单价，单位为分。  | 
 
 [\[返回类型列表\]](README.md#类型列表)
 [\[返回接口列表\]](README.md#接口列表)

docs/payments/h5/H5Api.md

@@ -112,15 +112,15 @@ func main() {
 			SupportFapiao: core.Bool(false),
 			Amount: &h5.Amount{
 				Currency: core.String("CNY"),
-				Total:    core.Int32(100),
+				Total:    core.Int64(100),
 			},
 			Detail: &h5.Detail{
-				CostPrice: core.Int32(608800),
+				CostPrice: core.Int64(608800),
 				GoodsDetail: []h5.GoodsDetail{h5.GoodsDetail{
 					GoodsName:        core.String("iPhoneX 256G"),
 					MerchantGoodsId:  core.String("ABC"),
-					Quantity:         core.Int32(1),
-					UnitPrice:        core.Int32(828800),
+					Quantity:         core.Int64(1),
+					UnitPrice:        core.Int64(828800),
 					WechatpayGoodsId: core.String("1001"),
 				}},
 				InvoiceId: core.String("wx123"),

docs/payments/jsapi/Amount.md

@@ -4,7 +4,7 @@
 
 名称 | 类型 | 描述 | 补充说明
 ------------ | ------------- | ------------- | -------------
-**Total** | **int32** | 订单总金额，单位为分  | 
+**Total** | **int64** | 订单总金额，单位为分  | 
 **Currency** | **string** | CNY：人民币，境内商户号仅支持人民币。  | [可选] 
 
 [\[返回类型列表\]](README.md#类型列表)

docs/payments/jsapi/Detail.md

@@ -6,7 +6,7 @@
 
 名称 | 类型 | 描述 | 补充说明
 ------------ | ------------- | ------------- | -------------
-**CostPrice** | **int32** | 1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等，则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。  | [可选] 
+**CostPrice** | **int64** | 1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等，则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。  | [可选] 
 **InvoiceId** | **string** | 商家小票ID。  | [可选] 
 **GoodsDetail** | [**[]GoodsDetail**](GoodsDetail.md) |  | [可选] 
 

docs/payments/jsapi/GoodsDetail.md

@@ -7,8 +7,8 @@
 **MerchantGoodsId** | **string** | 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成。  | 
 **WechatpayGoodsId** | **string** | 微信支付定义的统一商品编号（没有可不传）。  | [可选] 
 **GoodsName** | **string** | 商品的实际名称。  | [可选] 
-**Quantity** | **int32** | 用户购买的数量。  | 
-**UnitPrice** | **int32** | 商品单价，单位为分。  | 
+**Quantity** | **int64** | 用户购买的数量。  | 
+**UnitPrice** | **int64** | 商品单价，单位为分。  | 
 
 [\[返回类型列表\]](README.md#类型列表)
 [\[返回接口列表\]](README.md#接口列表)

docs/payments/jsapi/JsapiApi.md

@@ -112,18 +112,18 @@ func main() {
 			SupportFapiao: core.Bool(false),
 			Amount: &jsapi.Amount{
 				Currency: core.String("CNY"),
-				Total:    core.Int32(100),
+				Total:    core.Int64(100),
 			},
 			Payer: &jsapi.Payer{
 				Openid: core.String("oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"),
 			},
 			Detail: &jsapi.Detail{
-				CostPrice: core.Int32(608800),
+				CostPrice: core.Int64(608800),
 				GoodsDetail: []jsapi.GoodsDetail{jsapi.GoodsDetail{
 					GoodsName:        core.String("iPhoneX 256G"),
 					MerchantGoodsId:  core.String("ABC"),
-					Quantity:         core.Int32(1),
-					UnitPrice:        core.Int32(828800),
+					Quantity:         core.Int64(1),
+					UnitPrice:        core.Int64(828800),
 					WechatpayGoodsId: core.String("1001"),
 				}},
 				InvoiceId: core.String("wx123"),

docs/payments/native/Amount.md

@@ -4,7 +4,7 @@
 
 名称 | 类型 | 描述 | 补充说明
 ------------ | ------------- | ------------- | -------------
-**Total** | **int32** | 订单总金额，单位为分  | 
+**Total** | **int64** | 订单总金额，单位为分  | 
 **Currency** | **string** | CNY：人民币，境内商户号仅支持人民币。  | [可选] 
 
 [\[返回类型列表\]](README.md#类型列表)

docs/payments/native/Detail.md

@@ -6,7 +6,7 @@
 
 名称 | 类型 | 描述 | 补充说明
 ------------ | ------------- | ------------- | -------------
-**CostPrice** | **int32** | 1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等，则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。  | [可选] 
+**CostPrice** | **int64** | 1.商户侧一张小票订单可能被分多次支付，订单原价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等，则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付，以享受多次优惠的情况，正常支付订单不必上传此参数。  | [可选] 
 **InvoiceId** | **string** | 商家小票ID。  | [可选] 
 **GoodsDetail** | [**[]GoodsDetail**](GoodsDetail.md) |  | [可选] 
 

docs/payments/native/GoodsDetail.md

@@ -7,8 +7,8 @@
 **MerchantGoodsId** | **string** | 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成。  | 
 **WechatpayGoodsId** | **string** | 微信支付定义的统一商品编号（没有可不传）。  | [可选] 
 **GoodsName** | **string** | 商品的实际名称。  | [可选] 
-**Quantity** | **int32** | 用户购买的数量。  | 
-**UnitPrice** | **int32** | 商品单价，单位为分。  | 
+**Quantity** | **int64** | 用户购买的数量。  | 
+**UnitPrice** | **int64** | 商品单价，单位为分。  | 
 
 [\[返回类型列表\]](README.md#类型列表)
 [\[返回接口列表\]](README.md#接口列表)

docs/payments/native/NativeApi.md

@@ -112,15 +112,15 @@ func main() {
 			SupportFapiao: core.Bool(false),
 			Amount: &native.Amount{
 				Currency: core.String("CNY"),
-				Total:    core.Int32(100),
+				Total:    core.Int64(100),
 			},
 			Detail: &native.Detail{
-				CostPrice: core.Int32(608800),
+				CostPrice: core.Int64(608800),
 				GoodsDetail: []native.GoodsDetail{native.GoodsDetail{
 					GoodsName:        core.String("iPhoneX 256G"),
 					MerchantGoodsId:  core.String("ABC"),
-					Quantity:         core.Int32(1),
-					UnitPrice:        core.Int32(828800),
+					Quantity:         core.Int64(1),
+					UnitPrice:        core.Int64(828800),
 					WechatpayGoodsId: core.String("1001"),
 				}},
 				InvoiceId: core.String("wx123"),