Java调用微信企业付款到银行卡时，签名验证失败如何排查？

Question

Java调用微信企业付款到银行卡时签名验证失败，常见原因有：① **参数参与签名顺序错误**——微信要求按字段名ASCII升序拼接（key=value&），且必须排除空值和sign字段；② **编码不一致**——所有参数需UTF-8 URL编码后再拼接，但部分开发者遗漏`URLEncoder.encode(value, "UTF-8")`或重复编码；③ **密钥使用错误**——误用APIv3的`mch_key`（32位商户API密钥）而非APIv2的`API_KEY`，或密钥含多余空格/换行；④ **时间戳/随机串生成不规范**——`nonce_str`含非法字符或超长，`timestamp`非当前秒级时间戳；⑤ **HTTP请求体与签名原文不一致**——如JSON中字段名大小写、空格、null处理与签名时参数不一致。建议统一用`TreeMap`排序+严格UTF-8编码+日志打印原始待签名字符串比对，再用微信签名工具校验。

Answer 1

```html

一、现象定位：签名验证失败的典型错误码与日志特征

调用微信企业付款到银行卡（pay/transfer_bank）接口时，返回 {"return_code":"FAIL","return_msg":"签名错误"} 或 HTTP 401，是签名层最直接的信号。需优先检查日志中是否输出了完整待签名字符串（sign_str），并与微信官方签名工具比对——二者必须字节级完全一致（含空格、换行、编码）。常见干扰项：Log4j默认截断长字符串、SLF4J参数占位符误吞URL编码字符。

二、根因剖析：五大高频签名失效场景深度拆解

1. 参数排序陷阱：未使用 TreeMap<String, String>（自然排序），而用 HashMap 或 LinkedHashMap 导致字段顺序随机；ASCII升序要求 amount < bank_code < mch_id，但开发者常按业务逻辑硬编码拼接顺序。
2. URL编码失范：对空值、null、数字类型（如 1000）未强制转为字符串再编码；或对已编码的 value 二次编码（如 URLEncoder.encode(URLEncoder.encode("张三", "UTF-8"), "UTF-8")）；更隐蔽的是，Java 8+ 的 URLEncoder.encode() 会将空格转为 +，而微信要求统一为 %20（需手动替换）。
3. 密钥混淆风险：APIv2 企业付款使用 32位纯字母数字 API_KEY（商户平台「API安全」页获取），非 APIv3 的 mch_key（用于 AES-256-GCM 解密回调）；密钥末尾常藏不可见的 \r\n（Windows编辑器保存导致），建议用 apiKey.trim().replaceAll("[\\s\uFEFF\u200B]+", "") 清洗。
4. 时间与随机串合规性：nonce_str 必须为 6–32 位 ASCII 字母/数字组合（正则 ^[A-Za-z0-9]{6,32}$），禁止下划线、汉字、emoji；timestamp 必须为 当前 Unix 秒级时间戳（System.currentTimeMillis() / 1000），误差超过 ±300 秒即拒收。
5. 请求体-签名体割裂：签名时用 Map<String,String> 构建参数，但实际 HTTP Body 发送 JSON 时，字段名大小写不一致（如签名用 bank_code，JSON 写成 bankCode）、数值型字段未加双引号（JSON 中 "amount":1000 vs 签名原文 amount=1000）、null 值被忽略导致字段缺失。

三、工程化解决方案：可复用的签名生成器（Java 8+）

public class WechatBankSigner {
    public static String generateSign(Map<String, String> params, String apiKey) {
        // 1. 过滤空值 & sign字段 → TreeMap自动ASCII升序
        Map<String, String> sorted = new TreeMap<>();
        params.forEach((k, v) -> {
            if (v != null && !v.trim().isEmpty() && !"sign".equals(k)) {
                sorted.put(k, v.trim());
            }
        });

        // 2. 拼接key=value&格式（注意：value必须UTF-8 URL编码，空格→%20）
        StringBuilder sb = new StringBuilder();
        sorted.forEach((k, v) -> {
            try {
                String encodedValue = URLEncoder.encode(v, StandardCharsets.UTF_8)
                    .replace("+", "%20") // 关键修复：+ → %20
                    .replace("*", "%2A")
                    .replace("%7E", "~");
                sb.append(k).append("=").append(encodedValue).append("&");
            } catch (UnsupportedEncodingException e) {
                throw new RuntimeException("UTF-8 encoding failed", e);
            }
        });
        sb.append("key=").append(apiKey.trim().replaceAll("\\s+", ""));

        // 3. 签名并转大写（微信要求MD5后全部大写）
        String signStr = sb.toString();
        log.info("Raw sign string: {}", signStr); // 生产环境务必保留此日志！
        return DigestUtils.md5Hex(signStr).toUpperCase();
    }
}

四、验证闭环：签名调试黄金流程图

flowchart TD A[构造原始参数Map] --> B{过滤空值/sign?} B -->|Yes| C[TreeMap ASCII升序] B -->|No| D[终止：签名必错] C --> E[逐个UTF-8 URL编码
→ 替换+为%20] E --> F[拼接key=value&...&key=APIKEY] F --> G[打印完整sign_str日志] G --> H[微信签名工具校验] H -->|一致| I[发起HTTPS请求] H -->|不一致| J[比对差异位置
→ 定位编码/排序/密钥问题] I --> K[检查响应JSON字段名大小写
是否与签名参数完全一致]

五、避坑清单：生产环境必须执行的10项检查

序号	检查项	正确做法	高危示例
1	参数排序	强制使用 TreeMap	new HashMap<>() 直接遍历
2	空值处理	v != null && !v.trim().isEmpty()	v != null 忽略空格字符串
3	URL编码	URLEncoder.encode(v, UTF_8).replace("+", "%20")	未替换 + 或重复编码
4	API密钥来源	商户平台「API安全」页复制的32位密钥	误用公众号后台的AppSecret
5	nonce_str生成	RandomStringUtils.randomAlphanumeric(16)	含中文、下划线、长度超32
6	timestamp精度	System.currentTimeMillis()/1000	毫秒级时间戳、服务端时钟漂移
7	HTTP Body一致性	JSON字段名、值类型、null策略与签名Map严格一致	签名用 amount=1000，JSON发 {\"amount\":1000}
8	字符集声明	HTTP Header 显式指定 Content-Type: application/json;charset=UTF-8	缺失charset导致服务器解析乱码
9	日志脱敏	打印sign_str时保留全量，但屏蔽apiKey中间字符（如 ***）	日志明文输出完整apiKey
10	环境隔离	开发/测试/生产使用独立API_KEY，禁止共用	测试环境密钥泄露导致生产被封禁

```