wechatpay-apache-httpclient实战教程：从环境搭建到JSAPI下单完整流程

wechatpay-apache-httpclient实战教程：从环境搭建到JSAPI下单完整流程

【免费下载链接】wechatpay-apache-httpclient微信支付 APIv3 Apache HttpClient装饰器（decorator）项目地址: https://gitcode.com/gh_mirrors/we/wechatpay-apache-httpclient

wechatpay-apache-httpclient是微信支付APIv3的Apache HttpClient装饰器，能帮助开发者自动处理请求签名生成和应答签名验证，轻松对接微信支付接口。本文将带你从环境搭建开始，逐步掌握使用该工具实现JSAPI下单的完整流程。

一、环境准备与安装

1.1 环境要求

使用wechatpay-apache-httpclient需要满足以下环境要求：

• Java 1.8及以上版本
• Apache HttpClient相关依赖

1.2 安装方式

Gradle安装

在项目的build.gradle文件中添加以下依赖：

implementation 'com.github.wechatpay-apiv3:wechatpay-apache-httpclient:0.5.0'

Maven安装

在项目的pom.xml文件中添加以下依赖：

<dependency> <groupId>com.github.wechatpay-apiv3</groupId> <artifactId>wechatpay-apache-httpclient</artifactId> <version>0.5.0</version> </dependency>

二、核心概念与参数说明

2.1 必要参数解释

使用wechatpay-apache-httpclient需要准备以下核心参数：

• merchantId：商户号
• merchantSerialNumber：商户API证书的证书序列号
• merchantPrivateKey：商户API私钥
• wechatPayCertificates：微信支付平台证书列表

2.2 密钥与证书获取

• 商户API私钥：申请商户API证书时生成，保存在本地证书文件夹的apiclient_key.pem文件中
• 商户API证书序列号：可在证书文件中查看，具体方法参考微信支付官方文档
• 微信支付平台证书：通过调用获取平台证书列表接口下载
• API v3密钥：在商户平台的【API安全】页面设置

三、快速上手：初始化HttpClient

3.1 基础初始化方法

如果你使用HttpClientBuilder或HttpClients#custom()构造HttpClient，可以直接替换为WechatPayHttpClientBuilder：

import com.wechat.pay.contrib.apache.httpclient.WechatPayHttpClientBuilder; //... WechatPayHttpClientBuilder builder = WechatPayHttpClientBuilder.create() .withMerchant(merchantId, merchantSerialNumber, merchantPrivateKey) .withWechatPay(wechatPayCertificates); // ... 可以通过builder设置各种参数配置HttpClient // 构造的HttpClient会自动处理签名和验签 CloseableHttpClient httpClient = builder.build(); // 像使用普通Apache HttpClient一样使用 CloseableHttpResponse response = httpClient.execute(...);

3.2 加载商户私钥

使用PemUtil.loadPrivateKey()方法加载商户私钥：

// 从文件加载私钥 PrivateKey merchantPrivateKey = PemUtil.loadPrivateKey( new FileInputStream("/path/to/apiclient_key.pem")); // 从字符串加载私钥 PrivateKey merchantPrivateKey = PemUtil.loadPrivateKey( new ByteArrayInputStream(privateKey.getBytes("utf-8")));

四、定时更新平台证书功能

4.1 功能介绍

版本≥0.4.0可使用CertificatesManager.getVerifier(merchantId)得到的验签器替代默认验签器，它会定时下载和更新商户对应的微信支付平台证书（默认下载间隔为UPDATE_INTERVAL_MINUTE）。

4.2 使用示例

// 获取证书管理器实例 certificatesManager = CertificatesManager.getInstance(); // 向证书管理器增加需要自动更新平台证书的商户信息 certificatesManager.putMerchant(merchantId, new WechatPay2Credentials(merchantId, new PrivateKeySigner(merchantSerialNumber, merchantPrivateKey)), apiV3Key.getBytes(StandardCharsets.UTF_8)); // ... 若有多个商户号，可继续调用putMerchant添加商户信息 // 从证书管理器中获取verifier verifier = certificatesManager.getVerifier(merchantId); WechatPayHttpClientBuilder builder = WechatPayHttpClientBuilder.create() .withMerchant(merchantId, merchantSerialNumber, merchantPrivateKey) .withValidator(new WechatPay2Validator(verifier)) // ... 配置HttpClient的其他参数 // 构造的HttpClient会自动处理签名和验签，并进行证书自动更新 CloseableHttpClient httpClient = builder.build();

五、JSAPI下单完整实现

5.1 接口说明

JSAPI下单接口用于创建微信支付订单，请求地址为：https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi

5.2 实现步骤

步骤1：构造请求参数

使用JSON库（如jackson-databind）构造请求参数：

HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi"); httpPost.addHeader("Accept", "application/json"); httpPost.addHeader("Content-type","application/json; charset=utf-8"); ByteArrayOutputStream bos = new ByteArrayOutputStream(); ObjectMapper objectMapper = new ObjectMapper(); ObjectNode rootNode = objectMapper.createObjectNode(); rootNode.put("mchid","1900009191") // 替换为你的商户号 .put("appid", "wxd678efh567hg6787") // 替换为你的appid .put("description", "Image形象店-深圳腾大-QQ公仔") // 订单描述 .put("notify_url", "https://www.weixin.qq.com/wxpay/pay.php") // 回调通知地址 .put("out_trade_no", "1217752501201407033233368018"); // 商户订单号 rootNode.putObject("amount") .put("total", 1); // 订单金额，单位为分 rootNode.putObject("payer") .put("openid", "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"); // 用户openid objectMapper.writeValue(bos, rootNode); httpPost.setEntity(new StringEntity(bos.toString("UTF-8"), "UTF-8"));

步骤2：发送请求并处理响应

使用初始化好的HttpClient发送请求：

CloseableHttpResponse response = httpClient.execute(httpPost); String bodyAsString = EntityUtils.toString(response.getEntity()); System.out.println(bodyAsString);

步骤3：解析返回结果

成功调用后，会返回包含prepay_id的结果，用于后续调起支付：

{ "prepay_id": "wx201410272009395522657a690389285100" }

六、订单查询与关闭

6.1 订单查询

通过订单号查询订单状态：

URIBuilder uriBuilder = new URIBuilder("https://api.mch.weixin.qq.com/v3/pay/transactions/id/4200000889202103303311396384?mchid=1230000109"); HttpGet httpGet = new HttpGet(uriBuilder.build()); httpGet.addHeader("Accept", "application/json"); CloseableHttpResponse response = httpClient.execute(httpGet); String bodyAsString = EntityUtils.toString(response.getEntity()); System.out.println(bodyAsString);

6.2 订单关闭

关闭未支付的订单：

HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/1217752501201407033233368018/close"); httpPost.addHeader("Accept", "application/json"); httpPost.addHeader("Content-type","application/json; charset=utf-8"); ByteArrayOutputStream bos = new ByteArrayOutputStream(); ObjectMapper objectMapper = new ObjectMapper(); ObjectNode rootNode = objectMapper.createObjectNode(); rootNode.put("mchid","1900009191"); // 商户号 objectMapper.writeValue(bos, rootNode); httpPost.setEntity(new StringEntity(bos.toString("UTF-8"), "UTF-8")); CloseableHttpResponse response = httpClient.execute(httpPost); String bodyAsString = EntityUtils.toString(response.getEntity()); System.out.println(bodyAsString);

七、回调通知处理

7.1 通知处理流程

版本≥0.4.2可使用NotificationHandler.parse(request)对回调通知进行验签和解密：

// 构建request，传入必要参数 NotificationRequest request = new NotificationRequest.Builder().withSerialNumber(wechatPaySerial) .withNonce(nonce) .withTimestamp(timestamp) .withSignature(signature) .withBody(body) .build(); NotificationHandler handler = new NotificationHandler(verifier, apiV3Key.getBytes(StandardCharsets.UTF_8)); // 验签和解析请求体 Notification notification = handler.parse(request); // 从notification中获取解密报文 System.out.println(notification.getDecryptData());

7.2 异常处理

parse(request)可能返回以下异常，建议对异常打日志或上报监控：

• ValidationException：验签失败，检查参数是否被篡改
• ParseException：解析失败，检查包体是否被篡改或AES密钥是否正确

八、常见问题解决

8.1 如何下载平台证书？

第一次下载平台证书时，可以临时"跳过"应答签名验证：

CloseableHttpClient httpClient = WechatPayHttpClientBuilder.create() .withMerchant(merchantId, merchantSerialNumber, merchantPrivateKey) .withValidator(response -> true) // 临时跳过验签，不要用在业务请求 .build();

注意：业务请求请使用标准的初始化流程，务必验证应答签名。

8.2 如何解决依赖冲突？

如果项目中出现Jackson等依赖冲突，可通过引入bom来统一版本：

Gradle

implementation(platform("com.fasterxml.jackson:jackson-bom:2.13.2.20220328"))

Maven

<parent> <groupId>com.fasterxml.jackson</groupId> <artifactId>jackson-bom</artifactId> <version>2.13.2.20220328</version> </parent>

九、总结

wechatpay-apache-httpclient极大简化了微信支付APIv3的对接流程，通过自动处理签名和验签，让开发者可以更专注于业务逻辑实现。本文从环境搭建到JSAPI下单完整流程进行了详细介绍，涵盖了初始化、证书管理、订单操作和回调处理等核心功能。

通过使用该工具，开发者可以快速、安全地集成微信支付功能，减少对接过程中的安全风险和开发成本。如需了解更多细节，可参考项目中的测试代码，如NotificationHandlerTest等。

希望本教程能帮助你顺利使用wechatpay-apache-httpclient实现微信支付功能！如有任何问题，欢迎通过项目issue进行反馈。

【免费下载链接】wechatpay-apache-httpclient微信支付 APIv3 Apache HttpClient装饰器（decorator）项目地址: https://gitcode.com/gh_mirrors/we/wechatpay-apache-httpclient