## 📋 目录

- [一、工具类功能](#sec-func)
- [二、所需环境](#sec-env)
- [三、方法与调用示例（按需调用）](#sec-method)

## 一、工具类功能 <a id="sec-func"></a>

参数表按 key 字典序拼成签名原文，再走摘要式或 HMAC-SHA256 出签名，回调验签、请求签名、兼容微信支付宝老协议都能用，拿回来是十六进制签名串与验签结论。

## 二、所需环境 <a id="sec-env"></a>

JDK 17或以上

## 三、方法与调用示例（按需调用） <a id="sec-method"></a>

🔢 **方法序号**：1

🎯 **方法用途**：
- 把参数表按 key 字典序拼成签名原文，`sign`、`sign_type` 与空值参数一律不进原文
- 对接支付网关、开放平台回调时先拿它出原文，再交给具体算法

🧩 **方法定义**：`public static String buildSignSource(Map<String, ?> params)`

🗣️ **入参解释**：`public static String buildSignSource(参数表)`

📤 **返回值解释**：`String`，形如 `k1=v1&k2=v2` 的签名原文

💡 **边界口径**：
- 排序按 key 的字典序走，与参数表原本的插入顺序无关
- 值为 null 与空串的参数被跳过，各家平台在这点上是一致的
- 集合与数组按出现顺序展开成同名多项，`tag=b&tag=a` 这种写法
- 原文不做 URL 编码，这是它与 `UrlCodecUtils.encodeQuery` 的本质区别，拿编码后的串去签名一定对不上
- 原样拼接的边界有歧义：值里含 `&` 或 `=` 时能拼出同一份原文，参与签名的字段不能来自不可信输入的自由拼接
- 参数表传 null 抛 `IllegalArgumentException`，key 为 null 的条目被直接跳过

🧪 **方法示例**：
- `buildSignSource(params)` 拿到 `appid=wx08804b9c9f8f8e3a&body=测试商品-上海&nonce_str=593EF8934B5A94F0C2&out_trade_no=ORD20260925001&total_fee=1`
- `buildSignSource(multiValue)` 拿到 `amount=12800&tag=b&tag=a`，集合按出现顺序展开
- `buildSignSource(Map.of("a", "1&b=2"))` 拿到 `a=1&b=2`，与两个参数拼出的原文完全一样
- `buildSignSource(null)` 抛 `参数Map不能为null`

---

🔢 **方法序号**：2

🎯 **方法用途**：
- 在默认剔除清单之上再加本平台特有的字段，比如某些平台要把 `sign_key`、`attach` 摘掉
- 各家协议要求剔除的字段不同，用这一版就不用自己先复制一份 Map 再 remove

🧩 **方法定义**：`public static String buildSignSource(Map<String, ?> params, Set<String> excludeKeys)`

🗣️ **入参解释**：`public static String buildSignSource(参数表, 额外剔除字段)`

📤 **返回值解释**：`String`，剔除后按字典序拼出的签名原文

💡 **边界口径**：
- 自定义清单是追加在 `sign`、`sign_type` 之上的，没法靠它把默认剔除关掉
- `excludeKeys` 传 null 时只按默认清单剔，不报错
- 其余排序、空值跳过、不做 URL 编码的口径与单参版一致

🧪 **方法示例**：
- `buildSignSource(withExtra, Set.of("sign_key"))` 拿到 `appid=wx08804b9c9f8f8e3a&body=测试商品-上海&nonce_str=593EF8934B5A94F0C2&out_trade_no=ORD20260925001&total_fee=1`，与默认清单剔完的结果一模一样
- `buildSignSource(params, null)` 拿到 `body=测试商品-上海&out_trade_no=ORD20260925001&total_fee=1`
- `buildSignSource(Map.of("body", "x", "partner", "y"), Set.of("partner"))` 拿到 `body=x`

---

🔢 **方法序号**：3

🎯 **方法用途**：
- 对现成的签名原文做摘要式签名，原文末尾拼上 `&key=密钥` 再整体取摘要，输出小写 Hex
- 微信 JS-SDK 这类要自己拼原文（`jsapi_ticket=...&noncestr=...&url=...`）的协议只能走这一层

🧩 **方法定义**：`public static String signSourceByDigest(String signSource, String secret, String digestAlgorithm)`

🗣️ **入参解释**：`public static String signSourceByDigest(签名原文, 密钥, 摘要算法)`

📤 **返回值解释**：`String`，小写十六进制的签名值

💡 **边界口径**：
- 算法取 `ALG_MD5`、`ALG_SHA256` 这类常量，白名单外的名字抛 `IllegalArgumentException` 并列出支持范围
- 密钥拼在原文末尾的 `&key=` 之后，这是历史协议的固定写法
- 摘要式为兼容老协议保留，新接入用 HMAC，涉及资金的验签用非对称算法
- 原文为 null、密钥为 null 或空白都抛 `IllegalArgumentException`，空原文照样能算

🧪 **方法示例**：
- `signSourceByDigest(source, SECRET, ApiSignUtils.ALG_SHA256)` 拿到 `0f0d73df94313475f5585dcb66f4caabecc465f01605630afbb02dfa13b18491`
- `signSourceByDigest(jsApiSource, SECRET, ApiSignUtils.ALG_SHA256)` 拿到 `8b9bb3ee34396e862a5bb946a7c63b4cad0a1bcc6839372547df4594b0317ce5`
- `signSourceByDigest("", SECRET, ApiSignUtils.ALG_MD5)` 拿到 `0b4ad1d96492c0442d79efa9125434f4`，空原文也能算
- `signSourceByDigest(null, SECRET, ApiSignUtils.ALG_SHA256)` 抛 `签名原文不能为null`
- `signByDigest(params, SECRET, "SM3")` 抛 `不支持的摘要算法: SM3，仅支持 MD5/SHA-1/SHA-256/SHA-512`

---

🔢 **方法序号**：4

🎯 **方法用途**：
- 摘要式签名并要求输出大写 Hex，部分银行网关的字段就是这个形态
- 只是大小写不同的展示形式，签名值本身与三参版一致

🧩 **方法定义**：`public static String signSourceByDigest(String signSource, String secret, String digestAlgorithm, boolean uppercase)`

🗣️ **入参解释**：`public static String signSourceByDigest(签名原文, 密钥, 摘要算法, 是否大写)`

📤 **返回值解释**：`String`，`uppercase` 为 true 时给大写 Hex

💡 **边界口径**：
- 转大写用的是 `Locale.ROOT`，不受系统语言环境影响
- 验签侧比的是解码后的字节，发出去是大写、对方按小写验也能过
- 参数校验与三参版相同

🧪 **方法示例**：
- `signSourceByDigest(source, SECRET, ApiSignUtils.ALG_SHA256, true)` 拿到 `0F0D73DF94313475F5585DCB66F4CAABECC465F01605630AFBB02DFA13B18491`
- `verifySourceByDigest(source, SECRET, ApiSignUtils.ALG_MD5, 大写签名)` 拿到 `true`

---

🔢 **方法序号**：5

🎯 **方法用途**：
- 对签名原文做 HMAC 签名，输出小写 Hex，新接入首选 `HmacSHA256`
- 密钥不进原文、而是当 HMAC 的 key 用，比把密钥拼在明文尾巴上稳

🧩 **方法定义**：`public static String signSourceByHmac(String signSource, String key, String hmacAlgorithm)`

🗣️ **入参解释**：`public static String signSourceByHmac(签名原文, 密钥, HMAC算法)`

📤 **返回值解释**：`String`，小写十六进制的 HMAC 签名值

💡 **边界口径**：
- HMAC 算法白名单是 `HmacMD5`、`HmacSHA1`、`HmacSHA256`、`HmacSHA512`，写别的直接抛异常
- 原文为 null、密钥为 null 或空白都抛 `IllegalArgumentException`
- 原文这层不做任何拼接与排序，传进来什么就签什么

🧪 **方法示例**：
- `signSourceByHmac(source, SECRET, "HmacSHA256")` 拿到 `9aa4610b16258cd2970cdaa371c699a93ad8916889a527c89cd456c7600bf27c`
- `signSourceByHmac(source, "  ", "HmacSHA256")` 抛 `密钥不能为null或空白`
- `signSourceByHmac(source, SECRET, "HmacSM3")` 抛 `不支持的HMAC算法: HmacSM3，仅支持 HmacMD5/HmacSHA1/HmacSHA256/HmacSHA512`

---

🔢 **方法序号**：6

🎯 **方法用途**：
- HMAC 签名并控制输出大小写，网关要求大写 Hex 时用
- 与三参版只差展示形式，签名值一致

🧩 **方法定义**：`public static String signSourceByHmac(String signSource, String key, String hmacAlgorithm, boolean uppercase)`

🗣️ **入参解释**：`public static String signSourceByHmac(签名原文, 密钥, HMAC算法, 是否大写)`

📤 **返回值解释**：`String`，`uppercase` 为 true 时给大写 Hex

💡 **边界口径**：
- 大写只影响字符形态，验签比的是字节
- 参数校验与三参版相同

🧪 **方法示例**：
- `signSourceByHmac(source, SECRET, "HmacSHA256", true)` 拿到 `9AA4610B16258CD2970CDAA371C699A93AD8916889A527C89CD456C7600BF27C`

---

🔢 **方法序号**：7

🎯 **方法用途**：
- 参数表一步出摘要式签名，内部就是拼原文再做摘要
- 兼容微信公众号、支付宝老接口这类 `MD5(原文&key=密钥)` 的历史协议

🧩 **方法定义**：`public static String signByDigest(Map<String, ?> params, String secret, String digestAlgorithm)`

🗣️ **入参解释**：`public static String signByDigest(参数表, 密钥, 摘要算法)`

📤 **返回值解释**：`String`，小写十六进制的签名值

💡 **边界口径**：
- 原文口径与 `buildSignSource(params)` 完全一致，`sign` 与空值不参与
- 回调验签时对方带回来的 `sign` 会被自动剔掉，不会把自己算进去
- MD5 只用于兼容，新接入别用

🧪 **方法示例**：
- `signByDigest(params, SECRET, ApiSignUtils.ALG_MD5)` 拿到 `d7922d5ef9ab694bc6b87abb5d6c5f86`
- `signByDigest(params, SECRET, ApiSignUtils.ALG_SHA256)` 拿到 `0f0d73df94313475f5585dcb66f4caabecc465f01605630afbb02dfa13b18491`，与先拼原文再签同值

---

🔢 **方法序号**：8

🎯 **方法用途**：
- 参数表一步出摘要式签名并指定大写 Hex
- 老协议里要求签名字段大写的网关用这一版

🧩 **方法定义**：`public static String signByDigest(Map<String, ?> params, String secret, String digestAlgorithm, boolean uppercase)`

🗣️ **入参解释**：`public static String signByDigest(参数表, 密钥, 摘要算法, 是否大写)`

📤 **返回值解释**：`String`，指定大小写形态的签名值

💡 **边界口径**：
- 只是把三参版的结果整体转大写，原文与算法口径不变
- 参数表为 null 同样抛 `IllegalArgumentException`

🧪 **方法示例**：
- `signByDigest(params, SECRET, ApiSignUtils.ALG_MD5, true)` 拿到 `D7922D5EF9AB694BC6B87ABB5D6C5F86`

---

🔢 **方法序号**：9

🎯 **方法用途**：
- 参数表一步出 HMAC 签名，新接入的首选写法
- 不想自己先调一次拼原文时，用它把两步并成一步

🧩 **方法定义**：`public static String signByHmac(Map<String, ?> params, String key, String hmacAlgorithm)`

🗣️ **入参解释**：`public static String signByHmac(参数表, 密钥, HMAC算法)`

📤 **返回值解释**：`String`，小写十六进制的签名值

💡 **边界口径**：
- 与先 `buildSignSource` 再 `signSourceByHmac` 结果同值，两条路径可以混用
- 算法白名单、密钥与原文的校验口径与原文级入口一致

🧪 **方法示例**：
- `signByHmac(params, SECRET, "HmacSHA256")` 拿到 `9aa4610b16258cd2970cdaa371c699a93ad8916889a527c89cd456c7600bf27c`，与原文级入口同值

---

🔢 **方法序号**：10

🎯 **方法用途**：
- 参数表一步出 HMAC 签名并指定大写输出
- 对端字段要求大写时用它，其余口径与三参版相同

🧩 **方法定义**：`public static String signByHmac(Map<String, ?> params, String key, String hmacAlgorithm, boolean uppercase)`

🗣️ **入参解释**：`public static String signByHmac(参数表, 密钥, HMAC算法, 是否大写)`

📤 **返回值解释**：`String`，指定大小写形态的签名值

💡 **边界口径**：
- 大写只改展示形式，验签比的是字节
- 需要去掉 `=`、走 URL 安全字母形的 Base64 签名不属于本类范围

🧪 **方法示例**：
- `signByHmac(params, SECRET, "HmacSHA256", true)` 拿到 `9AA4610B16258CD2970CDAA371C699A93AD8916889A527C89CD456C7600BF27C`

---

🔢 **方法序号**：11

🎯 **方法用途**：
- 校验摘要式签名，走常量时间比较，避免按字节早退带来的计时侧信道
- 已经自己拼好原文（比如微信 JS-SDK）就验原文这一层

🧩 **方法定义**：`public static boolean verifySourceByDigest(String signSource, String secret, String digestAlgorithm, String expectedSign)`

🗣️ **入参解释**：`public static boolean verifySourceByDigest(签名原文, 密钥, 摘要算法, 待验签名)`

📤 **返回值解释**：`boolean`，签名与原文匹配返回 `true`

💡 **边界口径**：
- 比的是解码后的字节，待验签名的大小写、首尾空白都不影响结果
- 签名值缺失、长度不对、含非十六进制字符一律判 `false`，不抛异常
- 会先算一次签名，所以原文、密钥、算法这类调用方错误照样抛 `IllegalArgumentException`
- 只保证签名与原文一致，防重放还得自己配 nonce 与时间戳校验

🧪 **方法示例**：
- `verifySourceByDigest(source, SECRET, ApiSignUtils.ALG_MD5, legacyMd5)` 拿到 `true`
- 待验签名用大写形态传，同样拿到 `true`
- `verifySourceByDigest(source, SECRET, "SM3", "anyhex")` 抛 `不支持的摘要算法: SM3，仅支持 MD5/SHA-1/SHA-256/SHA-512`

---

🔢 **方法序号**：12

🎯 **方法用途**：
- 校验 HMAC 签名，同样走常量时间比较
- 对端把签名转成大写、或者串里带了空白时不会因为格式判错

🧩 **方法定义**：`public static boolean verifySourceByHmac(String signSource, String key, String hmacAlgorithm, String expectedSign)`

🗣️ **入参解释**：`public static boolean verifySourceByHmac(签名原文, 密钥, HMAC算法, 待验签名)`

📤 **返回值解释**：`boolean`，签名与原文匹配返回 `true`

💡 **边界口径**：
- 待验签名先按十六进制解析，解不出就判 `false`
- 大小写、首尾空白不参与比较
- 算法名非法、密钥空白这类调用方错误仍抛 `IllegalArgumentException`

🧪 **方法示例**：
- `verifySourceByHmac(source, SECRET, "HmacSHA256", hmacHex.toUpperCase())` 拿到 `true`
- 把签名改成小写再套上首尾空白，`verifyByHmac(params, SECRET, "HmacSHA256", "  大写串  ")` 仍拿到 `true`

---

🔢 **方法序号**：13

🎯 **方法用途**：
- 对整张回调参数表验摘要式签名，一步完成拼原文与比较
- 支付回调通知的验签入口，`sign` 字段本身会被自动剔掉

🧩 **方法定义**：`public static boolean verifyByDigest(Map<String, ?> params, String secret, String digestAlgorithm, String expectedSign)`

🗣️ **入参解释**：`public static boolean verifyByDigest(参数表, 密钥, 摘要算法, 待验签名)`

📤 **返回值解释**：`boolean`，参数表与签名匹配返回 `true`

💡 **边界口径**：
- 等于 `buildSignSource(params)` 再走原文级验签，剔除与排序口径完全一致
- 忘了剔 `sign` 这类字段导致验不过的情况在这一版不会发生
- 签名值非法只判 `false`，参数表为 null 抛异常

🧪 **方法示例**：
- `verifyByDigest(params, SECRET, ApiSignUtils.ALG_MD5, legacyMd5)` 拿到 `true`

---

🔢 **方法序号**：14

🎯 **方法用途**：
- 对整张参数表验 HMAC 签名，公网接口收到请求时的第一道校验
- 金额、订单号被改一分都过不了，签名值本身残缺也不会把异常抛给调用方

🧩 **方法定义**：`public static boolean verifyByHmac(Map<String, ?> params, String key, String hmacAlgorithm, String expectedSign)`

🗣️ **入参解释**：`public static boolean verifyByHmac(参数表, 密钥, HMAC算法, 待验签名)`

📤 **返回值解释**：`boolean`，参数表与签名匹配返回 `true`

💡 **边界口径**：
- 参数字段被改、被删、多出未签名字段都会判 `false`
- 待验签名为 null、空白、长度为奇数、含非十六进制字符都判 `false` 而不抛异常，公网收到的就是这种输入
- 值为 null 与空串的参数本来就不进原文，这类字段改了不影响验签结果
- 验过签名不等于请求没被重放，nonce 与时间戳要自己校验

🧪 **方法示例**：
- `verifyByHmac(tampered, SECRET, "HmacSHA256", hmacHex)` 拿到 `false`，total_fee 被改了一分钱
- 参数表原样不动时拿到 `true`
- 待验签名传 null 拿到 `false`，不抛异常
- 待验签名截掉最后一位（长度变奇数）拿到 `false`
- 待验签名塞进非十六进制字符拿到 `false`
- 待验签名传空白串拿到 `false`




参数表按 key 字典序拼成签名原文，再走摘要式或 HMAC-SHA256 出签名，回调验签、请求签名、兼容微信支付宝老协议都能用，拿回来是十六进制签名串与验签结论。

开放接口签名怎么算？这个Java工具类14个方法兼容微信支付宝

人工智能

提供Java版签名验签工具类，支持MD5/SHA/HMAC-SHA256算法，兼容微信支付宝协议。参数按字典序拼接自动剔除空值，提供原文生成、摘要/HMAC签名、回调验签及大写输出等功能，适配JDK17+，保障支付网关安全对接。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

开放接口签名怎么算？这个Java工具类14个方法兼容微信支付宝-腾讯云开发者社区-腾讯云

开放接口签名怎么算？这个Java工具类14个方法兼容微信支付宝

开放接口签名怎么算？这个Java工具类14个方法兼容微信支付宝

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐