wx

package module
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 28, 2023 License: MIT Imports: 36 Imported by: 0

README

wechat

wechat weixin sdk，支持微信应用和商户。

设计目标

在概念清晰的基础上追求更少的编码、更开放、灵活的结构。

本库不是在微信官方API基础上进一步封装，造出一个新的框架级的重体量SDK。而是努力成为微信官方文档的Golang版快速工具箱。

努力让开发者在学习微信官方文档后，不再有新的学习曲线（另学一套）！

所以本库目标是：极致、简单！不创另行发明新理念、不另行创造新架构！

概述

根据微信的文档，微信的业务有两个不同的领域：

  • 应用类账号下的Api
  • 商户类账号下的Api

遵守高内聚，低耦合的设计哲学。

所有同类型的请求，都能复用，封装聚合。其它零散的功能都封装成独立函数，按需调用。

所有的接口、请求数据、请求结果数据，都是开放的；可以使用我提供的数据，也能自行设计。

安装

go get github.com/blusewang/wx

应用账号API

订阅号、服务号、小程序、App

  • 支持连接不同的地区的微信服务器
  • 支持一行代码从被动消息的 http.Request 中安全取出消息成MessageData。内部实现了识别并解密消息、校验请求的Query数据。
  • 支持自动填充Query中的access_token数据。
  • 链式调用，让不同需求的业务能一气和成！

时效性凭证安置方式约定

access_token、js_sdk_ticket 这类需要每7200秒刷新一次的，放到crontab中。

对此不满的，完全可以在使用本库的基础上，采用自己熟悉的方式、甚至自己设计方案来替代crontab。

程序设计

对象设计

一个基础账号对象MpAccount，它有三个行为：

  • 为微信H5的网址签名 UrlSign(url string)
  • 读取被动消息通知 ReadMessage(req *http.Request)
  • 主动发出请求 NewMpReq(path mp_api.MpApi) *mpReq
数据设计
说明

只实现了很有限的数据。若需要使用本库自带的数据结构之外的API。完全可以参考本库的数据结构写法，自行另起书写(注意不同业务的tag名称不同)。 并能得到一样的兼容体验！

举例

	a := wx.MpAccount{
		AppId:       "your_app_id",
		AccessToken: "38_XtyPcVUODHd8q3TNYPVGAZ2WNRx_nW4gnclObbv78tsEa1Y_bwdkLALDMEb4372wYqcC_CanjU9O0Zw4MqHiqxrIukk_G4ElAUxyv_ASOb0V2y8647cbxbYU-G8CbtnPdLNub8NrqtUVrSTnWAPaAGALPE",
        // ...
		ServerHost:  mp_api.ServerHostShangHai, // 选择离自己最近的服务主机
	}

    // 一个简单的只带access_token的GET API
	var list mp_api.MessageCustomServiceKfListRes
	if err := a.NewMpReq(mp_api.MessageCustomServiceKfList).Bind(&list).Do(); err != nil {
		t.Error(err)
	}
	log.Println(list)

    // 一个POST API
	var rs mp_api.AccountShortUrlRes
	err = a.NewMpReq(mp_api.AccountShortUrl).SendData(mp_api.AccountShortUrlData{
		Action:  mp_api.ShortUrlAction,
		LongUrl: "https://developers.weixin.qq.com/doc/offiaccount/Account_Management/URL_Shortener.html",
	}).Bind(&rs).Do()
	if err != nil {
		t.Error(err)
	}
	log.Println(rs)

    // 一个上传媒体文件的API
	err = a.NewMpReq(mp_api.MessageCustomServiceKfAccountUploadHeadImg).Query(mp_api.MessageCustomServiceKfAccountUploadHeadImgQuery{
		KfAccount: "1@1",
	}).Upload(resp.Body, "png")
	if err != nil {
		t.Error(err)
	}

商户账号API（V2版）

App、JSAPI、小程序下单 分账 付款至微信零钱 付款至个人银行卡 发红包

  • 自动填充基础信息
  • 自动签名
  • 私有证书HTTP客户端自动缓存
  • 支持MD5、HMAC-SHA256加密
  • 支持付款至银行卡时，隐私信息加密

程序设计

对象设计

一个基础账号对象MchAccount，它有以下适用于V2的行为：

  • 创建请求 NewMchReq(url string)
  • 将订单签名给App OrderSign4App(or mch_api.PayUnifiedOrderRes)
  • 将订单签名给于H5、小程序 OrderSign(or mch_api.PayUnifiedOrderRes)
  • 验证支付成功通知 PayNotify(pn mch_api.PayNotify)
  • 付款至银行卡时，隐私信息项加密 RsaEncrypt(plain string)
数据设计
说明

只实现了很有限的数据。若需要使用本库自带的数据结构之外的API。完全可以参考本库的数据结构写法，自行另起书写(建议参考structs.go中的方式书写)。 能得到一样的兼容体验！

举例

    mch := wx.MchAccount{}
    
	var data mch_api.PayProfitSharingRes
	var body = mch_api.PayProfitSharingData{
		TransactionId: "4200000531202004307536721907",
		OutOrderNo:    "TSF_216144_1065_ye7DvHdSed",
	}
	_ = body.SerReceivers([]mch_api.PayProfitSharingReceiver{
		{
			Type:        "",
			Account:     "",
			Amount:      10,
			Description: "",
		},
	})

	err := mch.NewMchReq(mch_api.PayProfitSharing).
		Send(&body). // 注意：发送的数据需传指针，以便自动填充基础信息和签名
		UseHMacSign(). // 指定使用HMAC-SHA256
		UsePrivateCert(). // 指定使用私有证书通信
		Bind(&data).Do() // 传指针
	log.Println(err)
	log.Println(data)

商户账号API（V3版）（含服务商）

App、JSAPI、小程序等支付 分账 付款至微信零钱 付款至个人银行卡 服务商系列接口

  • 支持付款至银行卡时，隐私信息加密
  • 自动签名
  • 自动下载微信支付官方证书

程序设计

对象设计

一个基础账号对象MchAccount，它有以下适用于V3的行为：

  • 创建请求 NewMchReqV3(api mch_api_v3.MchApiV3)
  • 获取微信支付官方证书 LoadV3Cert()
  • AEAD_AES_256_GCM 解密 DecryptAES256GCM(nonce, associatedData, ciphertext string)
  • V3版通用签名 SignBaseV3(message string)
数据设计
说明

如果程序长时间运行，需要给DownloadV3Cert()做一个定时更新的任务。按自己的需求自行实现。 如果不实现，DownloadV3Cert()只会在第一次操作V3接口时获取一次。

举例

    mch := wx.MchAccount{}

	var res mch_api_v3.JsApiTransactionResp
	err = mch.NewMchReqV3(mch_api_v3.JsApiTransaction).Send(&mch_api_v3.JsApiTransactionReq{
		AppId:       constant.WxAppMember,
		MchId:       mch.MchId,
		Description: "this is a description",
		OutTradeNo:  wx.NewRandStr(22),
		NotifyUrl:   "https://yourdomain.name/notify/url",
		Amount:      mch_api_v3.Amount{Total: 100},
		Payer:       mch_api_v3.Payer{OpenId: "oEG8Ss_yCRB315jjLfdTRK-QicdY"},
	}).Bind(&res).Do(http.MethodPost)
	if err != nil {
		t.Fatal(err)
	}
	log.Println(res)

API Hook，同时支持两个类型的所有API

RegisterHook(hook func(req *http.Request, reqBody []byte, res *http.Response, err error)) 将每一次网络交互过程都开放出来，以便做自定义日志。

为微信业务数据提供的额外工具方法

  • NewRandStr 生成符合微信要求随机字符
  • LimitString 限制长度，并将微信不支持的字符替换成'x'，能满足公众号App的字符要求
  • SafeString 安全地限制长度，并将微信不支持的字符替换成'x'，能满足商户平台的字符要求

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func LimitString 

func LimitString(str string, length int) string

LimitString 限制长度，并将微信不支持的字符替换成'x'，能满足公众号App的字符要求

func NewRandStr 

func NewRandStr(n int) string

NewRandStr 生成符合微信要求随机字符

func RegisterHook added in v1.2.2 

func RegisterHook(hook func(req *http.Request, reqBody []byte, res *http.Response, startAt time.Time, stopAt time.Time, err error))

func SafeString 

func SafeString(str string, length int) string

SafeString 安全地限制长度，并将微信不支持的字符替换成'x'，能满足商户平台的字符要求

Types

type H 

type H map[string]interface{}

type MchAccount 

type MchAccount struct {
	MchId    string
	MchKeyV2 string
	MchKeyV3 string
	// contains filtered or unexported fields
}

MchAccount 商户账号

func NewMchAccount added in v1.3.0 

func NewMchAccount(mchid, key2, key3 string, cert, key, pubKey []byte) (ma *MchAccount, err error)

NewMchAccount 实例化商户账号

func (MchAccount) DecryptAES256GCM added in v1.3.0 

func (ma MchAccount) DecryptAES256GCM(nonce, associatedData, ciphertext string) (out []byte, err error)

DecryptAES256GCM AEAD_AES_256_GCM 解密

func (MchAccount) DecryptRefundNotify added in v1.2.3 

func (ma MchAccount) DecryptRefundNotify(rn mch_api.RefundNotify) (body mch_api.RefundNotifyBody, err error)

DecryptRefundNotify 验证支付成功通知

func (MchAccount) DownloadV3Cert added in v1.3.0 

func (ma MchAccount) DownloadV3Cert() (err error)

DownloadV3Cert 获取微信支付官方证书

func (MchAccount) GetCertificate added in v1.3.1 

func (ma MchAccount) GetCertificate() (cert *x509.Certificate, err error)

GetCertificate 获取证书

func (MchAccount) NewMchReq 

func (ma MchAccount) NewMchReq(api mch_api.MchApi) (req *mchReq)

NewMchReq 创建请求

func (MchAccount) NewMchReqV3 added in v1.2.0 

func (ma MchAccount) NewMchReqV3(api mch_api_v3.MchApiV3) (req *mchReqV3)

NewMchReqV3 创建请求

func (MchAccount) NewMchReqWithApp 

func (ma MchAccount) NewMchReqWithApp(api mch_api.MchApi, appId string) (req *mchReq)

NewMchReqWithApp 创建请求

func (MchAccount) OrderSign 

func (ma MchAccount) OrderSign(or mch_api.PayUnifiedOrderRes) H

OrderSign 订单签名，适用于H5、小程序

func (MchAccount) OrderSign4App 

func (ma MchAccount) OrderSign4App(or mch_api.PayUnifiedOrderRes) H

OrderSign4App 订单签名给App

func (MchAccount) PayNotify 

func (ma MchAccount) PayNotify(pn mch_api.PayNotify) bool

PayNotify 验证支付成功通知

func (MchAccount) RsaDecrypt added in v1.3.0 

func (ma MchAccount) RsaDecrypt(ciphertext string) (out string, err error)

RsaDecrypt 机要信息解密 兼容V2/V3

func (MchAccount) RsaEncrypt 

func (ma MchAccount) RsaEncrypt(plain string) (out string)

RsaEncrypt 机要信息加密V2

func (MchAccount) RsaEncryptV3 added in v1.3.0 

func (ma MchAccount) RsaEncryptV3(plain string) (out string)

RsaEncryptV3 机要信息加密V3

func (MchAccount) SignAppV3 added in v1.3.0 

func (ma MchAccount) SignAppV3(appId, prepayId string) (out H, err error)

SignAppV3 App支付订单签名

func (MchAccount) SignBaseV3 added in v1.3.0 

func (ma MchAccount) SignBaseV3(message string) (sign string, err error)

SignBaseV3 V3版通用签名

func (MchAccount) SignJSAPIV3 added in v1.3.0 

func (ma MchAccount) SignJSAPIV3(appId, prepayId string) (out H, err error)

SignJSAPIV3 JSAPI支付订单签名

func (MchAccount) VerifyV3 added in v1.3.0 

func (ma MchAccount) VerifyV3(header http.Header, body []byte) (err error)

VerifyV3 验签

type MpAccount 

type MpAccount struct {
	AppId                 string            `json:"app_id"`
	AccessToken           string            `json:"access_token"`
	AppSecret             string            `json:"app_secret"`
	PrivateToken          string            `json:"private_token"`
	EncodingAESKey        string            `json:"encoding_aes_key"`
	JsSdkTicket           string            `json:"js_sdk_ticket"`
	ComponentVerifyTicket *string           `json:"component_verify_ticket"`
	ServerHost            mp_api.ServerHost `json:"server_host"`
}

MpAccount 应用账号 ServerHost 默认为：mp_api.ServerHostUniversal

func (MpAccount) NewMpReq 

func (ma MpAccount) NewMpReq(path mp_api.MpApi) *mpReq

NewMpReq 新建一个请求

func (MpAccount) ReadMessage 

func (ma MpAccount) ReadMessage(req *http.Request) (q mp_api.MessageQuery, msg mp_api.MessageData, err error)

ReadMessage 读取通知消息

func (MpAccount) UrlSign 

func (ma MpAccount) UrlSign(u string) (d H)

UrlSign 微信网页的网址签名

type PayCert added in v1.3.1 

type PayCert struct {
	SerialNo      string    `json:"serial_no"`
	EffectiveTime time.Time `json:"effective_time"`
	ExpireTime    time.Time `json:"expire_time"`
	// contains filtered or unexported fields
}

type PayCertManager added in v1.3.1 

type PayCertManager struct {
	// contains filtered or unexported fields
}

func NewPayCerManager added in v1.3.1 

func NewPayCerManager() PayCertManager

func (*PayCertManager) Add added in v1.3.1 

func (pcm *PayCertManager) Add(pc PayCert)

func (*PayCertManager) GetCert added in v1.3.1 

func (pcm *PayCertManager) GetCert() *x509.Certificate

func (*PayCertManager) GetCertBySerialNo added in v1.3.1 

func (pcm *PayCertManager) GetCertBySerialNo(no string) *x509.Certificate

func (*PayCertManager) GetSerialNo added in v1.3.1 

func (pcm *PayCertManager) GetSerialNo() string

func (*PayCertManager) IsEmpty added in v1.3.1 

func (pcm *PayCertManager) IsEmpty() bool

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.