尧图网站建设 
开放接口这东西只要涉及对外合作基本都绕不开。你把接口暴露给第三方系统、H5 页面、小程序或者给合作方的服务端调用就等于把自家后门开在了马路边上。这时候最直接的问题就来了我怎么知道这个请求到底是谁发过来的参数有没有被人中途改过同一个请求会不会被反复重放一百遍我做过不少这类对接早期用过最简单的白名单 IP 加固定 token结果被合作方开发同学一不小心把 token 写进了前端 JS 里第二天日志就能看到陌生 IP 拿着这个 token 在刷我们的订单查询接口。后来换成 spring 开放接口的签名认证方案用拦截器统一收口一直用到现在都挺稳。这篇就把这套基于 spring 拦截器的签名认证方案从头到尾讲透包括签名规则怎么定、参数怎么拼、防重放怎么做、body 只能读一次的坑怎么绕、上线后怎么排查签名失败。适合正在做对外接口对接的后端同学也适合刚接触开放平台鉴权的初中级开发者。1. 开放接口的签名认证到底在防什么很多人一上来就问“签名怎么算”其实先想清楚要防什么方案自然就出来了。签名认证不是为了让接口变得高深它解决的是三个非常具体的问题身份不可伪造、内容不可篡改、请求不可重放。这三件事搞明白了代码只是把逻辑翻译成 Java 而已。1.1 从两个真实场景说起第一个场景是参数被篡改。我们有个合作方调用充值回调接口参数是userId和amount。当时只做了简单的 token 校验结果对方的技术人员用抓包工具改了一下amount把 100 改成 10000服务端照样通过。问题出在哪儿token 只证明了“你是谁”但没有证明“这份参数是不是你发的”。签名的作用就是给整份参数做一个指纹任何一位参数变化指纹立刻对不上。第二个场景是请求被重放。签名本身并不能防止重放因为攻击者可以把整个请求原封不动地复制一份再发一次签名依然是对的。所以签名方案里必须搭配时间戳和随机数让同一个签名只能在一定时间窗口内、且只能使用一次。我见过有团队只做了签名没做防重放结果支付回调接口被同一个请求重放了十几次幸好业务侧有幂等兜底才没出事。注意签名和防重放是两个独立机制缺一不可。只做签名等于只贴了封条没锁门。1.2 三种常见鉴权方式的取舍在做技术选型的时候我把三种主流方式摆在一起对比过结论是开放接口场景下签名认证基本没有替代品。鉴权方式典型实现是否防篡改是否防重放适合场景Session/Cookie容器 Session否否同域内部后台系统Token/JWT请求头携带 JWT否JWT 只签自身头部载荷否前后端分离、用户态接口签名认证appId secret sign是全参数参与是配合时间戳随机数对外开放接口、服务端对接JWT 的签名保护的是 token 内部那几个字段它管不到业务参数。你把 userId 写在 JWT 里没问题但如果你同时还在 URL 上传了 orderId攻击者照样能改 orderId。开放接口的参数形态千变万化把这些参数全部纳入签名才是一劳永逸的做法。1.3 为什么把校验放在拦截器这一层能实现统一校验的位置有很多Filter、Interceptor、AOP、网关。选拦截器有几个很实在的理由。第一拦截器能拿到HandlerMethod。这一点非常关键意味着我可以通过自定义注解做细粒度控制哪个方法要校验、哪个方法不要、用哪个版本的签名规则全都能在方法上标注而 Filter 拿不到这些信息只能靠 URL 规则猜。第二拦截器在 DispatcherServlet 之内异常会走 Spring 的统一异常处理链路我可以直接抛业务异常交给RestControllerAdvice转成标准 JSON 返回格式统一、处理优雅。Filter 里抛异常就得自己写 response很别扭。第三Filter 在拦截器之前参数解析都还没发生想读RequestBody的 JSON 体很麻烦。当然如果 body 要参与签名还是得在最外层套一个包装器这是后面要专门讲的坑。总结一下主体校验逻辑放拦截器body 缓存放 Filter两者配合才是完整方案。2. 签名规则设计先定标准再写代码签名认证最怕的就是“服务端写一套、客户端猜一套”。我踩过的最大的坑就是规则没写清楚对接方那边按自己的理解拼了一遍签名死活对不上来回扯了两天。所以这部分不是写代码是写规范。2.1 参与签名的参数清单与排序规则我是这么定的简单粗暴且不留歧义所有 query 参数、form 表单参数全部参与签名请求头中的X-App-Id、X-Timestamp、X-Nonce三个字段参与签名如果请求体是 JSON则对 body 原文做 SHA-256 摘要摘要值以参数名_bodyDigest参与签名参数名为sign、signType的字段一律排除值为null或空字符串的参数一律排除所有参数按参数名 ASCII 码升序排列后拼接。为什么按 ASCII 升序因为这是唯一不需要额外约定的排序方式。你按参数出现顺序排客户端和服务端拿到的顺序可能不一致你按字母表排中文参数名的排序规则又会有分歧。ASCII 升序是确定性的任何语言实现结果都一样。关于空值排除这里要特别强调一次ab1和b1的签名结果必须一致。如果服务端排除了空值而客户端没排除签名必错。我在对接文档里会把这条加粗写清楚因为它是最容易出错的地方。public static String buildSignContent(MapString, String params) { TreeMapString, String sorted new TreeMap(params); StringBuilder sb new StringBuilder(256); for (Map.EntryString, String entry : sorted.entrySet()) { String key entry.getKey(); String value entry.getValue(); // 排除签名相关字段 if (sign.equalsIgnoreCase(key) || signType.equalsIgnoreCase(key)) { continue; } // 排除空值 if (value null || value.isEmpty()) { continue; } if (sb.length() 0) { sb.append(); } sb.append(key).append().append(value); } return sb.toString(); }用TreeMap而不是手动 sort是因为TreeMap的 key 比较用的是String.compareTo也就是 Unicode 码点升序对纯 ASCII 参数名来说等价于 ASCII 升序天然满足要求。2.2 签名串拼接与摘要算法选型拼接好参数串之后还要不要把 secret 拼进去这里有两种流派我都用过分享一下差异。方案 AMD5 加盐是很多老平台的做法sign MD5(参数串 key appSecret)。优点是实现简单任何语言都有 MD5。缺点是 MD5 本身抗碰撞能力已经不被推荐而且任何一点的实现差异都会导致结果不同。方案 BHMAC-SHA256是我现在推荐的sign HMAC_SHA256(参数串, appSecret)。secret 作为 HMAC 的密钥使用不需要拼进明文串抗长度扩展攻击安全性明显更好。算法输出长度性能安全性建议MD532 位十六进制最快已不推荐只用于兼容老客户端SHA-140 位十六进制快不推荐不建议使用SHA-25664 位十六进制较快好可用于 body 摘要HMAC-SHA25664 位十六进制较快最好首选实测下来HMAC-SHA256 对单次请求的开销在微秒级别即使 QPS 上千也完全不是瓶颈。真正需要关注性能的反而是 Redis 的 nonce 校验这个后面讲。2.3 时间戳、随机数与防重放窗口时间戳我规定为毫秒级 Unix 时间戳服务端允许的偏移窗口是 ±5 分钟。为什么是 5 分钟这个数字是权衡出来的太短比如 30 秒服务器之间哪怕有一点点时钟漂移就会大面积失败太长比如 1 小时攻击者可重放的窗口就变大了。5 分钟是我在多个项目里验证过的比较舒服的值。随机数我用 UUID 去掉横杠32 位字符串。服务端拿到之后做两件事一是检查这个 nonce 在 Redis 里是否已经存在存在就直接拒绝二是如果不存在以openapi:nonce:{appId}:{nonce}为 key 写入 Redis过期时间设为 600 秒。为什么过期时间要设成时间窗口的两倍因为一个请求只要在 5 分钟窗口内有效那么 10 分钟之后这个 nonce 就算重复了也过不了时间戳校验缓存自然可以释放。设两倍窗口是给自己留了余量避免边界情况下误判。String nonceKey openapi:nonce: appId : nonce; Boolean firstUse stringRedisTemplate.opsForValue() .setIfAbsent(nonceKey, 1, Duration.ofSeconds(600)); if (!Boolean.TRUE.equals(firstUse)) { throw new OpenApiAuthException(401004, 请求已被使用疑似重放); }用setIfAbsent一条命令搞定“判断 写入”天然原子不需要先 get 再 set避免了并发下的竞态。注意nonce 缓存一定要放在 Redis 这类共享存储里不能放本地缓存。多实例部署时本地缓存会导致同一个 nonce 在不同节点上各通过一次防重放就失效了。2.4 请求头规范化约定请求头字段名如果各写各的联调时大小写、拼写对不上就白白浪费时间。我的做法是在文档里用一张表定死。请求头是否必填示例值说明X-App-Id是202401150001应用标识由平台分配X-Timestamp是1705305600000毫秒级时间戳X-Nonce是8f3c2b1a9d4e4f7ab6c532 位随机串X-Sign是9d1a...64 位HMAC-SHA256 结果小写十六进制X-Sign-Type否HMACSHA256多算法并存时使用默认 HMACSHA256签名值统一转小写十六进制比较时也统一转小写不要一半大写一半小写。这个细节看着小但真的有团队因为客户端输出大写、服务端按小写比较导致全线报错。3. Spring 拦截器方式的完整落地规则定完了接下来就是把这套东西落到 spring 项目里。我按实际工程顺序走一遍从依赖到注册每一段都能直接抄。3.1 工程结构与依赖我用的 Spring Boot 3.2 加 JDK 17依赖很干净不需要引入任何安全框架dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependency包结构我习惯这样分openapi ├── annotation OpenApiSign 注解 ├── config WebMvcConfig 注册拦截器 ├── filter CachedBodyFilter 请求体缓存 ├── interceptor SignAuthInterceptor 签名校验 ├── support SignUtil、OpenApiContext ├── exception OpenApiAuthException、全局异常处理 └── repository AppSecretRepository 密钥查询分包的核心逻辑是注解放最上面工具类和上下文放 support拦截器只做编排密钥查询单独抽出接口方便后面换成数据库或者配置中心而不动主流程。3.2 自定义注解 OpenApiSign我不喜欢用 URL 前缀去判断哪些接口需要校验因为业务迭代时路径很容易改。注解挂在方法上改动最少语义也最清晰。Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) Documented public interface OpenApiSign { /** 是否需要校验 body 摘要默认 false */ boolean checkBody() default false; /** 允许的时间偏移单位秒默认 300 */ long maxOffsetSeconds() default 300; /** 是否校验 nonce 防重放默认 true */ boolean checkNonce() default true; }为什么把checkBody做成开关因为文件上传、大报文推送这类接口把 body 纳入签名会带来额外的内存和 CPU 开销而且很多时候业务本身已经有幂等和校验了。留个开关按需开启而不是一刀切。3.3 签名工具类实现工具类我写成无状态的静态方法不依赖 Spring 容器这样单元测试也方便。public final class SignUtil { private static final char[] HEX 0123456789abcdef.toCharArray(); private SignUtil() { } public static String buildSignContent(MapString, String params) { // 见 2.1 节实现 } /** HMAC-SHA256输出小写十六进制 */ public static String hmacSha256(String content, String secret) { try { Mac mac Mac.getInstance(HmacSHA256); mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), HmacSHA256)); return toHex(mac.doFinal(content.getBytes(StandardCharsets.UTF_8))); } catch (GeneralSecurityException e) { throw new IllegalStateException(签名计算失败, e); } } /** 恒定时间比较防时序攻击 */ public static boolean safeEquals(String a, String b) { if (a null || b null) { return false; } return MessageDigest.isEqual( a.getBytes(StandardCharsets.UTF_8), b.getBytes(StandardCharsets.UTF_8)); } private static String toHex(byte[] bytes) { char[] out new char[bytes.length * 2]; for (int i 0; i bytes.length; i) { int v bytes[i] 0xFF; out[i * 2] HEX[v 4]; out[i * 2 1] HEX[v 0x0F]; } return new String(out); } }safeEquals这里用MessageDigest.isEqual而不是String.equals是因为普通字符串比较会在第一个不同字符处返回理论上可以通过响应时间差反推正确签名。虽然开放接口场景下这种攻击难度很高但改一行代码的事顺手做了更放心。3.4 拦截器主体实现拦截器是整个方案的核心我把它拆成几个私有方法每一步失败都对应一个明确的错误码方便排查。Component public class SignAuthInterceptor implements HandlerInterceptor { private static final String NONCE_KEY_PREFIX openapi:nonce:; private static final int NONCE_EXPIRE_SECONDS 600; Resource private AppSecretRepository appSecretRepository; Resource private StringRedisTemplate stringRedisTemplate; Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { if (!(handler instanceof HandlerMethod handlerMethod)) { return true; } OpenApiSign annotation handlerMethod.getMethodAnnotation(OpenApiSign.class); if (annotation null) { annotation handlerMethod.getBeanType().getAnnotation(OpenApiSign.class); } if (annotation null) { return true; } String appId request.getHeader(X-App-Id); String timestamp request.getHeader(X-Timestamp); String nonce request.getHeader(X-Nonce); String sign request.getHeader(X-Sign); if (isBlank(appId) || isBlank(timestamp) || isBlank(nonce) || isBlank(sign)) { throw new OpenApiAuthException(401001, 缺少必要的签名请求头); } long ts; try { ts Long.parseLong(timestamp); } catch (NumberFormatException e) { throw new OpenApiAuthException(401006, 时间戳格式非法); } long offset Math.abs(System.currentTimeMillis() - ts); if (offset annotation.maxOffsetSeconds() * 1000L) { throw new OpenApiAuthException(401003, 时间戳已过期请校准服务器时间); } String appSecret appSecretRepository.findSecret(appId); if (appSecret null) { throw new OpenApiAuthException(401002, appId 不存在或已停用); } if (annotation.checkNonce() !tryAcquireNonce(appId, nonce)) { throw new OpenApiAuthException(401004, 请求已被使用疑似重放); } MapString, String params collectParams(request, annotation); String content SignUtil.buildSignContent(params); String expected SignUtil.hmacSha256(content, appSecret); if (!SignUtil.safeEquals(expected, sign.toLowerCase())) { log.warn(签名校验失败 appId{} uri{} content{}, appId, request.getRequestURI(), content); throw new OpenApiAuthException(401005, 签名校验失败); } OpenApiContext.set(appId); return true; } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { // 必须清理否则线程池复用时会串数据 OpenApiContext.clear(); } private boolean tryAcquireNonce(String appId, String nonce) { String key NONCE_KEY_PREFIX appId : nonce; Boolean first stringRedisTemplate.opsForValue() .setIfAbsent(key, 1, Duration.ofSeconds(NONCE_EXPIRE_SECONDS)); return Boolean.TRUE.equals(first); } }afterCompletion里的OpenApiContext.clear()一定要写。我们用的是 Tomcat 线程池线程会被复用如果 ThreadLocal 不清理下一个请求可能读到上一个请求的 appId这种问题排查起来极其痛苦我之前在灰度环境里就吃过一次亏日志里出现了 A 应用的请求带着 B 应用的 appId。3.5 请求体只能读一次这个坑怎么绕如果 body 要参与签名就必须解决 Servlet 输入流只能读一次的问题。拦截器在preHandle阶段读 body读完之后 Controller 里的RequestBody就会拿到一个空流直接报Required request body is missing。正确做法是加一个 Filter在请求进入 DispatcherServlet 之前就把 body 读进字节数组然后包装成可以反复读取的包装类。public class CachedBodyHttpServletRequest extends HttpServletRequestWrapper { private final byte[] body; public CachedBodyHttpServletRequest(HttpServletRequest request) throws IOException { super(request); this.body StreamUtils.copyToByteArray(request.getInputStream()); } Override public ServletInputStream getInputStream() { ByteArrayInputStream in new ByteArrayInputStream(body); return new ServletInputStream() { Override public boolean isFinished() { return in.available() 0; } Override public boolean isReady() { return true; } Override public void setReadListener(ReadListener listener) { throw new UnsupportedOperationException(); } Override public int read() { return in.read(); } }; } Override public BufferedReader getReader() { return new BufferedReader(new InputStreamReader( new ByteArrayInputStream(body), StandardCharsets.UTF_8)); } public byte[] getBody() { return body; } }Filter 里只对 JSON 请求做包装并且加上大小限制Component public class CachedBodyFilter extends OncePerRequestFilter { private static final long MAX_BODY_SIZE 1024 * 1024L; Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { String contentType request.getContentType(); boolean needCache contentType ! null contentType.toLowerCase().contains(application/json) request.getContentLengthLong() 0 request.getContentLengthLong() MAX_BODY_SIZE; if (needCache) { chain.doFilter(new CachedBodyHttpServletRequest(request), response); } else { chain.doFilter(request, response); } } }注意这个包装器绝对不能用在multipart/form-data文件上传上。把整个文件读进内存一个不小心就是 OOM。所以我在 Filter 里用 Content-Type 做了严格白名单只处理 JSON 且限定了 1MB 上限。拦截器里取 body 摘要就简单了private String resolveBodyDigest(HttpServletRequest request, OpenApiSign annotation) { if (!annotation.checkBody() || !(request instanceof CachedBodyHttpServletRequest wrapper)) { return null; } byte[] body wrapper.getBody(); if (body.length 0) { return null; } return DigestUtils.sha256Hex(body); }客户端在签名时也要对同一份 body 原文做 SHA-256把结果作为_bodyDigest参数塞进待签串。只要客户端和服务端用的是同一份字节摘要就必然一致。3.6 注册拦截器与路径排除Configuration public class OpenApiWebConfig implements WebMvcConfigurer { Resource private SignAuthInterceptor signAuthInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(signAuthInterceptor) .addPathPatterns(/openapi/**) .excludePathPatterns( /openapi/public/**, /openapi/health, /openapi/callback/pay // 第三方回调一般用另外的验签方式 ) .order(1); } }这里我做了双保险路径只限/openapi/**避免误伤内部接口同时方法上必须带OpenApiSign注解才真正校验。这样即使有人不小心把内部接口挂到了/openapi/路径下没有注解也不会被拦安全性和可控性都更好。3.7 appId 与 secret 的多应用管理密钥不能写死在配置文件里一是轮换麻烦二是每个人的开发环境都要改配置。我的做法是存数据库加本地缓存。表结构很简单字段类型说明app_idvarchar(32)应用标识唯一索引app_secretvarchar(64)密钥建议加密存储app_namevarchar(64)应用名称statustinyint1 启用 0 停用expire_atdatetime密钥过期时间查询层加一层短缓存缓存时间 60 秒。为什么不缓存太久因为万一某个 appId 被判定为风险要紧急停用60 秒内生效是可以接受的缓存半小时就太久了。如果对时效性要求更高可以用 Redis 发布订阅做主动失效。3.8 客户端签名调用示例服务端写完了客户端这边我用 Java 和 JavaScript 各给一个例子因为对接方基本就这两种。Java 客户端public class OpenApiClient { private final String appId; private final String appSecret; public OpenApiClient(String appId, String appSecret) { this.appId appId; this.appSecret appSecret; } public String post(String url, String jsonBody) { long ts System.currentTimeMillis(); String nonce UUID.randomUUID().toString().replace(-, ); MapString, String params new LinkedHashMap(); params.put(X-App-Id, appId); params.put(X-Timestamp, String.valueOf(ts)); params.put(X-Nonce, nonce); if (jsonBody ! null !jsonBody.isEmpty()) { params.put(_bodyDigest, DigestUtils.sha256Hex( jsonBody.getBytes(StandardCharsets.UTF_8))); } String content SignUtil.buildSignContent(params); String sign SignUtil.hmacSha256(content, appSecret); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.set(X-App-Id, appId); headers.set(X-Timestamp, String.valueOf(ts)); headers.set(X-Nonce, nonce); headers.set(X-Sign, sign); return new RestTemplate().exchange( url, HttpMethod.POST, new HttpEntity(jsonBody, headers), String.class).getBody(); } }JavaScript 版本Node 环境浏览器端请勿存放 secretconst crypto require(crypto); function buildSign(params, secret) { const keys Object.keys(params) .filter(k k ! sign k ! signType) .filter(k params[k] ! null params[k] ! ) .sort(); const content keys.map(k ${k}${params[k]}).join(); return crypto.createHmac(sha256, secret).update(content, utf8).digest(hex); }这里面有个细节要提醒对接方Object.keys默认就是插入顺序但排序之后才是 ASCII 升序一定要显式调用.sort()不要依赖默认顺序。4. 联调、自测与排查实录方案上线只是开始真正耗时的是联调和对线上问题的排查。这部分我把自己积累的经验都倒出来能帮对接方少走很多弯路。4.1 服务端自测单元测试与 Postman 脚本单元测试的重点是把签名规则固化成断言任何人改了拼接逻辑都会立刻失败。Test void buildSignContent_shouldSortAndDropBlank() { MapString, String params new HashMap(); params.put(b, 2); params.put(a, 1); params.put(c, ); params.put(sign, xxx); String content SignUtil.buildSignContent(params); assertEquals(a1b2, content); }Postman 那边用 Pre-request Script 自动算签名联调效率能提升一大截const appId pm.environment.get(appId); const secret pm.environment.get(appSecret); const ts Date.now().toString(); const nonce CryptoJS.lib.WordArray.random(16).toString(); const params { X-App-Id: appId, X-Timestamp: ts, X-Nonce: nonce }; const keys Object.keys(params).sort(); const content keys.map(k k params[k]).join(); const sign CryptoJS.HmacSHA256(content, secret).toString(); pm.request.headers.add({ key: X-App-Id, value: appId }); pm.request.headers.add({ key: X-Timestamp, value: ts }); pm.request.headers.add({ key: X-Nonce, value: nonce }); pm.request.headers.add({ key: X-Sign, value: sign });把这段脚本贴进 Postman以后每次改参数都不用手动重算签名对接方那边也能直接复制省掉大量沟通成本。4.2 签名失败排查顺序表签名失败是最高频的问题我整理了一份排查顺序按这个顺序走基本十分钟内能定位。顺序检查项典型现象定位方法1请求头是否齐全401001抓包看 Header2appId 是否正确、是否启用401002查管理后台应用状态3服务器与客户端时间差401003对比两端date命令输出4nonce 是否重复401004检查客户端是否用了固定值5参数排序是否一致401005打印服务端待签串与客户端对比6空值处理是否一致401005检查客户端是否过滤了空值7body 摘要是否一致401005对比两侧 SHA-256 结果8字符编码是否一致401005确认双方都用 UTF-8关键技巧在这里服务端打日志的时候一定要把待签串content打出来但不要打 secret。这样对接方把他那边的待签串发过来两边一对比哪个参数多了、少了、顺序不同一眼就能看出来。我们统计过80% 的签名失败都是待签串不一致而不是算法问题。4.3 高频坑点与避坑心得第一个坑是 URL 编码。如果参数值里有中文或者特殊字符客户端先 URL 解码再拼接、还是先拼接再编码结果完全不同。我的规则是取原始值参与签名不做任何 URL 编码。服务端拿到的参数是容器已经解码过的两边保持一致。第二个坑是时间戳精度。有的客户端传秒级时间戳有的传毫秒级。文档里必须写死毫秒并且在服务端做长度校验如果发现是 10 位数字就直接拒绝并提示比等到签名对不上再排查要快得多。第三个坑是十六进制大小写。前面提过一次这里再强调输出统一小写服务端比较前先toLowerCase()双保险。第四个坑是 Spring Boot 的HiddenHttpMethodFilter。如果你用了表单方式的_method参数它会改写请求方法但参数集合也会受影响签名时要注意排除这个内部参数。我现在的做法是直接禁止_method参数出现在开放接口里。第五个坑是网关层的重复读取。如果前面挂了 Nginx 或者网关某些配置会提前消费请求体导致 Filter 读到空 body。上线前一定要在完整链路里跑一次带 body 签名的请求别只在本地 8080 端口测通了就上。实操心得给对接方提供一个“签名调试接口”非常值。把他们的 appId、待签串、签名值传过来服务端只做一次校验并把内部期望值返回不开任何权限对接方自助定位问题能省下你至少一半的答疑时间。4.4 性能与安全加固性能方面真正需要优化的是 Redis 那一跳。我做过压测单机 QPS 3000 的情况下Redis 的 nonce 校验占了整个链路耗时的六成以上。优化手段有两个一是用 Redis Pipeline 或者 Lua 脚本把校验和写入合并成一次网络往返二是把 nonce 的存储换成 Redis Cluster 并且和应用部署在同一可用区把网络延迟压到 1 毫秒以内。安全方面有几条我认为必须做的secret 在数据库里加密存储不要明文日志里绝对不能出现 secret 和完整签名值appId 支持一键停用且缓存 60 秒内生效secret 支持双密钥并存方便平滑轮换接口加上频率限制防止拿到合法签名后暴力刷接口。关于密钥轮换我多说一句。切换的时候不要直接改 secret因为对接方还在用旧的一改就是全线报错。做法是同时保留新旧两个 secret服务端校验时两个都试一遍都通过就用新的那个等对接方全部迁移完再删掉旧的。过渡期我一般给两周。5. 从单应用走向平台后续可扩展的方向单应用接入几个合作方用拦截器这套足够了。但如果合作方数量上到几十个或者公司内部已经有统一的 API 网关就需要考虑架构上的演进。5.1 把签名校验下沉到网关当接入方数量变多每新增一个业务应用都要复制一遍拦截器代码维护成本就上来了。这时候更合理的做法是把签名校验做成网关插件网关统一完成 appId 校验、时间戳校验、防重放和签名验证校验通过后把X-App-Id透传到后端服务后端只信任来自网关的流量。这样做还有一个额外好处nonce 的 Redis 操作只在网关做一次后端服务完全不用操心防重放性能也更好。需要注意的是后端服务要做好来源限制只接受网关的 IP 访问否则绕过网关直接打后端就把整个校验体系废掉了。什么阶段适合下沉我的经验是接入方超过 10 个或者公司已经有两套以上业务系统需要对外开放就该考虑统一网关了。5.2 响应体签名与防篡改目前只做了请求方向的签名如果对安全性要求更高响应方向也可以做。做法是服务端在返回时对响应体算一次 HMAC放到响应头X-Resp-Sign里。客户端拿到之后用同样的方式验一遍确认返回数据没有被中间环节篡改。这个在很多金融、支付类的开放平台是标配。实现上可以放在ResponseBodyAdvice里拦截所有标注了OpenApiSign的返回值统一加签。要注意的是加签之后响应体内容就不能再被其他 Advice 修改了执行顺序要排在最后。5.3 密钥轮换与灰度切换密钥轮换不是一个技术问题而是一个流程问题。我总结的流程是这样的先在管理后台生成新密钥此时新旧并存通知对接方切换服务端在过渡期内两个都接受观察日志里新密钥的使用比例当旧密钥连续 7 天没有调用记录后在管理后台标记待删除最后删除。日志记录里我会记下“命中密钥版本”这样切换进度一目了然。没有这个记录你根本不知道对接方到底切没切。5.4 一些放在最后面的经验签名认证这套东西代码本身其实不难难的是把规则讲清楚、把边界情况都覆盖到。我的建议是第一版就把签名调试工具、详细的错误码文档、可复制的 Postman 脚本一起交付给对接方让他们能自助解决问题。这三样东西的价值在实际对接过程中比多写几百行代码要大得多。另外不要一开始就追求完美。我见过有团队想一步到位做国密算法、做证书双向认证结果方案拖了两个月还没上线合作方那边等不及了。先用 HMAC-SHA256 把基础方案跑通安全等级够用后续有明确需求再升级这个节奏更符合实际。 基于Spring拦截器的开放接口签名认证与防重放方案
开放接口这东西只要涉及对外合作基本都绕不开。你把接口暴露给第三方系统、H5 页面、小程序或者给合作方的服务端调用就等于把自家后门开在了马路边上。这时候最直接的问题就来了我怎么知道这个请求到底是谁发过来的参数有没有被人中途改过同一个请求会不会被反复重放一百遍我做过不少这类对接早期用过最简单的白名单 IP 加固定 token结果被合作方开发同学一不小心把 token 写进了前端 JS 里第二天日志就能看到陌生 IP 拿着这个 token 在刷我们的订单查询接口。后来换成 spring 开放接口的签名认证方案用拦截器统一收口一直用到现在都挺稳。这篇就把这套基于 spring 拦截器的签名认证方案从头到尾讲透包括签名规则怎么定、参数怎么拼、防重放怎么做、body 只能读一次的坑怎么绕、上线后怎么排查签名失败。适合正在做对外接口对接的后端同学也适合刚接触开放平台鉴权的初中级开发者。1. 开放接口的签名认证到底在防什么很多人一上来就问“签名怎么算”其实先想清楚要防什么方案自然就出来了。签名认证不是为了让接口变得高深它解决的是三个非常具体的问题身份不可伪造、内容不可篡改、请求不可重放。这三件事搞明白了代码只是把逻辑翻译成 Java 而已。1.1 从两个真实场景说起第一个场景是参数被篡改。我们有个合作方调用充值回调接口参数是userId和amount。当时只做了简单的 token 校验结果对方的技术人员用抓包工具改了一下amount把 100 改成 10000服务端照样通过。问题出在哪儿token 只证明了“你是谁”但没有证明“这份参数是不是你发的”。签名的作用就是给整份参数做一个指纹任何一位参数变化指纹立刻对不上。第二个场景是请求被重放。签名本身并不能防止重放因为攻击者可以把整个请求原封不动地复制一份再发一次签名依然是对的。所以签名方案里必须搭配时间戳和随机数让同一个签名只能在一定时间窗口内、且只能使用一次。我见过有团队只做了签名没做防重放结果支付回调接口被同一个请求重放了十几次幸好业务侧有幂等兜底才没出事。注意签名和防重放是两个独立机制缺一不可。只做签名等于只贴了封条没锁门。1.2 三种常见鉴权方式的取舍在做技术选型的时候我把三种主流方式摆在一起对比过结论是开放接口场景下签名认证基本没有替代品。鉴权方式典型实现是否防篡改是否防重放适合场景Session/Cookie容器 Session否否同域内部后台系统Token/JWT请求头携带 JWT否JWT 只签自身头部载荷否前后端分离、用户态接口签名认证appId secret sign是全参数参与是配合时间戳随机数对外开放接口、服务端对接JWT 的签名保护的是 token 内部那几个字段它管不到业务参数。你把 userId 写在 JWT 里没问题但如果你同时还在 URL 上传了 orderId攻击者照样能改 orderId。开放接口的参数形态千变万化把这些参数全部纳入签名才是一劳永逸的做法。1.3 为什么把校验放在拦截器这一层能实现统一校验的位置有很多Filter、Interceptor、AOP、网关。选拦截器有几个很实在的理由。第一拦截器能拿到HandlerMethod。这一点非常关键意味着我可以通过自定义注解做细粒度控制哪个方法要校验、哪个方法不要、用哪个版本的签名规则全都能在方法上标注而 Filter 拿不到这些信息只能靠 URL 规则猜。第二拦截器在 DispatcherServlet 之内异常会走 Spring 的统一异常处理链路我可以直接抛业务异常交给RestControllerAdvice转成标准 JSON 返回格式统一、处理优雅。Filter 里抛异常就得自己写 response很别扭。第三Filter 在拦截器之前参数解析都还没发生想读RequestBody的 JSON 体很麻烦。当然如果 body 要参与签名还是得在最外层套一个包装器这是后面要专门讲的坑。总结一下主体校验逻辑放拦截器body 缓存放 Filter两者配合才是完整方案。2. 签名规则设计先定标准再写代码签名认证最怕的就是“服务端写一套、客户端猜一套”。我踩过的最大的坑就是规则没写清楚对接方那边按自己的理解拼了一遍签名死活对不上来回扯了两天。所以这部分不是写代码是写规范。2.1 参与签名的参数清单与排序规则我是这么定的简单粗暴且不留歧义所有 query 参数、form 表单参数全部参与签名请求头中的X-App-Id、X-Timestamp、X-Nonce三个字段参与签名如果请求体是 JSON则对 body 原文做 SHA-256 摘要摘要值以参数名_bodyDigest参与签名参数名为sign、signType的字段一律排除值为null或空字符串的参数一律排除所有参数按参数名 ASCII 码升序排列后拼接。为什么按 ASCII 升序因为这是唯一不需要额外约定的排序方式。你按参数出现顺序排客户端和服务端拿到的顺序可能不一致你按字母表排中文参数名的排序规则又会有分歧。ASCII 升序是确定性的任何语言实现结果都一样。关于空值排除这里要特别强调一次ab1和b1的签名结果必须一致。如果服务端排除了空值而客户端没排除签名必错。我在对接文档里会把这条加粗写清楚因为它是最容易出错的地方。public static String buildSignContent(MapString, String params) { TreeMapString, String sorted new TreeMap(params); StringBuilder sb new StringBuilder(256); for (Map.EntryString, String entry : sorted.entrySet()) { String key entry.getKey(); String value entry.getValue(); // 排除签名相关字段 if (sign.equalsIgnoreCase(key) || signType.equalsIgnoreCase(key)) { continue; } // 排除空值 if (value null || value.isEmpty()) { continue; } if (sb.length() 0) { sb.append(); } sb.append(key).append().append(value); } return sb.toString(); }用TreeMap而不是手动 sort是因为TreeMap的 key 比较用的是String.compareTo也就是 Unicode 码点升序对纯 ASCII 参数名来说等价于 ASCII 升序天然满足要求。2.2 签名串拼接与摘要算法选型拼接好参数串之后还要不要把 secret 拼进去这里有两种流派我都用过分享一下差异。方案 AMD5 加盐是很多老平台的做法sign MD5(参数串 key appSecret)。优点是实现简单任何语言都有 MD5。缺点是 MD5 本身抗碰撞能力已经不被推荐而且任何一点的实现差异都会导致结果不同。方案 BHMAC-SHA256是我现在推荐的sign HMAC_SHA256(参数串, appSecret)。secret 作为 HMAC 的密钥使用不需要拼进明文串抗长度扩展攻击安全性明显更好。算法输出长度性能安全性建议MD532 位十六进制最快已不推荐只用于兼容老客户端SHA-140 位十六进制快不推荐不建议使用SHA-25664 位十六进制较快好可用于 body 摘要HMAC-SHA25664 位十六进制较快最好首选实测下来HMAC-SHA256 对单次请求的开销在微秒级别即使 QPS 上千也完全不是瓶颈。真正需要关注性能的反而是 Redis 的 nonce 校验这个后面讲。2.3 时间戳、随机数与防重放窗口时间戳我规定为毫秒级 Unix 时间戳服务端允许的偏移窗口是 ±5 分钟。为什么是 5 分钟这个数字是权衡出来的太短比如 30 秒服务器之间哪怕有一点点时钟漂移就会大面积失败太长比如 1 小时攻击者可重放的窗口就变大了。5 分钟是我在多个项目里验证过的比较舒服的值。随机数我用 UUID 去掉横杠32 位字符串。服务端拿到之后做两件事一是检查这个 nonce 在 Redis 里是否已经存在存在就直接拒绝二是如果不存在以openapi:nonce:{appId}:{nonce}为 key 写入 Redis过期时间设为 600 秒。为什么过期时间要设成时间窗口的两倍因为一个请求只要在 5 分钟窗口内有效那么 10 分钟之后这个 nonce 就算重复了也过不了时间戳校验缓存自然可以释放。设两倍窗口是给自己留了余量避免边界情况下误判。String nonceKey openapi:nonce: appId : nonce; Boolean firstUse stringRedisTemplate.opsForValue() .setIfAbsent(nonceKey, 1, Duration.ofSeconds(600)); if (!Boolean.TRUE.equals(firstUse)) { throw new OpenApiAuthException(401004, 请求已被使用疑似重放); }用setIfAbsent一条命令搞定“判断 写入”天然原子不需要先 get 再 set避免了并发下的竞态。注意nonce 缓存一定要放在 Redis 这类共享存储里不能放本地缓存。多实例部署时本地缓存会导致同一个 nonce 在不同节点上各通过一次防重放就失效了。2.4 请求头规范化约定请求头字段名如果各写各的联调时大小写、拼写对不上就白白浪费时间。我的做法是在文档里用一张表定死。请求头是否必填示例值说明X-App-Id是202401150001应用标识由平台分配X-Timestamp是1705305600000毫秒级时间戳X-Nonce是8f3c2b1a9d4e4f7ab6c532 位随机串X-Sign是9d1a...64 位HMAC-SHA256 结果小写十六进制X-Sign-Type否HMACSHA256多算法并存时使用默认 HMACSHA256签名值统一转小写十六进制比较时也统一转小写不要一半大写一半小写。这个细节看着小但真的有团队因为客户端输出大写、服务端按小写比较导致全线报错。3. Spring 拦截器方式的完整落地规则定完了接下来就是把这套东西落到 spring 项目里。我按实际工程顺序走一遍从依赖到注册每一段都能直接抄。3.1 工程结构与依赖我用的 Spring Boot 3.2 加 JDK 17依赖很干净不需要引入任何安全框架dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependency包结构我习惯这样分openapi ├── annotation OpenApiSign 注解 ├── config WebMvcConfig 注册拦截器 ├── filter CachedBodyFilter 请求体缓存 ├── interceptor SignAuthInterceptor 签名校验 ├── support SignUtil、OpenApiContext ├── exception OpenApiAuthException、全局异常处理 └── repository AppSecretRepository 密钥查询分包的核心逻辑是注解放最上面工具类和上下文放 support拦截器只做编排密钥查询单独抽出接口方便后面换成数据库或者配置中心而不动主流程。3.2 自定义注解 OpenApiSign我不喜欢用 URL 前缀去判断哪些接口需要校验因为业务迭代时路径很容易改。注解挂在方法上改动最少语义也最清晰。Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) Documented public interface OpenApiSign { /** 是否需要校验 body 摘要默认 false */ boolean checkBody() default false; /** 允许的时间偏移单位秒默认 300 */ long maxOffsetSeconds() default 300; /** 是否校验 nonce 防重放默认 true */ boolean checkNonce() default true; }为什么把checkBody做成开关因为文件上传、大报文推送这类接口把 body 纳入签名会带来额外的内存和 CPU 开销而且很多时候业务本身已经有幂等和校验了。留个开关按需开启而不是一刀切。3.3 签名工具类实现工具类我写成无状态的静态方法不依赖 Spring 容器这样单元测试也方便。public final class SignUtil { private static final char[] HEX 0123456789abcdef.toCharArray(); private SignUtil() { } public static String buildSignContent(MapString, String params) { // 见 2.1 节实现 } /** HMAC-SHA256输出小写十六进制 */ public static String hmacSha256(String content, String secret) { try { Mac mac Mac.getInstance(HmacSHA256); mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), HmacSHA256)); return toHex(mac.doFinal(content.getBytes(StandardCharsets.UTF_8))); } catch (GeneralSecurityException e) { throw new IllegalStateException(签名计算失败, e); } } /** 恒定时间比较防时序攻击 */ public static boolean safeEquals(String a, String b) { if (a null || b null) { return false; } return MessageDigest.isEqual( a.getBytes(StandardCharsets.UTF_8), b.getBytes(StandardCharsets.UTF_8)); } private static String toHex(byte[] bytes) { char[] out new char[bytes.length * 2]; for (int i 0; i bytes.length; i) { int v bytes[i] 0xFF; out[i * 2] HEX[v 4]; out[i * 2 1] HEX[v 0x0F]; } return new String(out); } }safeEquals这里用MessageDigest.isEqual而不是String.equals是因为普通字符串比较会在第一个不同字符处返回理论上可以通过响应时间差反推正确签名。虽然开放接口场景下这种攻击难度很高但改一行代码的事顺手做了更放心。3.4 拦截器主体实现拦截器是整个方案的核心我把它拆成几个私有方法每一步失败都对应一个明确的错误码方便排查。Component public class SignAuthInterceptor implements HandlerInterceptor { private static final String NONCE_KEY_PREFIX openapi:nonce:; private static final int NONCE_EXPIRE_SECONDS 600; Resource private AppSecretRepository appSecretRepository; Resource private StringRedisTemplate stringRedisTemplate; Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { if (!(handler instanceof HandlerMethod handlerMethod)) { return true; } OpenApiSign annotation handlerMethod.getMethodAnnotation(OpenApiSign.class); if (annotation null) { annotation handlerMethod.getBeanType().getAnnotation(OpenApiSign.class); } if (annotation null) { return true; } String appId request.getHeader(X-App-Id); String timestamp request.getHeader(X-Timestamp); String nonce request.getHeader(X-Nonce); String sign request.getHeader(X-Sign); if (isBlank(appId) || isBlank(timestamp) || isBlank(nonce) || isBlank(sign)) { throw new OpenApiAuthException(401001, 缺少必要的签名请求头); } long ts; try { ts Long.parseLong(timestamp); } catch (NumberFormatException e) { throw new OpenApiAuthException(401006, 时间戳格式非法); } long offset Math.abs(System.currentTimeMillis() - ts); if (offset annotation.maxOffsetSeconds() * 1000L) { throw new OpenApiAuthException(401003, 时间戳已过期请校准服务器时间); } String appSecret appSecretRepository.findSecret(appId); if (appSecret null) { throw new OpenApiAuthException(401002, appId 不存在或已停用); } if (annotation.checkNonce() !tryAcquireNonce(appId, nonce)) { throw new OpenApiAuthException(401004, 请求已被使用疑似重放); } MapString, String params collectParams(request, annotation); String content SignUtil.buildSignContent(params); String expected SignUtil.hmacSha256(content, appSecret); if (!SignUtil.safeEquals(expected, sign.toLowerCase())) { log.warn(签名校验失败 appId{} uri{} content{}, appId, request.getRequestURI(), content); throw new OpenApiAuthException(401005, 签名校验失败); } OpenApiContext.set(appId); return true; } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { // 必须清理否则线程池复用时会串数据 OpenApiContext.clear(); } private boolean tryAcquireNonce(String appId, String nonce) { String key NONCE_KEY_PREFIX appId : nonce; Boolean first stringRedisTemplate.opsForValue() .setIfAbsent(key, 1, Duration.ofSeconds(NONCE_EXPIRE_SECONDS)); return Boolean.TRUE.equals(first); } }afterCompletion里的OpenApiContext.clear()一定要写。我们用的是 Tomcat 线程池线程会被复用如果 ThreadLocal 不清理下一个请求可能读到上一个请求的 appId这种问题排查起来极其痛苦我之前在灰度环境里就吃过一次亏日志里出现了 A 应用的请求带着 B 应用的 appId。3.5 请求体只能读一次这个坑怎么绕如果 body 要参与签名就必须解决 Servlet 输入流只能读一次的问题。拦截器在preHandle阶段读 body读完之后 Controller 里的RequestBody就会拿到一个空流直接报Required request body is missing。正确做法是加一个 Filter在请求进入 DispatcherServlet 之前就把 body 读进字节数组然后包装成可以反复读取的包装类。public class CachedBodyHttpServletRequest extends HttpServletRequestWrapper { private final byte[] body; public CachedBodyHttpServletRequest(HttpServletRequest request) throws IOException { super(request); this.body StreamUtils.copyToByteArray(request.getInputStream()); } Override public ServletInputStream getInputStream() { ByteArrayInputStream in new ByteArrayInputStream(body); return new ServletInputStream() { Override public boolean isFinished() { return in.available() 0; } Override public boolean isReady() { return true; } Override public void setReadListener(ReadListener listener) { throw new UnsupportedOperationException(); } Override public int read() { return in.read(); } }; } Override public BufferedReader getReader() { return new BufferedReader(new InputStreamReader( new ByteArrayInputStream(body), StandardCharsets.UTF_8)); } public byte[] getBody() { return body; } }Filter 里只对 JSON 请求做包装并且加上大小限制Component public class CachedBodyFilter extends OncePerRequestFilter { private static final long MAX_BODY_SIZE 1024 * 1024L; Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { String contentType request.getContentType(); boolean needCache contentType ! null contentType.toLowerCase().contains(application/json) request.getContentLengthLong() 0 request.getContentLengthLong() MAX_BODY_SIZE; if (needCache) { chain.doFilter(new CachedBodyHttpServletRequest(request), response); } else { chain.doFilter(request, response); } } }注意这个包装器绝对不能用在multipart/form-data文件上传上。把整个文件读进内存一个不小心就是 OOM。所以我在 Filter 里用 Content-Type 做了严格白名单只处理 JSON 且限定了 1MB 上限。拦截器里取 body 摘要就简单了private String resolveBodyDigest(HttpServletRequest request, OpenApiSign annotation) { if (!annotation.checkBody() || !(request instanceof CachedBodyHttpServletRequest wrapper)) { return null; } byte[] body wrapper.getBody(); if (body.length 0) { return null; } return DigestUtils.sha256Hex(body); }客户端在签名时也要对同一份 body 原文做 SHA-256把结果作为_bodyDigest参数塞进待签串。只要客户端和服务端用的是同一份字节摘要就必然一致。3.6 注册拦截器与路径排除Configuration public class OpenApiWebConfig implements WebMvcConfigurer { Resource private SignAuthInterceptor signAuthInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(signAuthInterceptor) .addPathPatterns(/openapi/**) .excludePathPatterns( /openapi/public/**, /openapi/health, /openapi/callback/pay // 第三方回调一般用另外的验签方式 ) .order(1); } }这里我做了双保险路径只限/openapi/**避免误伤内部接口同时方法上必须带OpenApiSign注解才真正校验。这样即使有人不小心把内部接口挂到了/openapi/路径下没有注解也不会被拦安全性和可控性都更好。3.7 appId 与 secret 的多应用管理密钥不能写死在配置文件里一是轮换麻烦二是每个人的开发环境都要改配置。我的做法是存数据库加本地缓存。表结构很简单字段类型说明app_idvarchar(32)应用标识唯一索引app_secretvarchar(64)密钥建议加密存储app_namevarchar(64)应用名称statustinyint1 启用 0 停用expire_atdatetime密钥过期时间查询层加一层短缓存缓存时间 60 秒。为什么不缓存太久因为万一某个 appId 被判定为风险要紧急停用60 秒内生效是可以接受的缓存半小时就太久了。如果对时效性要求更高可以用 Redis 发布订阅做主动失效。3.8 客户端签名调用示例服务端写完了客户端这边我用 Java 和 JavaScript 各给一个例子因为对接方基本就这两种。Java 客户端public class OpenApiClient { private final String appId; private final String appSecret; public OpenApiClient(String appId, String appSecret) { this.appId appId; this.appSecret appSecret; } public String post(String url, String jsonBody) { long ts System.currentTimeMillis(); String nonce UUID.randomUUID().toString().replace(-, ); MapString, String params new LinkedHashMap(); params.put(X-App-Id, appId); params.put(X-Timestamp, String.valueOf(ts)); params.put(X-Nonce, nonce); if (jsonBody ! null !jsonBody.isEmpty()) { params.put(_bodyDigest, DigestUtils.sha256Hex( jsonBody.getBytes(StandardCharsets.UTF_8))); } String content SignUtil.buildSignContent(params); String sign SignUtil.hmacSha256(content, appSecret); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.set(X-App-Id, appId); headers.set(X-Timestamp, String.valueOf(ts)); headers.set(X-Nonce, nonce); headers.set(X-Sign, sign); return new RestTemplate().exchange( url, HttpMethod.POST, new HttpEntity(jsonBody, headers), String.class).getBody(); } }JavaScript 版本Node 环境浏览器端请勿存放 secretconst crypto require(crypto); function buildSign(params, secret) { const keys Object.keys(params) .filter(k k ! sign k ! signType) .filter(k params[k] ! null params[k] ! ) .sort(); const content keys.map(k ${k}${params[k]}).join(); return crypto.createHmac(sha256, secret).update(content, utf8).digest(hex); }这里面有个细节要提醒对接方Object.keys默认就是插入顺序但排序之后才是 ASCII 升序一定要显式调用.sort()不要依赖默认顺序。4. 联调、自测与排查实录方案上线只是开始真正耗时的是联调和对线上问题的排查。这部分我把自己积累的经验都倒出来能帮对接方少走很多弯路。4.1 服务端自测单元测试与 Postman 脚本单元测试的重点是把签名规则固化成断言任何人改了拼接逻辑都会立刻失败。Test void buildSignContent_shouldSortAndDropBlank() { MapString, String params new HashMap(); params.put(b, 2); params.put(a, 1); params.put(c, ); params.put(sign, xxx); String content SignUtil.buildSignContent(params); assertEquals(a1b2, content); }Postman 那边用 Pre-request Script 自动算签名联调效率能提升一大截const appId pm.environment.get(appId); const secret pm.environment.get(appSecret); const ts Date.now().toString(); const nonce CryptoJS.lib.WordArray.random(16).toString(); const params { X-App-Id: appId, X-Timestamp: ts, X-Nonce: nonce }; const keys Object.keys(params).sort(); const content keys.map(k k params[k]).join(); const sign CryptoJS.HmacSHA256(content, secret).toString(); pm.request.headers.add({ key: X-App-Id, value: appId }); pm.request.headers.add({ key: X-Timestamp, value: ts }); pm.request.headers.add({ key: X-Nonce, value: nonce }); pm.request.headers.add({ key: X-Sign, value: sign });把这段脚本贴进 Postman以后每次改参数都不用手动重算签名对接方那边也能直接复制省掉大量沟通成本。4.2 签名失败排查顺序表签名失败是最高频的问题我整理了一份排查顺序按这个顺序走基本十分钟内能定位。顺序检查项典型现象定位方法1请求头是否齐全401001抓包看 Header2appId 是否正确、是否启用401002查管理后台应用状态3服务器与客户端时间差401003对比两端date命令输出4nonce 是否重复401004检查客户端是否用了固定值5参数排序是否一致401005打印服务端待签串与客户端对比6空值处理是否一致401005检查客户端是否过滤了空值7body 摘要是否一致401005对比两侧 SHA-256 结果8字符编码是否一致401005确认双方都用 UTF-8关键技巧在这里服务端打日志的时候一定要把待签串content打出来但不要打 secret。这样对接方把他那边的待签串发过来两边一对比哪个参数多了、少了、顺序不同一眼就能看出来。我们统计过80% 的签名失败都是待签串不一致而不是算法问题。4.3 高频坑点与避坑心得第一个坑是 URL 编码。如果参数值里有中文或者特殊字符客户端先 URL 解码再拼接、还是先拼接再编码结果完全不同。我的规则是取原始值参与签名不做任何 URL 编码。服务端拿到的参数是容器已经解码过的两边保持一致。第二个坑是时间戳精度。有的客户端传秒级时间戳有的传毫秒级。文档里必须写死毫秒并且在服务端做长度校验如果发现是 10 位数字就直接拒绝并提示比等到签名对不上再排查要快得多。第三个坑是十六进制大小写。前面提过一次这里再强调输出统一小写服务端比较前先toLowerCase()双保险。第四个坑是 Spring Boot 的HiddenHttpMethodFilter。如果你用了表单方式的_method参数它会改写请求方法但参数集合也会受影响签名时要注意排除这个内部参数。我现在的做法是直接禁止_method参数出现在开放接口里。第五个坑是网关层的重复读取。如果前面挂了 Nginx 或者网关某些配置会提前消费请求体导致 Filter 读到空 body。上线前一定要在完整链路里跑一次带 body 签名的请求别只在本地 8080 端口测通了就上。实操心得给对接方提供一个“签名调试接口”非常值。把他们的 appId、待签串、签名值传过来服务端只做一次校验并把内部期望值返回不开任何权限对接方自助定位问题能省下你至少一半的答疑时间。4.4 性能与安全加固性能方面真正需要优化的是 Redis 那一跳。我做过压测单机 QPS 3000 的情况下Redis 的 nonce 校验占了整个链路耗时的六成以上。优化手段有两个一是用 Redis Pipeline 或者 Lua 脚本把校验和写入合并成一次网络往返二是把 nonce 的存储换成 Redis Cluster 并且和应用部署在同一可用区把网络延迟压到 1 毫秒以内。安全方面有几条我认为必须做的secret 在数据库里加密存储不要明文日志里绝对不能出现 secret 和完整签名值appId 支持一键停用且缓存 60 秒内生效secret 支持双密钥并存方便平滑轮换接口加上频率限制防止拿到合法签名后暴力刷接口。关于密钥轮换我多说一句。切换的时候不要直接改 secret因为对接方还在用旧的一改就是全线报错。做法是同时保留新旧两个 secret服务端校验时两个都试一遍都通过就用新的那个等对接方全部迁移完再删掉旧的。过渡期我一般给两周。5. 从单应用走向平台后续可扩展的方向单应用接入几个合作方用拦截器这套足够了。但如果合作方数量上到几十个或者公司内部已经有统一的 API 网关就需要考虑架构上的演进。5.1 把签名校验下沉到网关当接入方数量变多每新增一个业务应用都要复制一遍拦截器代码维护成本就上来了。这时候更合理的做法是把签名校验做成网关插件网关统一完成 appId 校验、时间戳校验、防重放和签名验证校验通过后把X-App-Id透传到后端服务后端只信任来自网关的流量。这样做还有一个额外好处nonce 的 Redis 操作只在网关做一次后端服务完全不用操心防重放性能也更好。需要注意的是后端服务要做好来源限制只接受网关的 IP 访问否则绕过网关直接打后端就把整个校验体系废掉了。什么阶段适合下沉我的经验是接入方超过 10 个或者公司已经有两套以上业务系统需要对外开放就该考虑统一网关了。5.2 响应体签名与防篡改目前只做了请求方向的签名如果对安全性要求更高响应方向也可以做。做法是服务端在返回时对响应体算一次 HMAC放到响应头X-Resp-Sign里。客户端拿到之后用同样的方式验一遍确认返回数据没有被中间环节篡改。这个在很多金融、支付类的开放平台是标配。实现上可以放在ResponseBodyAdvice里拦截所有标注了OpenApiSign的返回值统一加签。要注意的是加签之后响应体内容就不能再被其他 Advice 修改了执行顺序要排在最后。5.3 密钥轮换与灰度切换密钥轮换不是一个技术问题而是一个流程问题。我总结的流程是这样的先在管理后台生成新密钥此时新旧并存通知对接方切换服务端在过渡期内两个都接受观察日志里新密钥的使用比例当旧密钥连续 7 天没有调用记录后在管理后台标记待删除最后删除。日志记录里我会记下“命中密钥版本”这样切换进度一目了然。没有这个记录你根本不知道对接方到底切没切。5.4 一些放在最后面的经验签名认证这套东西代码本身其实不难难的是把规则讲清楚、把边界情况都覆盖到。我的建议是第一版就把签名调试工具、详细的错误码文档、可复制的 Postman 脚本一起交付给对接方让他们能自助解决问题。这三样东西的价值在实际对接过程中比多写几百行代码要大得多。另外不要一开始就追求完美。我见过有团队想一步到位做国密算法、做证书双向认证结果方案拖了两个月还没上线合作方那边等不及了。先用 HMAC-SHA256 把基础方案跑通安全等级够用后续有明确需求再升级这个节奏更符合实际。