Fix naming convention (#107)

* docs: 修复文档中的API链接，使其与示例代码匹配 * docs: 统一文档中的缩写用法 `cert` --> `certificate` `serialNo` --> `serialNumber` * format: 调整代码/注释格式问题 * ci(staticcheck): 修复最新版 staticcheck 安装失败的问题 * ci(staticcheck): 更新 revive disble 注释的书写位置以符合[email protected]
wechatpay-apiv3 · May 13, 2022 · a6d5373 · a6d5373
1 parent 4460612
commit a6d5373
Show file tree

Hide file tree

Showing 11 changed files with 77 additions and 60 deletions.
diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
@@ -39,7 +39,7 @@ jobs:
         go-version: "1.16"
     - name: staticcheck
       run: |
-        go get -u honnef.co/go/tools/cmd/staticcheck@latest &&
+        go get -u honnef.co/go/tools/cmd/staticcheck@v0.2.2 &&
         $HOME/go/bin/staticcheck ./...
     - name: Revive Action
       uses: morphy2k/[email protected]

diff --git a/FAQ.md b/FAQ.md
@@ -18,7 +18,7 @@ go get -u github.com/wechatpay-apiv3/wechatpay-go/cmd/wechatpay_download_certs
 ```
 然后执行 `wechatpay_download_certs` 即可下载微信支付平台证书到当前目录
 ```shell
-wechatpay_download_certs -m <mchID> -p <mchPrivateKeyPath> -s <mchSerialNo> -k <mchAPIv3Key>
+wechatpay_download_certs -m <mchID> -p <mchPrivateKeyPath> -s <mchSerialNumber> -k <mchAPIv3Key>
 ```
 完整参数列表可运行 `wechatpay_download_certs -h` 查看。
 
@@ -28,7 +28,7 @@ wechatpay_download_certs -m <mchID> -p <mchPrivateKeyPath> -s <mchSerialNo> -k <
 
 ```go
 // GetCertificate 获取商户的某个平台证书
-func (mgr *CertificateDownloaderMgr) GetCertificate(ctx context.Context, mchID, serialNo string) (*x509.Certificate, bool)
+func (mgr *CertificateDownloaderMgr) GetCertificate(ctx context.Context, mchID, serialNumber string) (*x509.Certificate, bool)
 
 // GetCertificateVisitor 获取某个商户的平台证书访问器
 func (mgr *CertificateDownloaderMgr) GetCertificateVisitor(mchID string) core.CertificateVisitor

diff --git a/README.md b/README.md
@@ -97,7 +97,7 @@ func main() {
 
 ## 更多示例
 
-### 以 [JSAPI下单](https://pay.weixin.qq.com/wiki/doc/apiv3_partner/apis/chapter4_1_1.shtml) 为例
+### 以 [JSAPI下单](https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter3_1_1.shtml) 为例
 
 ```go
 import (
@@ -131,7 +131,7 @@ if err == nil {
 }
 ```
 
-### 以 [查询订单](https://pay.weixin.qq.com/wiki/doc/apiv3_partner/apis/chapter4_1_2.shtml) 为例
+### 以 [查询订单](https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter3_1_2.shtml) 为例
 
 ```go
 import (
@@ -297,9 +297,9 @@ ctx := context.Background()
 // 1. 使用 `RegisterDownloaderWithPrivateKey` 注册下载器
 err := downloader.MgrInstance().RegisterDownloaderWithPrivateKey(ctx, mchPrivateKey, mchCertificateSerialNumber, mchID, mchAPIV3Key)
 // 2. 获取商户号对应的微信支付平台证书访问器
-certVisitor := downloader.MgrInstance().GetCertificateVisitor(mchID)
+certificateVisitor := downloader.MgrInstance().GetCertificateVisitor(mchID)
 // 3. 使用证书访问器初始化 `notify.Handler`
-handler := notify.NewNotifyHandler(mchAPIv3Key, verifiers.NewSHA256WithRSAVerifier(certVisitor))
+handler := notify.NewNotifyHandler(mchAPIv3Key, verifiers.NewSHA256WithRSAVerifier(certificateVisitor))
 ```
 
 + 方法二：像 [发送请求](#发送请求) 那样使用 `WithWechatPayAutoAuthCipher` 初始化 `core.Client`，然后再用client进行接口调用。
@@ -314,9 +314,9 @@ opts := []core.ClientOption{
 }
 client, err := core.NewClient(ctx, opts...)	
 // 2. 获取商户号对应的微信支付平台证书访问器
-certVisitor := downloader.MgrInstance().GetCertificateVisitor(mchID)
+certificateVisitor := downloader.MgrInstance().GetCertificateVisitor(mchID)
 // 3. 使用证书访问器初始化 `notify.Handler`
-handler := notify.NewNotifyHandler(mchAPIv3Key, verifiers.NewSHA256WithRSAVerifier(certVisitor))
+handler := notify.NewNotifyHandler(mchAPIv3Key, verifiers.NewSHA256WithRSAVerifier(certificateVisitor))
 // 4. 使用client进行接口调用
 // ...
 ```
@@ -330,9 +330,9 @@ handler := notify.NewNotifyHandler(mchAPIv3Key, verifiers.NewSHA256WithRSAVerifi
 mchAPIv3Key := "<your apiv3 key>"
 wechatPayCert, err := utils.LoadCertificate("<your wechat pay certificate>")
 // 2. 使用本地管理的微信支付平台证书获取微信支付平台证书访问器
-certVisitor := core.NewCertificateMapWithList([]*x509.Certificate{wechatPayCert})
+certificateVisitor := core.NewCertificateMapWithList([]*x509.Certificate{wechatPayCert})
 // 3. 使用apiv3 key、证书访问器初始化 `notify.Handler`
-handler := notify.NewNotifyHandler(mchAPIv3Key, verifiers.NewSHA256WithRSAVerifier(certVisitor))
+handler := notify.NewNotifyHandler(mchAPIv3Key, verifiers.NewSHA256WithRSAVerifier(certificateVisitor))
 ```
 
 建议：为了正确使用平台证书下载管理器，你应阅读并理解 [如何使用平台证书下载管理器](FAQ.md#如何使用平台证书下载管理器)。

diff --git a/core/certificate_map.go b/core/certificate_map.go
@@ -36,8 +36,8 @@ func (m *CertificateMap) Reset(newCertificates map[string]*x509.Certificate) {
 }
 
 // Get 获取证书序列号对应的平台证书
-func (m *CertificateMap) Get(_ context.Context, serialNo string) (*x509.Certificate, bool) {
-	cert, ok := m.m[serialNo]
+func (m *CertificateMap) Get(_ context.Context, serialNumber string) (*x509.Certificate, bool) {
+	cert, ok := m.m[serialNumber]
 	return cert, ok
 }
 

diff --git a/core/certificate_visitor.go b/core/certificate_visitor.go
@@ -10,7 +10,7 @@ import (
 // CertificateGetter 平台证书提供器
 type CertificateGetter interface {
 	// Get 获取证书序列号对应的平台证书
-	Get(ctx context.Context, serialNo string) (*x509.Certificate, bool)
+	Get(ctx context.Context, serialNumber string) (*x509.Certificate, bool)
 	// GetAll 获取平台证书Map
 	GetAll(ctx context.Context) map[string]*x509.Certificate
 	// GetNewestSerial 获取最新的平台证书的证书序列号
@@ -20,7 +20,7 @@ type CertificateGetter interface {
 // CertificateExporter 平台证书导出器，可获取平台证书内容，
 type CertificateExporter interface {
 	// Export 获取证书序列号对应的平台证书内容
-	Export(ctx context.Context, serialNo string) (string, bool)
+	Export(ctx context.Context, serialNumber string) (string, bool)
 	// ExportAll 获取平台证书内容Map
 	ExportAll(ctx context.Context) map[string]string
 }

diff --git a/core/client.go b/core/client.go
@@ -409,7 +409,8 @@ func CreateFormFile(w *multipart.Writer, filename, contentType string, file []by
 	return err
 }
 
-// Set Request body from an interface
+//revive:disable-next-line:cyclomatic 本函数实现需要考虑多种情况，但理解起来并不复杂，进行圈复杂度豁免
+// setBody Set Request body from an interface
 func setBody(body interface{}, contentType string) (bodyBuf *bytes.Buffer, err error) {
 	bodyBuf = &bytes.Buffer{}
 
@@ -442,7 +443,7 @@ func setBody(body interface{}, contentType string) (bodyBuf *bytes.Buffer, err e
 	return bodyBuf, nil
 }
 
-// contains is a case insensitive match, finding needle in a haystack
+// contains is a case-insensitive match, finding needle in a haystack
 func contains(haystack []string, needle string) bool {
 	for _, a := range haystack {
 		if strings.EqualFold(a, needle) {

diff --git a/core/client_example_test.go b/core/client_example_test.go
@@ -24,14 +24,14 @@ func ExampleNewClient_default() {
 		mchID                      string
 		mchCertificateSerialNumber string
 		mchPrivateKey              *rsa.PrivateKey
-		wechatPayCertList          []*x509.Certificate
+		wechatPayCertificateList   []*x509.Certificate
 		customHTTPClient           *http.Client
 	)
 
 	client, err := core.NewClient(
 		context.Background(),
 		// 一次性设置 签名/验签/敏感字段加解密，并注册 平台证书下载器，自动定时获取最新的平台证书
-		option.WithWechatPayAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, wechatPayCertList),
+		option.WithWechatPayAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, wechatPayCertificateList),
 		// 设置自定义 HTTPClient 实例，不设置时默认使用 http.Client{}，并设置超时时间为 30s
 		option.WithHTTPClient(customHTTPClient),
 	)

diff --git a/core/downloader/downloader.go b/core/downloader/downloader.go
@@ -28,8 +28,8 @@ func isSameCertificateMap(l, r map[string]*x509.Certificate) bool {
 		return false
 	}
 
-	for serialNo := range l {
-		if _, ok := r[serialNo]; !ok {
+	for serialNumber := range l {
+		if _, ok := r[serialNumber]; !ok {
 			return false
 		}
 	}
@@ -47,11 +47,11 @@ type CertificateDownloader struct {
 }
 
 // Get 获取证书序列号对应的平台证书
-func (d *CertificateDownloader) Get(ctx context.Context, serialNo string) (*x509.Certificate, bool) {
+func (d *CertificateDownloader) Get(ctx context.Context, serialNumber string) (*x509.Certificate, bool) {
 	d.lock.RLock()
 	defer d.lock.RUnlock()
 
-	return d.certificates.Get(ctx, serialNo)
+	return d.certificates.Get(ctx, serialNumber)
 }
 
 // GetAll 获取平台证书Map
@@ -71,11 +71,11 @@ func (d *CertificateDownloader) GetNewestSerial(ctx context.Context) string {
 }
 
 // Export 获取证书序列号对应的平台证书内容
-func (d *CertificateDownloader) Export(_ context.Context, serialNo string) (string, bool) {
+func (d *CertificateDownloader) Export(_ context.Context, serialNumber string) (string, bool) {
 	d.lock.RLock()
 	defer d.lock.RUnlock()
 
-	content, ok := d.certContents[serialNo]
+	content, ok := d.certContents[serialNumber]
 	return content, ok
 }
 
@@ -85,8 +85,8 @@ func (d *CertificateDownloader) ExportAll(_ context.Context) map[string]string {
 	defer d.lock.RUnlock()
 
 	ret := make(map[string]string)
-	for serialNo, content := range d.certContents {
-		ret[serialNo] = content
+	for serialNumber, content := range d.certContents {
+		ret[serialNumber] = content
 	}
 
 	return ret
@@ -156,10 +156,10 @@ func (d *CertificateDownloader) DownloadCertificates(ctx context.Context) error
 			return fmt.Errorf("parse downlaoded certificate failed: %v, certcontent:%v", err, certContent)
 		}
 
-		serialNo := *rawCertificate.SerialNo
+		serialNumber := *rawCertificate.SerialNo
 
-		rawCertContentMap[serialNo] = certContent
-		certificateMap[serialNo] = certificate
+		rawCertContentMap[serialNumber] = certContent
+		certificateMap[serialNumber] = certificate
 	}
 
 	if len(certificateMap) == 0 {

diff --git a/core/downloader/downloader_mgr.go b/core/downloader/downloader_mgr.go
@@ -29,8 +29,8 @@ func (d *pseudoCertificateDownloader) GetAll(ctx context.Context) map[string]*x5
 }
 
 // Get 获取证书序列号对应的平台证书
-func (d *pseudoCertificateDownloader) Get(ctx context.Context, serialNo string) (*x509.Certificate, bool) {
-	return d.mgr.GetCertificate(ctx, d.mchID, serialNo)
+func (d *pseudoCertificateDownloader) Get(ctx context.Context, serialNumber string) (*x509.Certificate, bool) {
+	return d.mgr.GetCertificate(ctx, d.mchID, serialNumber)
 }
 
 // GetNewestSerial 获取最新的平台证书的证书序列号
@@ -44,8 +44,8 @@ func (d *pseudoCertificateDownloader) ExportAll(ctx context.Context) map[string]
 }
 
 // Export 获取证书序列号对应的平台证书内容
-func (d *pseudoCertificateDownloader) Export(ctx context.Context, serialNo string) (string, bool) {
-	return d.mgr.ExportCertificate(ctx, d.mchID, serialNo)
+func (d *pseudoCertificateDownloader) Export(ctx context.Context, serialNumber string) (string, bool) {
+	return d.mgr.ExportCertificate(ctx, d.mchID, serialNumber)
 }
 
 // CertificateDownloaderMgr 证书下载器管理器
@@ -70,7 +70,7 @@ func (mgr *CertificateDownloaderMgr) Stop() {
 }
 
 // GetCertificate 获取商户的某个平台证书
-func (mgr *CertificateDownloaderMgr) GetCertificate(ctx context.Context, mchID, serialNo string) (
+func (mgr *CertificateDownloaderMgr) GetCertificate(ctx context.Context, mchID, serialNumber string) (
 	*x509.Certificate, bool,
 ) {
 	mgr.lock.RLock()
@@ -81,7 +81,7 @@ func (mgr *CertificateDownloaderMgr) GetCertificate(ctx context.Context, mchID,
 		return nil, false
 	}
 
-	return downloader.Get(ctx, serialNo)
+	return downloader.Get(ctx, serialNumber)
 }
 
 // GetCertificateMap 获取商户的平台证书Map
@@ -109,7 +109,7 @@ func (mgr *CertificateDownloaderMgr) GetNewestCertificateSerial(ctx context.Cont
 }
 
 // ExportCertificate 获取商户的某个平台证书内容
-func (mgr *CertificateDownloaderMgr) ExportCertificate(ctx context.Context, mchID, serialNo string) (string, bool) {
+func (mgr *CertificateDownloaderMgr) ExportCertificate(ctx context.Context, mchID, serialNumber string) (string, bool) {
 	mgr.lock.RLock()
 	downloader, ok := mgr.downloaderMap[mchID]
 	mgr.lock.RUnlock()
@@ -118,7 +118,7 @@ func (mgr *CertificateDownloaderMgr) ExportCertificate(ctx context.Context, mchI
 		return "", false
 	}
 
-	return downloader.Export(ctx, serialNo)
+	return downloader.Export(ctx, serialNumber)
 }
 
 // ExportCertificateMap 导出商户的平台证书内容Map

diff --git a/core/downloader/example_test.go b/core/downloader/example_test.go
@@ -17,22 +17,22 @@ func ExampleNewCertificateDownloader_saveCert() {
 	ctx := context.Background()
 
 	var (
-		mchID           string
-		mchCertSerialNo string
-		mchPrivateKey   *rsa.PrivateKey
-		mchAPIv3Key     string
+		mchID                      string
+		mchCertificateSerialNumber string
+		mchPrivateKey              *rsa.PrivateKey
+		mchAPIv3Key                string
 	)
 	// 假设以上参数已初始化完成
 
-	d, err := downloader.NewCertificateDownloader(ctx, mchID, mchPrivateKey, mchCertSerialNo, mchAPIv3Key)
+	d, err := downloader.NewCertificateDownloader(ctx, mchID, mchPrivateKey, mchCertificateSerialNumber, mchAPIv3Key)
 	if err != nil {
 		fmt.Println(err)
 		return
 	}
 
-	for serialNo, certContent := range d.ExportAll(ctx) {
-		// 将 certContent 写入文件 *.pem
-		_, _ = serialNo, certContent
+	for serialNumber, certificateContent := range d.ExportAll(ctx) {
+		// 将 certificateContent 写入文件 *.pem
+		_, _ = serialNumber, certificateContent
 	}
 }
 
@@ -42,43 +42,45 @@ func ExampleNewCertificateDownloaderMgr() {
 	// CertificateDownloaderMgr 初始化完成，尚未注册任何 Downloader，不会进行任何证书下载
 
 	var (
-		mchID           string
-		mchCertSerialNo string
-		mchPrivateKey   *rsa.PrivateKey
-		mchAPIv3Key     string
+		mchID                      string
+		mchCertificateSerialNumber string
+		mchPrivateKey              *rsa.PrivateKey
+		mchAPIv3Key                string
 	)
 	// 假设以上参数已初始化完成
 
 	// 注册证书下载器
 	if err := mgr.RegisterDownloaderWithPrivateKey(
-		ctx, mchPrivateKey, mchCertSerialNo, mchID, mchAPIv3Key,
+		ctx, mchPrivateKey, mchCertificateSerialNumber, mchID, mchAPIv3Key,
 	); err == nil {
 		fmt.Println(err)
 		return
 	}
 	// 可以注册多个商户的证书下载器...
 
 	// 获取证书访问器
-	certVisitor := mgr.GetCertificateVisitor(mchID)
+	certificateVisitor := mgr.GetCertificateVisitor(mchID)
 
-	// 使用 certVisitor 初始化 Validator 进行验签
-	option.WithVerifier(verifiers.NewSHA256WithRSAVerifier(certVisitor))
+	// 使用 certificateVisitor 初始化 Validator 进行验签
+	option.WithVerifier(verifiers.NewSHA256WithRSAVerifier(certificateVisitor))
 }
 
 func ExampleNewCertificateDownloaderMgr_useMgr() {
-	var certDownloadMgr *downloader.CertificateDownloaderMgr
-	// certDownloadMgr 已经初始化完成且注册了需要的 Downloader
+	var certificateDownloaderMgr *downloader.CertificateDownloaderMgr
+	// certificateDownloaderMgr 已经初始化完成且注册了需要的 Downloader
 
 	var (
-		mchID           string
-		mchCertSerialNo string
-		mchPrivateKey   *rsa.PrivateKey
+		mchID                      string
+		mchCertificateSerialNumber string
+		mchPrivateKey              *rsa.PrivateKey
 	)
 
 	ctx := context.Background()
 	client, err := core.NewClient(
 		ctx,
-		option.WithWechatPayAutoAuthCipherUsingDownloaderMgr(mchID, mchCertSerialNo, mchPrivateKey, certDownloadMgr),
+		option.WithWechatPayAutoAuthCipherUsingDownloaderMgr(
+			mchID, mchCertificateSerialNumber, mchPrivateKey, certificateDownloaderMgr,
+		),
 	)
 
 	if err != nil {

diff --git a/utils/pem.go b/utils/pem.go
@@ -101,11 +101,25 @@ func GetCertificateSerialNumber(certificate x509.Certificate) string {
 }
 
 // IsCertExpired 判定证书在特定时间是否过期
+//
+// Deprecated: 请使用 IsCertificateExpired
 func IsCertExpired(certificate x509.Certificate, now time.Time) bool {
 	return now.After(certificate.NotAfter)
 }
 
+// IsCertificateExpired 判定证书在特定时间是否过期
+func IsCertificateExpired(certificate x509.Certificate, now time.Time) bool {
+	return now.After(certificate.NotAfter)
+}
+
 // IsCertValid 判定证书在特定时间是否有效
+//
+// Deprecated: 请使用 IsCertificateValid
 func IsCertValid(certificate x509.Certificate, now time.Time) bool {
 	return now.After(certificate.NotBefore) && now.Before(certificate.NotAfter)
 }
+
+// IsCertificateValid 判定证书在特定时间是否有效
+func IsCertificateValid(certificate x509.Certificate, now time.Time) bool {
+	return now.After(certificate.NotBefore) && now.Before(certificate.NotAfter)
+}