From b601b557f90053979412d152d8e3f836c7913513 Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Sun, 21 Dec 2025 21:57:27 +0800
Subject: [PATCH] =?UTF-8?q?:art:=20=E6=94=AF=E4=BB=98=E5=9B=9E=E8=B0=83?=
 =?UTF-8?q?=E7=BB=93=E6=9E=9C=E8=A7=A3=E6=9E=90=E6=97=B6=E6=8F=90=E4=BE=9B?=
 =?UTF-8?q?=E5=BF=85=E8=A6=81=E7=9A=84=E6=A3=80=E6=B5=8B=E6=8A=A5=E9=94=99?=
 =?UTF-8?q?=E5=88=A4=E6=96=AD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../service/impl/BaseWxPayServiceImpl.java    |  7 ++++
 .../impl/BaseWxPayServiceImplTest.java        | 36 +++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/weixin-java-pay/src/main/java/com/github/binarywang/wxpay/service/impl/BaseWxPayServiceImpl.java b/weixin-java-pay/src/main/java/com/github/binarywang/wxpay/service/impl/BaseWxPayServiceImpl.java
index 484e19154..2e896cda7 100644
--- a/weixin-java-pay/src/main/java/com/github/binarywang/wxpay/service/impl/BaseWxPayServiceImpl.java
+++ b/weixin-java-pay/src/main/java/com/github/binarywang/wxpay/service/impl/BaseWxPayServiceImpl.java
@@ -344,6 +344,13 @@ public abstract class BaseWxPayServiceImpl implements WxPayService {
   public WxPayOrderNotifyResult parseOrderNotifyResult(String xmlData, String signType) throws WxPayException {
     try {
       log.debug("微信支付异步通知请求参数：{}", xmlData);
+      
+      // 检测数据格式并给出适当的处理建议
+      if (xmlData != null && xmlData.trim().startsWith("{")) {
+        throw new WxPayException("检测到V3版本的JSON格式通知数据，请使用parseOrderNotifyV3Result方法解析。" +
+            " V3 API需要传入SignatureHeader参数进行签名验证。");
+      }
+      
       WxPayOrderNotifyResult result = WxPayOrderNotifyResult.fromXML(xmlData);
       if (signType == null) {
         this.switchover(result.getMchId(), result.getAppid());
diff --git a/weixin-java-pay/src/test/java/com/github/binarywang/wxpay/service/impl/BaseWxPayServiceImplTest.java b/weixin-java-pay/src/test/java/com/github/binarywang/wxpay/service/impl/BaseWxPayServiceImplTest.java
index bd24f188d..7dff396de 100644
--- a/weixin-java-pay/src/test/java/com/github/binarywang/wxpay/service/impl/BaseWxPayServiceImplTest.java
+++ b/weixin-java-pay/src/test/java/com/github/binarywang/wxpay/service/impl/BaseWxPayServiceImplTest.java
@@ -627,6 +627,42 @@ public class BaseWxPayServiceImplTest {
 
   }
 
+  /**
+   * Test parse order notify result with JSON format should give helpful error.
+   * 测试当传入V3版本的JSON格式通知数据时，应该抛出清晰的错误提示
+   *
+   * @throws Exception the exception
+   */
+  @Test
+  public void testParseOrderNotifyResultWithJsonShouldGiveHelpfulError() throws Exception {
+    String jsonString = "{\n" +
+      "    \"id\": \"EV-2018022511223320873\",\n" +
+      "    \"create_time\": \"2015-05-20T13:29:35+08:00\",\n" +
+      "    \"resource_type\": \"encrypt-resource\",\n" +
+      "    \"event_type\": \"TRANSACTION.SUCCESS\",\n" +
+      "    \"summary\": \"支付成功\",\n" +
+      "    \"resource\": {\n" +
+      "        \"algorithm\": \"AEAD_AES_256_GCM\",\n" +
+      "        \"ciphertext\": \"test\",\n" +
+      "        \"associated_data\": \"transaction\",\n" +
+      "        \"nonce\": \"test\"\n" +
+      "    }\n" +
+      "}";
+
+    try {
+      this.payService.parseOrderNotifyResult(jsonString);
+      fail("Expected WxPayException for JSON input");
+    } catch (WxPayException e) {
+      // 验证错误消息包含V3版本和parseOrderNotifyV3Result方法的指导信息
+      String message = e.getMessage();
+      assertTrue(message.contains("V3版本"), "错误消息应包含'V3版本'");
+      assertTrue(message.contains("JSON格式"), "错误消息应包含'JSON格式'");
+      assertTrue(message.contains("parseOrderNotifyV3Result"), "错误消息应包含'parseOrderNotifyV3Result'方法名");
+      assertTrue(message.contains("SignatureHeader"), "错误消息应包含'SignatureHeader'");
+      log.info("JSON格式检测正常，错误提示: {}", message);
+    }
+  }
+
   /**
    * Test get wx api data.
    *