feat: 微信小程序-小程序链接 (#833)

* feat: 微信小程序-小程序链接 * feat: 微信小程序-小程序链接
2026-02-04 12:52:27 +08:00 · 2025-05-01 10:19:19 +08:00
parent 2dfd2ff608
commit dd43b7baa3
3 changed files with 96 additions and 40 deletions
--- a/miniprogram/urllink/query.go
+++ b/miniprogram/urllink/query.go
@@ -6,7 +6,13 @@ import (
 	"github.com/silenceper/wechat/v2/util"
 )

-const queryURL = "https://api.weixin.qq.com/wxa/query_urllink"
+const queryURL = "https://api.weixin.qq.com/wxa/query_urllink?access_token=%s"
+
+// ULQueryRequest 查询加密URLLink请求
+type ULQueryRequest struct {
+	URLLink   string `json:"url_link"`
+	QueryType int    `json:"query_type"`
+}

 // ULQueryResult 返回的结果
 // https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/url-link/urllink.query.html 返回值
@@ -28,25 +34,35 @@ type ULQueryResult struct {
 			ResourceAppid string `json:"resource_appid"`
 		} `json:"cloud_base"`
 	} `json:"url_link_info"`
-	VisitOpenid string `json:"visit_openid"`
+	VisitOpenid string    `json:"visit_openid"`
+	QuotaInfo   QuotaInfo `json:"quota_info"`
+}
+
+// QuotaInfo quota 配置
+type QuotaInfo struct {
+	RemainVisitQuota int64 `json:"remain_visit_quota"`
 }

 // Query 查询小程序 url_link 配置。
 func (u *URLLink) Query(urlLink string) (*ULQueryResult, error) {
-	accessToken, err := u.GetAccessToken()
-	if err != nil {
-		return nil, err
-	}
-
-	uri := fmt.Sprintf("%s?access_token=%s", queryURL, accessToken)
-	response, err := util.PostJSON(uri, map[string]string{"url_link": urlLink})
-	if err != nil {
-		return nil, err
-	}
-	var resp ULQueryResult
-	err = util.DecodeWithError(response, &resp, "URLLink.Query")
-	if err != nil {
-		return nil, err
-	}
-	return &resp, nil
+	return u.QueryWithType(&ULQueryRequest{URLLink: urlLink})
+}
+
+// QueryWithType 查询加密URLLink
+// see https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/qrcode-link/url-link/queryUrlLink.html
+func (u *URLLink) QueryWithType(req *ULQueryRequest) (*ULQueryResult, error) {
+	var (
+		accessToken string
+		err         error
+	)
+	if accessToken, err = u.GetAccessToken(); err != nil {
+		return nil, err
+	}
+	var response []byte
+	if response, err = util.PostJSON(fmt.Sprintf(queryURL, accessToken), req); err != nil {
+		return nil, err
+	}
+	result := &ULQueryResult{}
+	err = util.DecodeWithError(response, result, "URLLink.Query")
+	return result, err
 }
--- a/miniprogram/urlscheme/query.go
+++ b/miniprogram/urlscheme/query.go
@@ -14,7 +14,8 @@ const (
 // https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/url-scheme/urlscheme.query.html#参数
 type QueryScheme struct {
 	// 小程序 scheme 码
-	Scheme string `json:"scheme"`
+	Scheme    string `json:"scheme"`
+	QueryType int    `json:"query_type"`
 }

 // SchemeInfo scheme 配置
@@ -33,34 +34,47 @@ type SchemeInfo struct {
 	EnvVersion EnvVersion `json:"env_version"`
 }

-// resQueryScheme 返回结构体
+// QuotaInfo quota 配置
+type QuotaInfo struct {
+	RemainVisitQuota int64 `json:"remain_visit_quota"`
+}
+
+// ResQueryScheme 返回结构体
 // https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/url-scheme/urlscheme.query.html#参数
-type resQueryScheme struct {
+type ResQueryScheme struct {
 	// 通用错误
 	util.CommonError
 	// scheme 配置
 	SchemeInfo SchemeInfo `json:"scheme_info"`
 	// 访问该链接的openid，没有用户访问过则为空字符串
-	VisitOpenid string `json:"visit_openid"`
+	VisitOpenid string    `json:"visit_openid"`
+	QuotaInfo   QuotaInfo `json:"quota_info"`
 }

 // QueryScheme 查询小程序 scheme 码
 func (u *URLScheme) QueryScheme(querySchemeParams QueryScheme) (schemeInfo SchemeInfo, visitOpenid string, err error) {
-	var accessToken string
-	accessToken, err = u.GetAccessToken()
+	res, err := u.QuerySchemeWithRes(querySchemeParams)
 	if err != nil {
 		return
 	}
-
-	urlStr := fmt.Sprintf(querySchemeURL, accessToken)
-	var response []byte
-	response, err = util.PostJSON(urlStr, querySchemeParams)
-	if err != nil {
-		return
-	}
-
-	// 使用通用方法返回错误
-	var res resQueryScheme
-	err = util.DecodeWithError(response, &res, "QueryScheme")
 	return res.SchemeInfo, res.VisitOpenid, err
 }
+
+// QuerySchemeWithRes 查询scheme码
+// see https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/qrcode-link/url-scheme/queryScheme.html
+func (u *URLScheme) QuerySchemeWithRes(req QueryScheme) (*ResQueryScheme, error) {
+	var (
+		accessToken string
+		err         error
+	)
+	if accessToken, err = u.GetAccessToken(); err != nil {
+		return nil, err
+	}
+	var response []byte
+	if response, err = util.PostJSON(fmt.Sprintf(querySchemeURL, accessToken), req); err != nil {
+		return nil, err
+	}
+	result := &ResQueryScheme{}
+	err = util.DecodeWithError(response, result, "QueryScheme")
+	return result, err
+}
--- a/miniprogram/urlscheme/urlscheme.go
+++ b/miniprogram/urlscheme/urlscheme.go
@@ -17,7 +17,12 @@ func NewURLScheme(ctx *context.Context) *URLScheme {
 	return &URLScheme{Context: ctx}
 }

-const generateURL = "https://api.weixin.qq.com/wxa/generatescheme"
+const (
+	// generateURL 获取加密scheme码
+	generateURL = "https://api.weixin.qq.com/wxa/generatescheme"
+	// generateNFCURL 获取 NFC 的小程序 scheme
+	generateNFCURL = "https://api.weixin.qq.com/wxa/generatenfcscheme?access_token=%s"
+)

 // TExpireType 失效类型 (指定时间戳/指定间隔)
 type TExpireType int
@@ -50,11 +55,13 @@ type JumpWxa struct {
 // USParams 请求参数
 // https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/url-scheme/urlscheme.generate.html#请求参数
 type USParams struct {
-	JumpWxa        *JumpWxa    `json:"jump_wxa"`
-	ExpireType     TExpireType `json:"expire_type"`
-	ExpireTime     int64       `json:"expire_time"`
-	ExpireInterval int         `json:"expire_interval"`
+	JumpWxa        *JumpWxa    `json:"jump_wxa,omitempty"`
+	ExpireType     TExpireType `json:"expire_type,omitempty"`
+	ExpireTime     int64       `json:"expire_time,omitempty"`
+	ExpireInterval int         `json:"expire_interval,omitempty"`
 	IsExpire       bool        `json:"is_expire,omitempty"`
+	ModelID        string      `json:"model_id,omitempty"`
+	Sn             string      `json:"sn,omitempty"`
 }

 // USResult 返回的结果
@@ -81,3 +88,22 @@ func (u *URLScheme) Generate(params *USParams) (string, error) {
 	err = util.DecodeWithError(response, &resp, "URLScheme.Generate")
 	return resp.OpenLink, err
 }
+
+// GenerateNFC 获取 NFC 的小程序 scheme
+// see https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/qrcode-link/url-scheme/generateNFCScheme.html
+func (u *URLScheme) GenerateNFC(params *USParams) (string, error) {
+	var (
+		accessToken string
+		err         error
+	)
+	if accessToken, err = u.GetAccessToken(); err != nil {
+		return "", err
+	}
+	var response []byte
+	if response, err = util.PostJSON(fmt.Sprintf(generateNFCURL, accessToken), params); err != nil {
+		return "", err
+	}
+	result := &USResult{}
+	err = util.DecodeWithError(response, result, "URLScheme.GenerateNFC")
+	return result.OpenLink, err
+}