做接口开发的这几年，我最常被问到的不是“怎么写接口”，而是“为什么我调接口老报签名错误”。就拿这个api请求加密（MD5+UTF-8）来说，听起来是三个词拼在一起，实际落地时涉及编码规则、参数排序、密钥约定、时间戳防重放一整套逻辑。你百度一圈看到一堆代码，抄过来还是验签失败，不是你笨，是你在动手前缺了一张完整的“签名生成地图”。
这篇文章我就围绕“MD5+UTF-8”这套最常用的API签名方案，把为什么需要签名、签名算法怎么设计、客户端怎么生成、服务端怎么校验、失败怎么排查一次讲透。适合正在写对外接口的后端开发、刚接手支付或开放平台项目的同学，也适合前端调用接口时总被签名问题搞心态的人。看完你至少能手写出一个能稳跑业务的签名模块，并且知道哪些地方容易踩坑。
1. 为什么要给API请求加签名：先搞懂它解决什么问题
1.1 裸参数请求的三个致命问题
假设你设计了一个用户余额查询接口，参数只有userId=1001，客户端直接GET /getBalance?userId=1001就能拿到余额。在公司内网、私有协议下这问题不大，但一旦接口暴露在公网，比如你做的是一个微信小程序后端，那问题就出来了。
第一个问题是参数篡改。攻击者把userId=1001改成userId=1002，如果服务端只依赖这个参数做查询，他就能看到别人的余额。有人会说“我用HTTPS，数据是加密传输的”，HTTPS保护的是传输过程中的保密性和完整性，但服务端和客户端各有一把钥匙，到了服务端之后参数变成明文，服务端无法区分这段请求是来自你的App还是来自攻击者伪造的请求。这里的本质是“服务端无法验证参数是否被第三方修改过”。
第二个问题是身份伪装。攻击者不需要登录态，直接把你的请求参数复制一份，换个IP重放一遍，服务端还是照单处理。如果你的接口是查询类问题不大，但如果接口是“转账”“改密码”“核销券码”，重放就是灾难。
第三个问题是明文参数暴露。URL里写着amount=1000&account=6222xxxx，不仅日志会记录，浏览器的历史记录、CDN的访问日志都会留下完整参数。就算服务端加了权限校验，参数本身也属于敏感信息，最好让它不可直接读取。
这时候就需要一套机制，让服务端能判断“这段请求确实是客户端发出的、参数在传输中没有被改过、请求本身足够新鲜”。这就是API签名的价值。
1.2 签名机制是怎么工作的：一次请求的完整信任链
签名机制可以类比成你寄一个快递时在封口处贴的防拆标签。你把所有要寄的东西（参数）放在盒子里，在封口处用一团印泥盖一个专属于你的图章，收件人收到后先看封口处图章是否完整，再打开箱子核对物品。如果封口图章破损，说明运输途中有人动过手脚；如果图章对不上，说明这盒子不是你的原装货。
API签名也是这样工作的：
客户端把所有业务参数、密钥、时间戳按约定规则拼成一个字符串，计算出一个固定长度的签名值sign，这个sign随请求一起发给服务端。服务端收到请求后，用同样的参数、同样的密钥、同样的规则，自己算一遍sign。如果两边算出来完全一致，说明请求参数没被改过、来源可信；如果不一致，直接拒绝请求并把请求丢弃。
这里的核心逻辑是：密钥只有客户端和服务端知道，第三方不知道，所以第三方即使拿到全部参数也拼不出正确的签名。MD5在这个环节就是那个“图章生成器”，它的特点是同样的输入一定得到同样的输出，而输入中任何一个字符变了，输出就会完全变样。
这套机制解决上一节提到的三个问题：
- 参数被篡改后，重新计算出的MD5值对不上，服务端直接拒绝
- 第三方伪造参数时不知道密钥，无法生成合法签名
- 因为签名不含明文敏感信息，日志泄露参数不会导致直接安全风险（当然敏感字段还是建议单独加密）
1.3 为什么偏偏选MD5：不是因为它最强，而是因为它够简单可靠
有人一听到MD5就觉得过时了，确实MD5在碰撞性上已经被学术界证明不再安全，但在API请求签名这个场景里，它依然有不可替代的优势。
首先是实现普及度。几乎每种编程语言原生就能算MD5，不需要装额外依赖，Java、Python、Go、Node.js、PHP、Objective-C、Kotlin全部内置，移动端和服务端没有技术代沟。你新接手一个老项目，随手一翻工具类就能找到MD5计算函数。
其次是计算性能。一次MD5计算约几十微秒级别，单机每秒可以算几万甚至十几万次，在签名验签这种高频操作上不会成为瓶颈。如果你选用非对称加密RSA做签名，单次耗时是毫秒级，性能差了几十倍，而且密钥管理复杂度高。
第三是长度固定、拼接方便。MD5输出固定32位十六进制字符串，适合放在sign=xxxxxxxx这样一个参数里，日志里也好识别，数据库里也好存储和比对。
作为从业者，我还是要诚实说一句：如果你做的是金融级或极重要数据的接口，且请求量不大，建议优先用HMAC-SHA256或RSA签名。MD5适合的业务场景是“防止参数被简单篡改、防止接口被无聊脚本刷”，它能挡住99%的菜鸟攻击，但挡不住专业级攻击。后面第5章我会专门展开这个边界。
2. 签名之前必须做对的三件事：UTF-8编码、参数排序、密钥约定
2.1 UTF-8是签名的隐形地基
大多数验签失败的问题，根源不在签名算法本身，而是编码问题。项目标题里单独把UTF-8列出来，不是没有原因的。
MD5计算的对象是字节序列，不是字符串。同一个字符串“你好”，在UTF-8编码下是E4 BD A0 E5 A5 BD（6个字节），在GBK编码下是C4 E3 BA C3（4个字节），在UTF-16下又是另一种字节序。如果客户端用UTF-8把“你好”转成了字节数组后计算MD5，服务端却用系统默认编码GBK解析了请求参数再算MD5，两个结果必然不一样，签名就对不上。
这个问题的隐蔽之处在于：很多开发者平时写的接口参数全是英文和数字，用哪种编码计算都一模一样，所以一直没暴露过问题。一旦有用户把昵称、地址、备注等中文参数放进请求里，签名就开始随机性失败，而且是在线上才会暴露。
正确的做法是：在拼接完原始签名字符串之后，所有语言里都必须显式声明用UTF-8编码去获取字节数组，再送入MD5函数。
以Java为例：
String rawString = "amount=100&name=张三&key=abcd1234"; MessageDigest md = MessageDigest.getInstance("MD5"); byte[] digest = md.digest(rawString.getBytes(StandardCharsets.UTF_8));以Go为例：
rawString := "amount=100&name=张三&key=abcd1234" hash := md5.Sum([]byte(rawString))如果你写的是getBytes()而没有指定字符集，JVM在Linux服务器上默认是UTF-8，在Windows默认可能是GBK，同一个代码在两地部署结果完全不同。Python里也要注意字符串和字节串的转换，Python3的md5()函数必须传入bytes类型，你需要先s.encode("utf-8")，直接传字符串会直接报错，而在Python2里你还得小心默认编码不一致。
服务端在接收参数时同样要注意URL解码的编码方式。比如HTTP请求体里name=%E5%BC%A0%E4%B8%89是UTF-8百分号编码，你的容器用ISO-8859-1去解码就变成了乱码，签名自然对不上。Spring系框架getParameter()默认按request.setCharacterEncoding("UTF-8")处理，有的老项目没设置就会出问题。
2.2 ASCII码升序排序规则：字典序背后的防混淆逻辑
签名的原始字符串由多个参数拼接而成，这里关键的一个设计是：参数必须按固定顺序拼接。如果前后端约定不一样，比如客户端按a=1&b=2拼，服务端按b=2&a=1拼，两边算出来的MD5完全不同。
最常用的约定是按参数名ASCII码升序排列，也就是字典序。这样做的好处有三个：
第一，服务端不需要知道客户端当初是怎么排序的，只要拿到参数后自己按所有常见语言排序函数排一遍，就能还原出同样的拼接串。比如a、b、c，在ASCII码里就是字母序，Java的Arrays.sort()、Python的sorted()、Go的sort.Strings()默认行为都是字典序。
第二，避免人为沟通时搞错顺序。如果约定“按照文档里表格从上到下的顺序拼接”，文档更新后新旧顺序对不上就会大面积报错。而“按key排序”是客观规则，不依赖文档，代码解析出来几个参数就排几个。
第三，防止参数被增加后混乱。客户端新增一个timestamp参数后，排序规则自动把它放到正确的位置，不需要人工指定插到哪。
下面给出一个最典型的拼接过程：
假设业务参数是：
amount=100 orderId=20240606001 name=张三 timestamp=1717600000密钥约定为abc123secert（生产环境请随机生成一个足够长的字符串）。
第一步：剔除签名本身参数sign以及请求中用于传输签名的辅助参数，将剩余参数按key名做ASCII升序排序：
amount name orderId timestamp第二步：拼成key1=value1&key2=value2...格式：
amount=100&name=张三&orderId=20240606001×tamp=1717600000第三步：把密钥拼到末尾（也可以拼到开头，但头尾都要约定好）：
amount=100&name=张三&orderId=20240606001×tamp=1717600000&key=abc123secert第四步：对上面的字符串做UTF-8编码后计算MD5：
d41f8c7f0d2cf9d9a2e5a0b6e3c03b91这里有一个小细节：排序是对参数名排序，不是对value排序。参数的值保持原样不要动。还要注意参数名必须是全小写或全大写，并且大小写敏感——Amount和amount是两个不同的key，排序位置也完全不同，一旦混用就会验签失败。我在实际项目里要求所有参数名强制定义为小写，避免这种低级错误。
2.3 时间戳与随机数nonce：防重放的两个关键设计
光有参数学MD5，只能证明参数没被改过，但无法防止攻击者把一整段合法请求保存下来，过几分钟、过几天再重放一次。比如一个“领取优惠券”的接口，攻击者截获你领券的请求，重放100次，服务端可能就会发100张券给他。
解决方案是给签名加入时效性和一次性两个概念。
时效性用timestamp实现。客户端请求时把当前Unix秒级时间戳作为参数发给服务端，参与签名计算。服务端拿到请求先看时间戳与当前时间差，一般约定5分钟内为有效，超过这个时间窗口直接拒绝，不再做签名比对。这个设计使得攻击者保存的请求最多只有5分钟的生命周期，过期自动失效。
一次性用nonce实现。nonce是一个客户端生成的随机字符串，每次请求都不同，同样参与签名计算。服务端在校验签名通过之后，把这个nonce记录下来，在有效时间窗口内如果再次收到相同nonce的请求，判定为重放，直接拒绝。这样即使攻击者在5分钟内重放原始请求，服务端也已经记住了那个nonce，第二次来就过不了。
有人会问：如果攻击者同时又改了timestamp和nonce，是不是就能绕过了？不行，因为timestamp和nonce都参与签名计算，攻击者改了它们就要重新计算签名，但签名计算需要密钥，他不知道密钥就生不成合法签名。所以time=5分钟、nonce=一次性，这两道关卡和MD5签名是相互咬合在一起的一套整体，缺一个都不安全。
整个签名串从“参数防篡改”变成：
amount=100&name=张三&nonce=6f4e2b1a9c8d4f2e&orderId=20240606001×tamp=1717600000&key=abc123secert这里的nonce只需要保证在5分钟内全局唯一即可，不需要全局唯一。实际上即使两个请求用了相同的nonce，由于上一节那个排序后的串内容完全一样、签名也一样，服务端看到重复nonce就拒绝，逻辑完全自洽。
3. 手把手实现MD5+UTF-8签名：客户端生成与服务端校验完整代码
3.1 先定规矩：签名算法的统一约定文档
实现代码前，先要有一份可以发给前后端所有人的约定文档。以我自己常用的约定为例：
| 项目 | 约定 |
|---|---|
| 编码格式 | UTF-8 |
| 摘要算法 | MD5 |
| 排序规则 | 对参数名ASCII升序排，拼接为k1=v1&k2=v2 |
| 密钥拼接 | 在串末尾追加&key=你的私钥 |
| 签名参数名 | sign，传递时放在请求参数末尾 |
| 时效性 | 请求参数必带timestamp，服务端允许偏差 ±5分钟 |
| 重放防护 | 请求参数必带nonce，服务端在时间窗口内缓存nonce |
| 参与签名参数 | 除sign外所有参数均参与（有些框架把sign之外的辅助参数也排除，务必明确） |
这份约定是所有代码的实现依据，前后端、客户端、团队新人都要照着一份文档开发，而不是各写各的。我见过太多部署后联调失败，最后发现“客户端把accessToken也参与签了名，服务端把accessToken排除了”，整个签名体系瞬间失效。
3.2 服务端MD5签名工具函数（Java实现）
大部分后端项目是Java或Spring技术栈，我把服务端核心工具写好，其他语言照着翻译即可。
public class SignUtil { /** * 生成签名 * * @param params 参与签名的参数（不包含sign本身） * @param secretKey 双方约定的密钥 */ public static String sign(SortedMap<String, String> params, String secretKey) throws UnsupportedEncodingException { StringBuilder sb = new StringBuilder(); for (Map.Entry<String, String> entry : params.entrySet()) { String key = entry.getKey(); String value = entry.getValue(); if (key == null || key.equals("sign") || value == null || value.isEmpty()) { continue; } sb.append(key).append("=").append(value).append("&"); } sb.append("key=").append(secretKey); return md5(sb.toString()); } private static String md5(String data) throws UnsupportedEncodingException { try { byte[] bytes = data.getBytes(StandardCharsets.UTF_8); MessageDigest md = MessageDigest.getInstance("MD5"); byte[] digest = md.digest(bytes); StringBuilder hexStr = new StringBuilder(); for (byte b : digest) { String hex = Integer.toHexString(0xff & b); if (hex.length() == 1) { hexStr.append('0'); } hexStr.append(hex); } return hexStr.toString(); } catch (NoSuchAlgorithmException e) { throw new RuntimeException("MD5 algorithm not found"); } } }这里的SortedMap传入的时候就按key排好序，不要到函数里再排一次。实际开发里建议用TreeMap，因为HashMap的顺序是随机的，必须用TreeMap。
3.3 客户端签名计算（Java / Android / iOS风格）
客户端和服务端用同一套规则，下面给出一个典型的客户端生成签名的代码。注意在Android开发中MessageDigest的用法和服务端完全一致。
public static String createSign(Map<String, String> params, String secretKey) { TreeMap<String, String> sortedParams = new TreeMap<>(params); sortedParams.remove("sign"); // 签名参数本身不参与签名 StringBuilder sb = new StringBuilder(); for (Map.Entry<String, String> entry : sortedParams.entrySet()) { String value = entry.getValue(); if (value != null && !value.isEmpty()) { sb.append(entry.getKey()).append("=").append(value).append("&"); } } sb.append("key=").append(secretKey); String raw = sb.toString(); // 关键：getBytes必须指定UTF-8 String sign = md5(raw.getBytes(StandardCharsets.UTF_8)); return sign.toUpperCase(); }有些团队约定MD5结果大写，有些约定小写，关键是前后端保持一致。常见的做法是统一转成大写或统一小写后比较，我习惯用小写并显式转换。
3.4 服务端完整验签流程（含时间戳和nonce校验）
一个可靠的验签流程不能只比签名，必须按以下顺序走：
public boolean verifySign(Map<String, String> params, String secretKey) { String sign = params.get("sign"); if (StringUtils.isEmpty(sign)) { return false; // 没有签名的请求直接拒绝 } String timestampStr = params.get("timestamp"); long timestamp = Long.parseLong(timestampStr); long now = System.currentTimeMillis() / 1000; if (Math.abs(now - timestamp) > 300) { // 5分钟 return false; // 过期请求拒绝 } String nonce = params.get("nonce"); if (nonceExistsInWindow(nonce)) { return false; // 重复nonce，判定为重放 } String serverSign = SignUtil.sign(params, secretKey); boolean ok = serverSign.equalsIgnoreCase(sign); if (ok) { saveNonce(nonce, timestamp); // 记录nonce，过期自动清理 } return ok; }nonce的存储可以简单用一个Redis Set，key为nonce:{timestamp的一半窗口}，过期时间设为10分钟让Redis自动清理，不必做得太重。如果是单机小项目，用一个带过期时间的ConcurrentHashMap也行。
3.5 客户端工具类：自动带timestamp和nonce的请求封装
签名不能靠业务代码里手动拼参数，那样太容易漏。封装一个SignedRequestHelper，业务代码只需传业务参数，工具类自动附加时间戳、nonce和签名。
public class SignedRequest { public static Map<String, String> buildSignedParams(Map<String, String> businessParams, String secretKey) { TreeMap<String, String> treeMap = new TreeMap<>(); treeMap.putAll(businessParams); treeMap.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000)); treeMap.put("nonce", UUID.randomUUID().toString().replace("-", "")); String sign = createSign(treeMap, secretKey); treeMap.put("sign", sign); return treeMap; } }这里有个细节：buildSignedParams的入参是业务参数，它内部新增的timestamp和nonce需要参与签名。如果把这两个参数放到createSign之后才加，签名就会缺失这两个关键字段，重放防护形同虚设。
3.6 兼容多个密钥与多版本签名的方法
演进过程中经常遇到老版本客户端还在用旧的密钥或旧签名规则，不能一刀切下线。我的做法是：在签名串中加入版本号参数version=1，服务端读取版本号来选择对应的密钥和校验规则。同时保留一份“兼容模式”的对比表，新规则验签失败后再用旧规则尝试一次。兼容窗口不要开太久，建议设定一个明确的deadline，到期后强制客户端升级。
这些内容看似琐碎，但在真实联调中几乎每个项目都会遇到。生产级别稳定的签名系统，不是网页上抄一段md5工具函数就能用的，必须把时间戳、nonce、版本号、异常分支这些边界都补全。
4. 排查实录：签名验证失败的典型问题速查
4.1 编码不一致：同一条请求，为什么两边算出来的sign不一样
这是我在支持其他团队联调时遇到最多的一个问题，占比接近四成。具体症状是：客户端明明在本地用相同参数、相同密钥算出了正确签名，服务端验签却怎么也对不上。
有一次排查了很久，最后发现客户端是Objective-C写的，用NSString的dataUsingEncoding:NSUTF8StringEncoding转码，看起来没问题，但它在拼接签名字符串时对中文的value做了stringByAddingPercentEscapesUsingEncoding，把张三变成了%E5%BC%A0%E4%B8%89，而服务端拿到的是解码后的原始中文张三，两边参与签名的字符串本质不同。
这个排查过程也提示了规范的重要性：签名阶段对参数值不做URL编码，保持原始值拼接；而在HTTP传输阶段做URL编码。一个参数两套状态，一旦混淆就会出问题。
另一个常见的编码坑是PHP环境：老版本PHP的http_build_query默认把中文编码成urlencode格式，用这个结果去计算MD5就会与服务端不一致。正确做法是先urldecode再参与签名。
如果前后端签名不一致，建议先在日志中打印“签名原文”，就是拼接后的那个字符串，对比两端原文是否完全一致。这个操作比猜哪里错了快得多。
4.2 路由和反向代理对签名的干扰
生产环境里前端请求往往不会直达业务服务器，中间可能有Nginx、网关、负载均衡。这里有一个隐蔽问题：如果你签名时用的参数来自于HTTP请求体，中间经过网关转发时，请求体可能被重新解析、重写。
具体场景是：客户端签名用的是a=1&b=2&c=3这个原始顺序和编码，但Nginx配置了proxy_set_header或网关做了参数重组，服务端收到的请求体被改了顺序或增加了一些网关透传字段（比如gw_timestamp、traceId）。虽然你加的辅助参数如果不参与签名就不会影响最终验签，但如果网关把原始body整体重新序列化，比如把JSON里的key顺序打乱，就会导致服务端重新拼签名的串与客户端不一致。
解决思路：
- 配置网关时关闭body改写，透明传递
- 如果确实需要注入字段，让这些字段不参与签名，但要明确列入约定文档
- 签名参数使用queryString传参而非body传参，可以规避部分body重写问题
这类问题非常难定位，因为签名计算是对的，但传输链路对数据动了手脚。建议在服务端打印收到的“原始请求体”再进行签名比对，不要打印框架帮你解析成Map之后的东西。
4.3 时间偏差过大造成的阴间报错
如果你的服务器时间不准，或者客户端设备时间被用户手动改偏了，服务端时间窗口校验就会误杀正常请求。遇到过最夸张的一个case是测试机BIOS电池老化，系统时间慢了一整天，所有带timestamp的请求都被拒，签名算法本身完全没问题。
这类问题的排查思路很简单：打开服务端日志，打印请求的timestamp值和服务器当前时间，差多少一眼就看得出来。真正要决策的是时间窗口设多大：设得太短，比如30秒，网络抖动加服务器时钟偏差很容易误伤；设得太长，比如30分钟，重放窗口也太宽。我一般设5分钟，客户端的timestamp生成逻辑使用设备当前时间，如果检测到设备时间与服务器时间差超过1分钟就自动校准一次，避免用户改时间导致的边界问题。
另外要注意时间戳单位统一：Unix时间戳有的用秒，有的用毫秒。十位的“1717600000”和十三位的“1717600000000”刚好差1000倍，一旦混用签名串就不同，这个错误在日志里特别难发现，因为看起来只是数字长了一截。
4.4 并发请求的nonce冲突与重复提交
小流量时nonce用UUID基本不会重复，但一旦服务端并发高，可能会出现重放误判：两个不同请求恰好用了相同nonce，后到的被误判为重放。出现概率极低，但并非零。
严格的做法是nonce加入随机数生成时的熵源，比如UUID本身就够用，但如果用的随机算法较弱，建议加前缀时间戳-业务号-随机数组合，确保全局唯一且与业务维度绑定。同时服务端在保存nonce时不要设太短的过期时间，至少覆盖时间窗口的时间长度，否则窗口内nonce记录失效，重放又会漏进来。
常见问题整理成一个速查表：
| 问题现象 | 可能原因 | 排查与修复 |
|---|---|---|
| 中文参数验签失败 | 编码不是UTF-8；或签名时做了URL编码 | 统一UTF-8；签名用原始值，传输阶段再编码 |
| 英文数字参数验签失败 | 参数顺序不一致或value首尾空格未trim | 打印签名原文对比；所有value先trim再拼接 |
| 同一请求偶发失败 | 时间戳偏差、网关改写body | 校准设备时间；网关关闭body改写 |
| 重放请求被放行 | nonce未参与签名、nonce未保存 | 确认nonce参与拼接；加Redis保存nonce |
| 老版本客户端报错 | 新旧规则未兼容 | 加版本号判断，保留兼容窗口 |
| 签名值大小写不一致 | MD5结果转大写/小写不统一 | 统一转小写或大小写不敏感比较 |
4.5 从日志里捞证据：一条合格签名请求的日志长什么样
在联调和线上排查中，最忌讳的是“靠猜”。我的习惯是签名相关的请求必须打印完整链路日志。一条合格的日志至少包含以下信息：
[签名验签] path=/api/order/create raw_query=amount=100&name=张三&orderId=20240606001&nonce=xxx×tamp=1717600000&sign=abc123 signed_string=amount=100&name=张三&orderId=20240606001&nonce=xxx×tamp=1717600000&key=****** client_sign=abc123 server_sign=def456 result=fail注意key字段必须打码，不能把密钥明文打到日志里。如果发现client_sign和server_sign不一致，先对比signed_string，这一步能筛掉90%的问题。如果signed_string完全一致但MD5结果不同，就检查两边是否是同一个UTF-8字节序列，用Hex.encodeHexString(raw.getBytes(UTF_8).toHexString())打印十六进制对比。
5. 从MD5+UTF-8到更稳的进阶方案
5.1 MD5的碰撞风险与适用边界
前面我承认过MD5有理论上的碰撞风险，学术界也早就有构造碰撞的方法。但要换个角度想：MD5碰撞攻击的应用场景是“我预谋生成两个内容不同但MD5相同的文件，用来做数字证书伪造”，也就是攻击者是可以选择输入内容的。而API签名场景里，参数值大部分是业务数据，攻击者能控制的是他传入的value，但他拿不到密钥，连签名值都拼不出来，“输入可控”换来还是算不出合法签名，所以实际的利用难度极高。
这也让很多业务系统在经历多年生产验证后仍然选择MD5做签名，就是一种“够用就好”的工程权衡。但如果你的接口涉及资金、积分、大额交易，或者有合规审计要求，建议直接上HMAC-SHA256。
5.2 HMAC-SHA256：多一份安全性、代码改动又不大
HMAC-SHA256是一种基于密钥的哈希消息认证码，它的特点是把密钥和消息混合后多次迭代哈希，输出256位摘要。它比MD5安全性高几个量级，而且实现复杂度基本相当。
以Java为例：
Mac mac = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); mac.init(secretKeySpec); byte[] raw = mac.doFinal(originalString.getBytes(StandardCharsets.UTF_8)); String sign = HexUtil.encodeHexString(raw);注意HMAC的原始串只需要把参数排序拼好，不需要再手动拼&key=xxx，因为密钥已经传入SecretKeySpec。期待一下这个改动：参与签名参数的排序规则、时间戳、nonce机制可以完全不变，只有“拼接密钥方式”和“摘要函数”两处变化，迁移成本很低。
5.3 更完整的一层防护：签名+HTTPS+鉴权+限流
签名这套机制解决的是“参数没有被篡改、来源基本可信”，但完整的API安全不能只靠签名。我在实际项目中通常会配合下面几层：
- 传输安全：强制HTTPS，防止最基础的窃听
- 身份认证：OAuth2 Token、JWT等方式确认“是谁在调用”
- 签名防篡改：本文这套MD5/HMAC机制
- 幂等性控制：交易类接口要求
requestId全局唯一 - 限流：按IP、按用户维度限制单时间窗口调用次数
- 审计日志：所有带敏感操作的请求记录完整链路
每一层解决一个问题，签名不是万能的，它只是把最底层的“裸奔”状态解除掉。
最后再分享一点经验
签名联调失败的时候，冷静下来第一步永远是对“签名原文”。两边日志打印出来左边拼好、右边拼好，一个字符一个字符对比，什么问题都藏不住。不要一上来就怀疑MD5算法实现有问题，MD5在全世界跑了好几十年，你不是那个例外。
另外，我踩过很深的坑是业务参数序列化顺序。如果你用JSON传参并要求签名，服务端解析成Map再排序拼接，而客户端用字符串直接拼接，两边即使key一样，value里如果有一层嵌套JSON，那嵌套JSON内部key的顺序也可能会被框架重排。这种情况一定要约定“签名原文使用原始JSON字符串逐层拼接”，或者干脆要求“参与签名的字段都是单层键值对，拒绝嵌套对象”。我自己做开放平台API时直接规定：参与签名的参数不允许为JSON对象，一律打平成key=value的字符串，彻底规避这类问题。
这套MD5+UTF-8方案虽然简单，但把编码、排序、密钥、时间戳、nonce每个环节都做到位，你就能交付一个在生产环境稳定跑几年的签名模块。下次有人再跟你说“MD5过时了不能用”，你可以笑着回一句：签名场景看的是密钥安全性，不是摘要算法江湖排位。
