后端金融科技【免费下载链接】gopay微信、支付宝、抖音、通联支付、拉卡拉、PayPal、Apple 的Go版本SDK。【极简、易用的聚合支付SDK】项目地址https://gitcode.com/gh_mirrors/go/gopay点击查看免费下载GoPay 是一个覆盖微信、支付宝、抖音、通联支付、拉卡拉、PayPal、Apple 等渠道的 Go 聚合支付 SDK。本指南围绕仓库内置的标准工作流.claude/skills/add-payment-interface/SKILL.md展开详细讲解为 GoPay 新增支付平台接口的五个标准步骤接口文档分析、接口代码实现、文档更新、版本记录与提交合入并以微信支付 V3「医保自费混合收款」三个接口在仓库中的真实落地实现作为贯穿全文的实战案例。读完本文你将掌握一套可直接套用的「新增支付接口」标准化流程并能结合源码逐行理解 GoPay v3 系列接口的请求签名、响应验签与错误处理约定。一、该 Skill 的适用场景什么时候激活add-payment-interface是 GoPay 仓库内置的 Agent 技能面向所有为项目新增或扩展支付能力的场景官方定义为Add new payment interfaces to GoPay project following standard workflow。以下四类情形会触发该工作流新增微信支付 V3 接口例如医保支付、智慧商圈等模块新增支付宝 V3 接口例如棋盘密云、商家商品上传等模块为其他支付平台抖音、通联、拉卡拉等新增接口为既有支付接口扩展新能力例如给某模块补充查询、撤销、退款类方法。从仓库结构看每个支付平台都是一个独立目录微信 V3 在 wechat/v3支付宝 V3 在 alipay/v3抖音在 douyin招商银行聚合支付在 cmbpay。新增接口时遵循的是同一套骨架因此这套工作流具有很强的可复用性。二、标准工作流总览整个流程被拆解为五个依次推进的步骤每步都有明确的文件落点分析接口文档—— 从官方文档中抽取完整的接口规格HTTP 方法、URL 路径、请求/响应参数实现接口代码—— 按项目约定补齐路径常量、数据模型与接口方法更新文档—— 在doc/wechat_v3.md或doc/alipay_v3.md附录登记新接口更新版本记录—— 递增根目录constant.go中的版本号并写入release_note.md变更日志提交变更—— 将涉及的全部文件纳入git add并做构建验证。下面按步骤深入每一步都结合仓库中真实存在的源码给出证据。三、Step 1分析接口文档目标从官方文档中提取完整、无歧义的接口规格。推荐的手段有两类优先使用WebFetch直接抓取官方文档页面若文档是交互式需要点击展开、切换 Tab则使用浏览器自动化工具mcp__browser-automation__*进行导航读取。需要抽取的三类关键信息信息维度说明示例HTTP 方法GET / POST / PUT / DELETE / PATCHPOSTURL 路径接口的完整请求路径注意路径参数占位符/v3/med-ins/orders请求参数参数名、类型、是否必填、含义说明mix_pay_type, order_type, appid, openid, ...响应参数参数名、类型、含义说明mix_trade_no, mix_pay_status, ...在分析阶段就产出结构化摘要能让后续编码与文档登记保持一致。以医保支付为例规范化的分析产物形如Interface: 医保自费混合收款下单 Method: POST Path: /v3/med-ins/orders Request: mix_pay_type, order_type, appid, openid, ... Response: mix_trade_no, mix_pay_status, ...仓库印证这一分析结果在源码中得到了逐字落实。微信 V3 的医保支付三个接口路径常量定义在 wechat/v3/constant.go与文档分析产物一一对应见下一节。四、Step 2实现接口代码这是整个流程的核心分三部分完成路径常量、数据模型、接口方法。4.1 添加 API 路径常量文件落点wechat/v3/constant.go或alipay/v3/constant.go。命名规范v3 模块名 动作名全小写驼峰。路径常量同时承担接口文档注释的职责注释里必须写明 HTTP 方法。以医保支付为例仓库中真实存在的常量wechat/v3/constant.go// 医保支付 v3MedInsOrder /v3/med-ins/orders // 医保自费混合收款下单 POST v3MedInsOrderQueryByMixNo /v3/med-ins/orders/mix-trade-no/%s // mix_trade_no 使用医保自费混合订单号查看下单结果 GET v3MedInsOrderQueryByOutNo /v3/med-ins/orders/out-trade-no/%s // out_trade_no 使用商户订单号查看下单结果 GET两个细节值得注意含路径参数的 URL 使用%s占位符如/v3/med-ins/orders/mix-trade-no/%s实际调用时通过fmt.Sprintf填充同文件顶部统一声明了方法名常量与请求头常量wechat/v3/constant.go如MethodGet、MethodPost、HeaderAuthorization、HeaderRequestID等新增接口直接复用即可不要手写字符串。4.2 定义数据模型文件落点新建或更新model_*.go如医保模块对应 wechat/v3/model_medins.go。每个接口需要两类结构响应包装结构XxxRsp与响应数据结构Xxx。响应包装结构的模板如下SKILL 规定的规范// Response wrapper type XxxRsp struct { Code int json:- SignInfo *SignInfo json:- Response *Xxx json:response,omitempty ErrResponse ErrResponse json:err_response,omitempty Error string json:- } // Response data type Xxx struct { Field1 string json:field1 // 字段说明 Field2 int json:field2 // 字段说明 // ... more fields }仓库中医保模块的落地实现wechat/v3/model_medins.go完全遵循该模板下单接口使用MedInsOrderRsp/MedInsOrder查询接口使用MedInsQueryOrderRsp/MedInsQueryOrder。每个响应结构体字段都带 JSON tag 与中文注释例如查询订单响应中的金额字段全部以「分」为单位TotalFee int json:total_fee // 总金额 MedInsGovFee int json:med_ins_gov_fee,omitempty // 医保统筹支付金额 MedInsSelfFee int json:med_ins_self_fee,omitempty // 医保个账支付金额 MedInsOtherFee int json:med_ins_other_fee,omitempty // 医保其他支付金额 MedInsCashFee int json:med_ins_cash_fee,omitempty // 医保结算后需自费金额 WechatPayCashFee int json:wechat_pay_cash_fee,omitempty // 实际微信支付金额模型设计上的约定必返回字段不加omitempty可选字段统一加omitempty保证 JSON 序列化的最小化嵌套结构如CashAddDetail []*CashDetail独立成类型放在文件底部布尔字段如MedInsTestEnv也按可选字段处理。4.3 实现接口方法文件落点新建或更新模块文件如医保模块为 wechat/v3/medins.go。方法命名V3 模块名 动作名例如V3MedInsOrder、V3MedInsOrderQueryByMixNo。标准实现骨架SKILL 规定的模式func (c *ClientV3) V3XxxMethod(ctx context.Context, bm gopay.BodyMap) (wxRsp *XxxRsp, err error) { // 1. Generate authorization authorization, err : c.authorization(MethodPost, v3ApiPath, bm) if err ! nil { return nil, err } // 2. Send request (use doProdPost for POST, doProdGet for GET) res, si, bs, err : c.doProdPost(ctx, bm, v3ApiPath, authorization) if err ! nil { return nil, err } // 3. Initialize response wxRsp XxxRsp{Code: Success, SignInfo: si, Response: new(Xxx)} if res.StatusCode ! http.StatusOK { wxRsp.Code res.StatusCode wxRsp.Error string(bs) _ js.UnmarshalBytes(bs, wxRsp.ErrResponse) return wxRsp, nil } // 4. Parse response if err json.Unmarshal(bs, wxRsp.Response); err ! nil { return nil, fmt.Errorf([%w]: %v, bytes: %s, gopay.UnmarshalErr, err, string(bs)) } // 5. Verify signature return wxRsp, c.verifySyncSign(si) }SKILL 明确列出的关键点POST 请求使用doProdPostGET 请求使用doProdGet路径参数用fmt.Sprintf格式化 URL每次调用都通过verifySyncSign完成响应验签。源码级印证仓库中V3MedInsOrderQueryByMixNo的真实实现wechat/v3/medins.go展示了路径参数的填充方式与 GET 调用形态func (c *ClientV3) V3MedInsOrderQueryByMixNo(ctx context.Context, mixTradeNo string) (wxRsp *MedInsQueryOrderRsp, err error) { uri : fmt.Sprintf(v3MedInsOrderQueryByMixNo, mixTradeNo) authorization, err : c.authorization(MethodGet, uri, nil) if err ! nil { return nil, err } res, si, bs, err : c.doProdGet(ctx, uri, authorization) // ... 其余处理与骨架一致 }请求签名Authorization是如何生成的authorization方法实现于 wechat/v3/sign.go它把 HTTP 方法、请求路径、时间戳、随机串与请求体拼成待签串用商户私钥做 RSA-SHA256 签名后组装为Authorization头_str : method \n path \n ts \n nonceStr \n jb \n sign, err : c.rsaSign(_str) return Authorization mchid c.Mchid ,nonce_str nonceStr ,timestamp ts ,serial_no c.SerialNo ,signature sign , nil其中Authorization WECHATPAY2-SHA256-RSA2048wechat/v3/constant.go。rsaSignwechat/v3/sign.go使用rsa.SignPKCS1v15crypto.SHA256对私钥签名。响应如何验签doProdPost/doProdGetwechat/v3/request.go在拿到响应后会从响应头收集Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Signature、Wechatpay-Serial连同响应体组装成SignInfo。verifySyncSignwechat/v3/sign.go再按时间戳\n随机串\n响应体\n拼串做 RSA 验签。重要前提verifySyncSign只有在客户端开启自动验签autoSign true时才会真正执行验签否则直接放行。开启方式是在初始化后调用client.AutoVerifySign()微信平台证书自动刷新或client.AutoVerifySignByPublicKey(...)微信支付公钥新商户推荐详见 wechat/v3/client.go。请求体 BodyMap入参统一使用gopay.BodyMap定义于 body_map.go它本质是map[string]any提供链式Set、SetBodyMap嵌套结构等方法最终通过bm.JsonBody()序列化为请求 JSON。微信 V3 的下单、查询接口都以此作为统一入参类型。五、Step 3更新文档文件落点doc/wechat_v3.md或doc/alipay_v3.md。位置约定追加到文档末尾的「附录」区按功能模块分组。格式规范* font color#07C160 size4Module Name/font * Interface description: client.V3MethodName() * Interface description: client.V3MethodName2()仓库印证医保支付在 doc/wechat_v3.md 附录中的登记与实际方法完全一致* font color#07C160 size4医保支付/font * 医保自费混合收款下单client.V3MedInsOrder() * 使用医保自费混合订单号查看下单结果client.V3MedInsOrderQueryByMixNo() * 使用商户订单号查看下单结果client.V3MedInsOrderQueryByOutNo()六、Step 4更新版本记录新接口必须同步变更版本信息共两处6.1 递增版本号文件落点根目录 constant.go其中维护着全局版本常量Version v1.5.123动作递增 patch 版本号例如v1.5.116→v1.5.117。仓库印证医保支付正是在 v1.5.116 基础上递增为 v1.5.117当前仓库版本已推进至 v1.5.123根目录 constant.go。6.2 更新发布记录文件落点根目录 release_note.md。动作在文件顶部新增最新版本小节。格式规范## 版本号v1.5.xxx * 修改记录 * 平台名新增 功能模块 相关接口。 * client.MethodName()接口说明。 * client.MethodName2()接口说明。仓库印证医保支付版本的发布记录release_note.md## 版本号v1.5.117 * 修改记录 * 微信v3新增 医保支付 相关接口。 * client.V3MedInsOrder()医保自费混合收款下单。 * client.V3MedInsOrderQueryByMixNo()使用医保自费混合订单号查看下单结果。 * client.V3MedInsOrderQueryByOutNo()使用商户订单号查看下单结果。七、Step 5提交变更目标把所有相关文件纳入暂存区并做构建验证。SKILL 给出的标准操作# Add all related files git add constant.go git add release_note.md git add doc/wechat_v3.md # or corresponding platform doc git add wechat/v3/constant.go # or corresponding platform git add wechat/v3/new_file.go git add wechat/v3/model_new_file.go # Check status git status # Add any linter-formatted files git add formatted_files提交前务必执行编译验证确保代码可构建SKILL 质量清单中的第一条go build ./wechat/v3/...八、完整实战案例微信支付 V3 医保支付SKILL 以「微信支付 V3 医保自费混合收款」作为完整示例该案例在仓库中已真实合入是验证整个工作流的最佳样本。识别出的接口对应微信官方医保支付文档创建医保订单 ——POST /v3/med-ins/orders按混合订单号查询 ——GET /v3/med-ins/orders/mix-trade-no/{mix_trade_no}按商户订单号查询 ——GET /v3/med-ins/orders/out-trade-no/{out_trade_no}实际修改的文件清单与仓库现状一一对应文件变更内容根目录 constant.go版本号递增至 v1.5.117release_note.md新增 v1.5.117 变更日志doc/wechat_v3.md附录新增「医保支付」分组wechat/v3/constant.go新增 3 个接口路径常量wechat/v3/medins.go新建文件含 3 个方法wechat/v3/model_medins.go新建文件含响应结构体调用方式结合 doc/wechat_v3.md 的初始化说明与源码整理先初始化客户端并开启自动验签然后直接调用方法。下单接口以gopay.BodyMap传入业务参数查询接口以订单号作为路径参数传入// 1. 初始化客户端mchid / serialNo / apiV3Key / privateKey 取自商户平台 client, err : wechat.NewClientV3(MchId, SerialNo, APIv3Key, PrivateKey) if err ! nil { xlog.Error(err) return } // 2. 开启自动验签二选一微信支付公钥 或 微信平台证书 err client.AutoVerifySignByPublicKey([]byte(微信支付公钥内容), 微信支付公钥ID不能删除 PUB_KEY_ID_ 前缀) if err ! nil { xlog.Error(err) return } // 3. 医保自费混合收款下单 bm : make(gopay.BodyMap) bm.Set(mix_pay_type, xxx). Set(order_type, xxx). Set(appid, xxx). Set(openid, xxx) // ... 其余业务字段 wxRsp, err : client.V3MedInsOrder(ctx, bm) if err ! nil { xlog.Error(err) return } if wxRsp.Code Success { xlog.Debugf(wxRsp: %#v, wxRsp.Response) } // 4. 查询下单结果按混合订单号 / 按商户订单号 queryRsp, err : client.V3MedInsOrderQueryByMixNo(ctx, mixTradeNo) // queryRsp, err : client.V3MedInsOrderQueryByOutNo(ctx, outTradeNo)查询响应中的MedInsQueryOrder结构wechat/v3/model_medins.go完整覆盖了医保支付场景的金额拆分信息MedInsGovFee医保统筹支付、MedInsSelfFee医保个账支付、MedInsOtherFee医保其他支付、MedInsCashFee医保结算后需自费金额与WechatPayCashFee实际微信支付金额可以直接据此做业务侧的对账与展示。九、质量检查清单SKILL 要求每完成一个接口合入前逐项核对这是保障新增代码与既有风格一致的关键代码可编译通过go build ./wechat/v3/...所有 API 路径均已加入路径常量数据模型覆盖官方文档的全部字段方法实现遵循既有实现模式骨架一致错误处理完整含非 200 状态码与gopay.UnmarshalErr包装包含响应验签verifySyncSignAPI 文档已更新doc/wechat_v3.md附录版本号已递增根目录constant.go发布记录已更新release_note.md所有文件已纳入暂存区十、参考文件速查新增支付接口时优先阅读以下既有实现作为范本路径常量wechat/v3/constant.go、alipay/v3/constant.go数据模型wechat/v3/model_*.go、alipay/v3/model_*.go接口实现wechat/v3/medins.go 等模块文件、alipay/v3 目录请求与签名底层wechat/v3/request.go、wechat/v3/sign.go、body_map.go文档登记doc/wechat_v3.md、doc/alipay_v3.md版本记录根目录 constant.go、release_note.md十一、工具链速查该工作流依赖的工具组合SKILL 原文WebFetch—— 抓取官方文档内容Browser automation—— 导航交互式文档页面Read—— 参考仓库既有实现Write/Edit—— 创建或修改代码文件Bash—— 执行 git 命令与构建验证go build。这套「分析 → 编码 → 文档 → 版本 → 提交」的闭环保证了 GoPay 每次新增支付能力都能保持路径常量、模型、方法、文档与发布记录五处信息的一致性——新增接口时只要照着 wechat/v3/medins.go 这类既有实现依样实现就能以最小成本、最低出错率接入新的支付平台能力。赞分享后端金融科技【免费下载链接】gopay微信、支付宝、抖音、通联支付、拉卡拉、PayPal、Apple 的Go版本SDK。【极简、易用的聚合支付SDK】项目地址https://gitcode.com/gh_mirrors/go/gopay点击查看免费下载相关推荐GoPay项目微信支付V2接口开发指南GoPay项目微信支付V2接口开发指南 前言 在移动支付领域微信支付是开发者常用的支付方式之一。GoPay项目提供了简洁易用的微信支付V2接口封装帮助Go开后端金融科技uni-app支付对接终极指南微信支付宝支付统一接口uni app支付对接终极指南微信支付宝支付统一接口 想要在uni app项目中快速实现支付功能本文将为您详细介绍uni app的支付对接方案让您轻松搞定示例工程前端移动开发跨平台上一篇web-editor高级技巧自定义配置与扩展功能全解析下一篇Motion MotionValue 派生图统一设计mark-dirty / pull-compute 惰性计算架构解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考