silenceper/wechat v2 微信小程序 Go SDK 接入指南：配置、数据分析与虚拟支付实战-平芜编程栈

网络安全

【免费下载链接】sliver

Adversary Emulation Framework

项目地址：https://gitcode.com/gh_mirrors/sl/sliver

本指南以仓库中 vendored 的github.com/silenceper/wechat/v2微信开发框架的 miniprogram 包文档为核心，系统讲解如何在 Go 服务中初始化微信小程序实例、理解Config各字段含义、调用数据分析 API，并完整跑通小程序虚拟支付（米大师 xpay）的余额查询与签名流程。读完本文，你将能够基于该 SDK 快速搭建小程序后端接入层，并掌握虚拟支付场景下AppKey、OfferID、session_key与 HMAC-SHA256 签名的配合方式。

一、miniprogram 包定位与包说明

github.com/silenceper/wechat/v2是一个覆盖微信公众号、小程序、企业微信、微信支付与开放平台的 Go SDK，统一入口为wechat.NewWechat()（见 wechat.go）。其中miniprogram子包封装了微信小程序服务端全部常用 OpenAPI，按业务域拆分为多个子包：

analysis：数据分析相关 API（留存、趋势、画像、访问分布、页面访问、性能数据等）
auth：登录 / 用户信息相关接口（code2session 等）
business：业务接口（含手机号快速验证组件）
content、security：内容安全接口
encryptor：小程序数据加解密
express：微信物流服务
message：客服消息、模板消息、动态消息与消息推送接收器
minidrama：小程序娱乐微短剧
ocr：OCR 接口
operation：小程序运维中心
order：发货信息管理服务
privacy：小程序隐私协议相关 API
qrcode：小程序码相关 API
redpacketcover：微信红包封面 API
riskcontrol：安全风控接口
shortlink：小程序短链接口
subscribe：订阅消息
tcb：小程序云开发（云函数、云数据库、云文件）
urllink：URL Link 接口
urlscheme：URL Scheme 接口
virtualpayment：小程序虚拟支付（米大师 xpay）
werun：微信运动接口
openapi：OpenAPI 管理接口（位于internal/openapi）

所有子模块统一通过 MiniProgram 实例上的GetXxx()方法获得，例如GetAnalysis()、GetAuth()、GetVirtualPayment()、GetQRCode()、GetTcb()等，每个模块共享同一个*context.Context，从而复用统一的access_token获取与缓存机制。

二、快速入门：三行代码初始化小程序实例

文档给出的最小可运行示例（miniprogram/README.md）：

wc := wechat.NewWechat() memory := cache.NewMemory() cfg := &miniConfig.Config{ AppID: "xxx", AppSecret: "xxx", Cache: memory, } miniprogram := wc.GetMiniProgram(cfg) miniprogram.GetAnalysis().GetAnalysisDailyRetain()

拆解来看，初始化链路分为四步：

创建 SDK 入口：wechat.NewWechat()返回*Wechat，可通过SetCache或SetHTTPClient做全局配置；
准备缓存：cache.NewMemory()创建内存缓存。SDK 需要缓存access_token（默认 7200 秒有效期）以避免每次请求都重新换取，cache 包还提供cache.NewRedis(...)、cache.NewMemcache(...)等实现，生产环境建议使用 Redis 以便多实例共享令牌；
组装配置：构造miniConfig.Config，核心必填项为AppID、AppSecret；
获取实例并调用 API：wc.GetMiniProgram(cfg)返回*miniprogram.MiniProgram，再通过GetAnalysis()等入口调用具体业务方法。

注意：文档示例中GetAnalysisDailyRetain()省略了参数，实际源码中该方法签名是GetAnalysisDailyRetain(beginDate, endDate string)（见 analysis.go），需要传入形如20230801的起止日期。示例仅为演示调用链，真实使用时务必补全日期参数。

从源码看，GetMiniProgram在cfg.Cache == nil时会自动回退使用Wechat全局设置的 cache（wechat.go），所以两种配置方式都合法。随后 NewMiniProgram 会依据cfg.UseStableAK选择稳定的access_token处理器还是默认处理器，并将Config与令牌处理器注入context.Context。

三、Config 配置项全解

miniprogram/config包的Config结构体（config.go）完整字段如下：

字段	JSON 标签	说明
`AppID`	`app_id`	小程序 AppID，必填
`AppSecret`	`app_secret`	小程序 AppSecret，必填
`AppKey`	`app_key`	虚拟支付米大师应用密钥，仅虚拟支付场景需要
`OfferID`	`offer_id`	米大师侧申请的 offerId，仅虚拟支付场景需要
`Token`	`token`	消息校验 Token（接收微信服务器推送时用于签名校验）
`EncodingAESKey`	`encoding_aes_key`	消息加解密密钥
`Cache`	—	令牌缓存实现，`cache.Cache`接口
`UseStableAK`	—	是否使用稳定版`access_token`

要点：

AppID/AppSecret是几乎所有接口的前提，SDK 据此自动换取access_token；
Token与EncodingAESKey服务于被动消息接收与加解密（配合GetMessageReceiver()使用），普通主动调用 API 不需要；
UseStableAK = true时走稳定版令牌（credential.NewStableAccessToken），适合对令牌稳定性要求高的场景；默认为false时使用credential.NewDefaultAccessToken；
Cache若未在 Config 中设置，GetMiniProgram会自动回退到Wechat全局 cache（为nil时可能导致令牌管理异常，务必配置其一）。

四、小程序虚拟支付（米大师 xpay）接入

虚拟支付是本文档重点示例场景，适用于小游戏、短剧等安卓端道具直购、代币充值的行业能力。与普通 API 不同，虚拟支付必须额外传入AppKey和OfferID，且依赖用户态session_key做签名。

4.1 初始化：传入 AppKey / OfferID 并配置 Redis 缓存

文档示例：

wc := wechat.NewWechat() miniprogram := wc.GetMiniProgram(&miniConfig.Config{ AppID: "xxx", AppSecret: "xxx", AppKey: "xxx", OfferID: "xxx", Cache: cache.NewRedis(&redis.Options{ Addr: "", }), }) virtualPayment := miniprogram.GetVirtualPayment() virtualPayment.SetSessionKey("xxx")

这里值得说明两点设计：

AppKey与OfferID的用途：从 virtualpayment.go 可以看到，PaySign使用AppKey对url + "&" + data做hmacSha256，是**支付签名（pay_sig）**的密钥；而OfferID则作为业务参数出现在SignData（下单/充值的offerId字段）中，标识米大师侧的应用。二者缺一不可；
Redis 缓存的价值：虚拟支付接口同样依赖access_token，多实例部署时用cache.NewRedis(&redis.Options{Addr: "..."})共享令牌缓存，避免令牌过期抖动；内存缓存仅适合单机或测试环境。

获取VirtualPayment实例后，必须先调用SetSessionKey(sessionKey)注入用户态会话密钥（来自登录流程的session_key）。从源码看（virtualpayment.go#L458-L463），Signature（用户态签名）使用sessionKey对数据做 HMAC-SHA256，若未设置会直接返回sessionKey is empty错误。

4.2 查询用户余额（QueryUserBalance）

文档示例：

var ( res *virtualPayment.QueryUserBalanceResponse err error ) if res, err = virtualPayment.QueryUserBalance(context.TODO(), &virtualPayment.QueryUserBalanceRequest{ OpenID: "xxx", Env: virtualPayment.EnvProduction, UserIP: "xxx", }); err != nil { panic(err) }

请求参数QueryUserBalanceRequest（见 domain.go）包含：

OpenID：用户 openid（必填）；
Env：环境，EnvProduction = 0（正式环境）或EnvSandbox = 1（沙箱环境），常量定义在 constant.go；
UserIP：用户 IP，例如1.1.1.1。

响应QueryUserBalanceResponse提供代币余额明细：Balance（代币总余额，含有价与赠送部分）、PresentBalance（赠送账户余额）、SumSave（累计有价充值）、SumCost（历史总消耗）、FirstSaveFlag（是否满足首充活动标记，0 不满足 / 1 满足）等，可用于游戏内代币资产的展示与校验。

从实现上看，QueryUserBalance属于“需要用户态签名 + 支付签名”的接口（requestAddress中落入PaySignature分支），会依次完成PaySign（AppKey 签名）与Signature（sessionKey 签名），并把access_token、pay_sig、signature拼接到https://api.weixin.qq.com/xpay/query_user_balance请求上（见 constant.go#L75-L120 的接口路径常量与 virtualpayment.go#L476-L515 的 URL 组装逻辑）。

4.3 虚拟支付能力全景与签名规则

除余额查询外，VirtualPayment还封装了完整的米大师 xpay 服务器 API（全部定义在 domain.go）：

方法	对应接口路径	签名要求	用途
`QueryUserBalance`	`/xpay/query_user_balance`	支付签名 + 用户态签名	查询用户代币余额
`CurrencyPay`	`/xpay/currency_pay`	支付签名 + 用户态签名	扣减代币（代币支付）
`CancelCurrencyPay`	`/xpay/cancel_currency_pay`	支付签名 + 用户态签名	代币支付退款（逆操作）
`PresentCurrency`	`/xpay/present_currency`	支付签名 + 用户态签名	赠送代币
`QueryOrder`	`/xpay/query_order`	支付签名	查询现金单订单
`NotifyProvideGoods`	`/xpay/notify_provide_goods`	支付签名	异常情况下手动通知发货
`DownloadBill`	`/xpay/download_bill`	支付签名	下载交易账单
`RefundOrder`	`/xpay/refund_order`	支付签名	现金单退款
`CreateWithdrawOrder`	`/xpay/create_withdraw_order`	支付签名	创建提现单
`QueryWithdrawOrder`	`/xpay/query_withdraw_order`	支付签名	查询提现单
`StartUploadGoods`/`QueryUploadGoods`	`/xpay/start_upload_goods`等	支付签名	批量上传道具
`StartPublishGoods`/`QueryPublishGoods`	`/xpay/start_publish_goods`等	支付签名	批量发布道具

签名规则要点（源码 virtualpayment.go#L442-L474）：

支付签名 pay_sig：HMAC-SHA256(AppKey, url + "&" + data)，其中url为接口路径，data为请求体 JSON 字符串；
用户态签名 signature：HMAC-SHA256(sessionKey, data)，仅在需要校验用户身份的接口（余额查询、代币支付/退款/赠送）上使用；
两处签名均以十六进制字符串输出，最终以pay_sig、signature查询参数随access_token一起拼入请求 URL。

错误码速查（constant.go#L29-L54）也值得接入时对照处理：

0：成功；
268490001：openid 错误；
268490002：请求参数字段错误（看 errmsg）；
268490003：签名错误；
268490004：重复操作（赠送 / 代币支付接口表示之前操作已成功，可视为幂等成功）；
268490005：订单已通过cancel_currency_pay退款，不支持再退款；
268490006：代币退款 / 支付金额不足；
268490007：图片或文字存在敏感内容；
268490008：代币未发布，不允许代币操作；
268490009：用户session_key不存在或已过期，需重新登录；
268490011：账单数据生成中，稍后重试。

另外，domain.go中SignData（下单签名数据）对业务侧约束明显：OutTradeNo要求 8–32 字符、仅限数字/大小写字母/_-|*@且不能以下划线开头；GoodsPrice以“分”为单位用于校验与后台道具价格一致，避免价格投诉；Mode支持short_series_goods（道具直购）与short_series_coin（代币充值）两种模式。这些字段在对接客户端下单逻辑时需要严格对齐。

五、数据分析 API 的完整调用面

文档“包说明”中特别点名了analysis子包，实际源码（analysis.go）暴露的分析能力远不止日留存一项，全部方法均接受begin_date/end_date（yyyymmdd格式）：

GetAnalysisDailyRetain/GetAnalysisWeeklyRetain/GetAnalysisMonthlyRetain：日 / 周 / 月留存，返回ResAnalysisRetain，含VisitUVNew（新增用户留存）与VisitUV（活跃用户留存）两个[]RetainItem序列；
GetAnalysisDailySummary：访问概况，返回累计用户数、转发次数（SharePV）、转发人数（ShareUV）；
GetAnalysisDailyVisitTrend/GetAnalysisWeeklyVisitTrend/GetAnalysisMonthlyVisitTrend：访问趋势，含打开次数、访问 PV/UV、新用户数、人均/次均停留时长、平均访问深度；
GetAnalysisUserPortrait：新 / 活跃用户画像（省份、城市、性别、终端、机型、年龄）；
GetAnalysisVisitDistribution：访问来源分布；
GetAnalysisVisitPage：页面访问数据（访问次数、停留、进入/退出页、转发）；
GetPerformanceData：小程序性能数据（需构造GetPerformanceDataRequest，包含Module、时间区间Time与Params筛选条件）。

实现上，这些方法统一走fetchData：先从context.Context的GetAccessToken()取令牌，拼入https://api.weixin.qq.com/datacube/...系列 URL，POST JSON 后解析并校验ErrCode（非 0 时包装为带 errcode/errmsg 的 error）。该封装对所有调用方透明，业务侧只需关注入参日期与结果结构体字段即可。

六、从 README 到生产：接入清单与常见问题

结合文档与源码，落地一个可运行的小程序后端模块需要确认以下几点：

令牌缓存必须就绪：Config.Cache或wechat.SetCache(...)至少配置其一，生产多实例建议cache.NewRedis；否则GetAccessToken缺少存储后端会导致令牌获取失败。
普通接口只需AppID+AppSecret，数据分析、二维码、订阅消息等均在此之上工作；虚拟支付必须补全AppKey、OfferID，并在每次会话中先SetSessionKey，三者任一缺失都会在签名阶段直接报错（如appKey is empty、sessionKey is empty）。
区分环境与幂等：Env使用EnvProduction/EnvSandbox常量；PresentCurrency等接口遇到268490004（重复操作）应按成功处理，避免误判为失败而重复赠送。
金额单位统一为“分”：SignData.GoodsPrice、RefundOrderRequest.RefundFee、UploadItem.Price等字段均为分，账单下载接口的金额同样以分为单位，换算失误是虚拟支付对接最常见的坑。
发货回调走消息推送：正常发货成功通过xpay_goods_deliver_notify事件推送（对应domain.go中的AsyncXPayGoodsDeliverNotifyRequest结构，可用GetMessageReceiver()接收解析），NotifyProvideGoods仅在推送异常时作为兜底手动置为已发货。

综上，miniprogram包通过统一的MiniProgram门面 + 子模块GetXxx()方法，把微信小程序服务端 API 的令牌管理、签名与错误处理收敛到一处；虚拟支付部分则完整复刻了米大师 xpay 的签名与调用约定。接入时以本指南的配置清单与签名规则为准，即可快速在 Go 后端中稳定跑通数据分析与虚拟支付两大核心场景。