前阵子对接一个开放平台对方给了一堆接口文档权限校验用的是类似AWS SigV4的签名规则。我一开始觉得麻烦心想直接用Token或者Basic Auth不就完了但在用JDK17的HttpClient手写实现了一遍之后才理解这套设计确实有它的道理。今天就把整个签名生成和集成逻辑梳理清楚重点讲三件事签名里每个字节是怎么算出来的、怎么用JDK17 HttpClient把签名后的请求安全地发出去、实际对接中哪些坑最容易踩。这篇文章适合正在对接云厂商API、开放平台网关或者想给自己内部服务设计一套请求签名体系的同学。如果你还在用RestTemplate或者OkHttp看完也可以把思路平移过去签名逻辑本身是通用的跟具体HTTP客户端没有强绑定。1. 请求签名到底要解决什么问题1.1 签名不是加密而是防篡改、防伪装、防重放很多人第一次接触“请求签名”这个概念时会下意识认为它是为了加密数据。这个理解偏差很要命。签名算法做的是完整性校验和身份认证而不是内容保密。你POST给服务端的JSON仍然是明文抓包一样能看见请求体但这个请求体一旦被中间人改了哪怕一个字节服务端验签时就能立刻发现。打个比方签名就像你在合同每一页上按的手印。合同内容人人都能看但谁要是偷偷改了某个数字手印就对不上了。而且这个手印只能由持有密钥的人按出来别人伪造不了。在实际的业务场景里请求签名要解决的具体问题有三个身份认证服务端收到请求后需要通过签名确认“你是谁”。密钥即身份客户端持有下发的AccessKey和SecretKey签名能证明请求是由合法客户端发出的。完整性校验请求参数、请求体、请求头在传输过程中都不能被改动。为了做到这一点签名时会把这些内容一起参与计算任何一个字段的变化都会导致签名结果完全不同。防重放抓包拿到一个完整的签名请求后能不能直接重放一万次不能。SigV4风格的签名会把请求时间戳作为签名因子服务端一般建议把时间窗口控制在15分钟以内超时直接拒绝。所以你去看AWS的官方文档里面有一句话我记得很清楚签名是用来提供请求完整性的而不是用来加密请求内容。想清楚这个定位后面写代码时就不会搞混。1.2 为什么大家都要抄SigV4的作业这几年我接触过的云厂商、开放平台网关至少有五六家采用了和SigV4非常相似的签名规则。不是说大家懒得创新而是这套设计确实经过了大规模生产环境的验证具备几个其他方案没有的优点。第一签名覆盖范围广。SigV4不只是把请求体和参数拿来算一遍它把HTTP方法、URI路径、查询字符串、选定请求头、请求体哈希全部纳入规范请求Canonical Request相当于把HTTP请求的关键指纹都锁死了。无论是谁篡改了参数名、参数值还是Header验签都过不了。第二签名密钥是“派生”的。它不是直接用你的SecretKey去签而是通过时间戳、地域、服务名做了一层HMAC派生得到临时签名密钥再用这个临时密钥去签请求。这样即使某个请求的签名被截获也无法逆向推导出原始SecretKey减少了长期密钥泄露的风险。第三规范化规则清晰。所有参与签名的字符串都有精确的拼接方式和编码规则比如URI每个路径段要单独URL编码、请求头名称要转小写并按字典序排序。这些规则虽然写起来繁琐但好处是各种语言、各种平台的实现可以做到完全一致服务端验签时不会因为编码细节不统一而误判。我自己的体会是这套签名算法第一次看会觉得步骤太多但当你把它拆成“规范化请求、待签字符串、派生签名密钥”三个模块后每一块都很好理解代码量其实也控制在两三百行以内。2. SigV4签名算法核心流程拆解2.1 签名过程的整体逻辑在写代码之前先把SigV4风格的签名算法在脑子里形成一个完整链条。整个过程可以分成两大阶段第一阶段在客户端完成第二阶段在服务端完成。客户端签名流程如下将请求的原始内容整理成“规范请求”CanonicalRequest包括HTTP方法、规范化URI、规范化查询字符串、规范化请求头、请求体哈希。用规范请求拼接生成“待签字符串”StringToSign待签字符串里还包含签名算法标识、请求时间戳、凭证作用域。用你的SecretKey结合时间戳、地域、服务名派生出签名密钥。用派生签名密钥对待签字符串做HMAC-SHA256计算得到二进制摘要再转成十六进制小写字符串。组装Authorization请求头内容包括签名算法、AccessKey、凭证作用域、参与签名的Header列表和最终签名值。服务端验签时做的事情基本就是反向操作同一个请求自己按同样的规则重新算一遍签名如果结果和客户端传过来的签名一致就认为请求合法。所以这个算法能成立的前提是两端对规范化规则的理解完全一致哪怕一个多余的换行符都会导致验签失败。2.2 规范请求长什么样规范请求是整个签名链路的起点它把HTTP请求的核心信息变成一个定长字符串。以GET请求为例它的格式如下HTTPMethod \n CanonicalURI \n CanonicalQueryString \n CanonicalHeaders \n SignedHeaders \n HashedPayload逐行拆开看HTTPMethod就是GET、POST这类大写方法名原样放上去不需要加任何编码。CanonicalURIURI路径的规范化版本。规则是每个路径段单独做URL编码但保留路径分隔符/比如/v1/users/detail不能把斜杠也编码成%2F。CanonicalQueryString查询字符串的规范化版本。需要把参数名和参数值都做URL编码然后按参数名ASCII码升序排列多个参数用连接。CanonicalHeaders需要参与签名的请求头列表格式是“请求头小写名称:请求头值”每个请求头占一行以换行符结尾。这些请求头还要按名称的ASCII码排序。SignedHeaders参与签名的请求头名称列表用分号分隔且所有名称转小写。HashedPayload请求体的SHA-256哈希值十六进制小写。对于GET请求请求体为空字符串那就对空字符串做SHA-256哈希。看着很抽象我举个实际例子。如果请求是GET https://api.example.com/v1/users?pageSize20page1请求头包含host: api.example.com和x-ca-date: 20250601T120000Z请求体为空。那么这个请求的规范请求就是GET /v1/users page1pageSize20 host:api.example.com x-ca-date:20250601T120000Z host;x-ca-date e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855注意这里CanonicalHeaders后面有个空行那个空行是用来分隔请求头列表和请求体哈希的。很多人第一次写这个算法时就在这里翻车少了一个换行符签名怎么都对不上。我把这个细节写出来希望你能避免踩同样的坑。2.3 待签字符串与派生签名密钥规范请求算完之后还要再做一次哈希然后拼接到待签字符串里。待签字符串的格式如下HMAC_SHA256_ALGORITHM \n RequestTimestamp \n CredentialScope \n HashedCanonicalRequest其中HMAC_SHA256_ALGORITHM在SigV4里是固定字符串AWS4-HMAC-SHA256RequestTimestamp是形如20250601T120000Z的UTC时间CredentialScope是YYYYMMDD/region/service/aws4_request格式的凭证作用域最后一项就是把上一步得到的规范请求再做一次SHA-256哈希转为十六进制小写。到这里签名还没开始计算。真正的密钥从你的SecretKey派生而来派生链条如下kDate HMAC_SHA256(AWS4 SecretKey, YYYYMMDD) kRegion HMAC_SHA256(kDate, Region) kService HMAC_SHA256(kRegion, Service) kSigning HMAC_SHA256(kService, aws4_request)看到没有每一级HMAC的密钥都是上一级的输出最初的是AWS4拼接你的SecretKey。最终拿到的kSigning就是当前请求的签名密钥。这个设计的巧妙之处在于你的SecretKey不会直接参与请求签名计算即使服务端日志里记录了签名值也无法反推出密钥本身。最后一步用kSigning对待签字符串做HMAC-SHA256得到32字节的二进制摘要转成十六进制小写就是最终签名值。3. JDK17环境准备与基础工具代码3.1 为什么选JDK17的HttpClient很多同学还在用Java 8每次提到JDK11以后的原生HttpClient都有点犹豫。以我个人的使用体验来说从JDK11引入HttpClient开始它就已经覆盖了绝大多数生产环境的需求。为什么非要强调JDK17主要是两个原因。一是JDK17是长期支持版本国内大部分互联网公司已经逐步把生产环境从8迁移到17你写的代码如果不能在新版本上跑迟早是要还债的。二是我下面示例里用到了一个很舒服的APIjava.util.HexFormat这是Java 17才有的工具类用来做字节数组和十六进制字符串的互转比之前手写String.format或者BigInteger.toString(16)舒服太多。另外原生HttpClient支持HTTP/2、响应式Body处理、异步发送、超时控制都是开箱即用不需要额外引入依赖。Spring的RestTemplate虽然生态好但在新项目里我越来越倾向于直接用原生客户端少一层封装就少一层幺蛾子。3.2 十六进制转换和HMAC工具先备好签名过程中大量涉及SHA-256哈希和HMAC计算所以先把这两个最基础的能力封装好。Java标准库提供了java.security.MessageDigest和javax.crypto.Mac不需要引第三方包。package com.example.sigv4; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import java.util.HexFormat; public final class CryptoUtils { private CryptoUtils() { } public static String sha256Hex(byte[] data) { try { MessageDigest digest MessageDigest.getInstance(SHA-256); byte[] hash digest.digest(data); return HexFormat.of().formatHex(hash); } catch (NoSuchAlgorithmException e) { throw new IllegalStateException(SHA-256 algorithm not available, e); } } public static String sha256Hex(String data) { return sha256Hex(data.getBytes(StandardCharsets.UTF_8)); } public static byte[] hmacSha256(byte[] key, byte[] data) { try { Mac mac Mac.getInstance(HmacSHA256); mac.init(new SecretKeySpec(key, HmacSHA256)); return mac.doFinal(data); } catch (Exception e) { throw new IllegalStateException(Failed to calculate HMAC-SHA256, e); } } public static byte[] hmacSha256(byte[] key, String data) { return hmacSha256(key, data.getBytes(StandardCharsets.UTF_8)); } }这段代码里有个细节值得说一下。Mac初始化时传入的SecretKeySpec使用的是HmacSHA256算法名它要求密钥类型是SecretKey直接把byte数组包成SecretKeySpec是标准做法。另外Mac实例不是线程安全的每次计算时都new一个新的避免在并发场景下出现数据错乱。我在封装工具类时没有把Mac做成单例缓存正是基于这个考虑。4. 手写SigV4签名完整实现4.1 构建规范请求签名核心的第一步就是构建规范请求。这里我把URI和查询字符串的规范化逻辑单独抽取出来因为实际项目中这两个地方最容易出幺蛾子。package com.example.sigv4; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.Collections; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; import java.util.stream.Collectors; public final class SignRequestBuilder { private static final char HEX_DIGITS[] 0123456789abcdef.toCharArray(); private SignRequestBuilder() { } public static String canonicalUri(String rawPath) { if (rawPath null || rawPath.isEmpty()) { return /; } String raw rawPath.startsWith(/) ? rawPath : / rawPath; String[] segments raw.split(/, -1); StringBuilder sb new StringBuilder(); for (int i 0; i segments.length; i) { if (i 0) { sb.append(/); } sb.append(encodePathSegment(segments[i])); } return sb.length() 0 ? / : sb.toString(); } private static String encodePathSegment(String segment) { if (segment.isEmpty()) { return segment; } StringBuilder result new StringBuilder(); byte[] bytes segment.getBytes(StandardCharsets.UTF_8); for (byte b : bytes) { char ch (char) (b 0xFF); if ((ch A ch Z) || (ch a ch z) || (ch 0 ch 9) || ch - || ch _ || ch . || ch ~) { result.append(ch); } else { result.append(%); result.append(HEX_DIGITS[(b 4) 0xF]); result.append(HEX_DIGITS[b 0xF]); } } return result.toString(); } public static String canonicalQueryString(MapString, String queryParams) { if (queryParams null || queryParams.isEmpty()) { return ; } ListString encodedPairs new ArrayList(); for (Map.EntryString, String entry : queryParams.entrySet()) { String key urlEncode(entry.getKey()); String value urlEncode(entry.getValue() null ? : entry.getValue()); encodedPairs.add(key value); } Collections.sort(encodedPairs); return String.join(, encodedPairs); } private static String urlEncode(String value) { return URLEncoder.encode(value, StandardCharsets.UTF_8) .replace(, %20) .replace(*, %2A) .replace(%7E, ~); } }这个类里有一个必须重点强调的规则RFC 3986对URL编码的规定和URLEncoder默认行为不一致。URLEncoder会把空格编码成但签名算法要求空格必须编码成%20星号*应该编码成%2A波浪号~在URL里属于非保留字符不应该被编码。所以我写了三个replace调用把URLEncoder的默认行为纠正过来。URI路径编码也容易出错。很多人直接对整个路径调用URLEncoder.encode结果斜杠/也被转义成了%2F导致服务端解析路径时直接404。正确做法是把路径按斜杠拆开对每一段单独编码再把斜杠拼回去。这一点我在代码里用split(/, -1)配合循环处理了。4.2 计算签名并生成Authorization头有了规范请求就能计算签名了。下面这个类负责拼接待签字符串、派生签名密钥、生成最终的Authorization请求头。package com.example.sigv4; import java.time.ZoneOffset; import java.time.ZonedDateTime; import java.time.format.DateTimeFormatter; import java.util.Locale; import java.util.Map; import java.util.TreeMap; public final class SigV4Util { public static final String ALGORITHM AWS4-HMAC-SHA256; public static final String TERMINATOR aws4_request; private static final DateTimeFormatter DATE_FORMATTER DateTimeFormatter.ofPattern(yyyyMMdd, Locale.ROOT).withZone(ZoneOffset.UTC); private static final DateTimeFormatter TIME_FORMATTER DateTimeFormatter.ofPattern(yyyyMMddTHHmmssZ, Locale.ROOT).withZone(ZoneOffset.UTC); private static final ZoneOffset UTC ZoneOffset.UTC; private final String accessKey; private final String secretKey; private final String region; private final String service; public SigV4Util(String accessKey, String secretKey, String region, String service) { this.accessKey accessKey; this.secretKey secretKey; this.region region; this.service service; } public String buildAuthorizationHeader(String method, String uri, MapString, String queryParams, MapString, String headers, byte[] payload) { ZonedDateTime now ZonedDateTime.now(UTC); String amzDate TIME_FORMATTER.format(now); String dateStamp DATE_FORMATTER.format(now); String payloadHash CryptoUtils.sha256Hex(payload ! null ? payload : new byte[0]); TreeMapString, String sortedHeaders new TreeMap(headers); sortedHeaders.put(host, headers.getOrDefault(host, )); sortedHeaders.put(x-ca-date, amzDate); sortedHeaders.put(x-ca-content-sha256, payloadHash); String canonicalRequest buildCanonicalRequest(method, uri, queryParams, sortedHeaders, payloadHash); String credentialScope dateStamp / region / service / TERMINATOR; String stringToSign ALGORITHM \n amzDate \n credentialScope \n CryptoUtils.sha256Hex(canonicalRequest); byte[] signingKey deriveSigningKey(dateStamp); byte[] signatureBytes CryptoUtils.hmacSha256(signingKey, stringToSign); String signature java.util.HexFormat.of().formatHex(signatureBytes); return ALGORITHM Credential accessKey / credentialScope , SignedHeaders signedHeaders(sortedHeaders) , Signature signature; } private String buildCanonicalRequest(String method, String uri, MapString, String queryParams, MapString, String sortedHeaders, String payloadHash) { String canonicalQuery SignRequestBuilder.canonicalQueryString(queryParams); String canonicalHeaders buildCanonicalHeaders(sortedHeaders); String signedHeaders signedHeaders(sortedHeaders); return method \n SignRequestBuilder.canonicalUri(uri) \n canonicalQuery \n canonicalHeaders \n signedHeaders \n payloadHash; } private String buildCanonicalHeaders(TreeMapString, String sortedHeaders) { StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : sortedHeaders.entrySet()) { String name entry.getKey().toLowerCase(Locale.ROOT); String value entry.getValue() null ? : entry.getValue().trim(); sb.append(name).append(:).append(value).append(\n); } return sb.toString(); } private String signedHeaders(TreeMapString, String sortedHeaders) { return sortedHeaders.keySet().stream() .map(name - name.toLowerCase(Locale.ROOT)) .collect(java.util.stream.Collectors.joining(;)); } private byte[] deriveSigningKey(String dateStamp) { byte[] kDate CryptoUtils.hmacSha256( (AWS4 secretKey).getBytes(java.nio.charset.StandardCharsets.UTF_8), dateStamp); byte[] kRegion CryptoUtils.hmacSha256(kDate, region); byte[] kService CryptoUtils.hmacSha256(kRegion, service); return CryptoUtils.hmacSha256(kService, TERMINATOR); } }这段代码里我把参与签名的请求头放进了TreeMap它默认按Key的字典序排序省得自己写比较器。然后主动把host、x-ca-date、x-ca-content-sha256三个头合并进去确保签名覆盖了目标Host、请求时间和请求体哈希。host这里是从入参headers里取的如果在实际使用中没传那就得从URI里提取。这一点我在下一节集成到HttpClient时再做演示。这里我还想解释一下x-ca-date和x-ca-content-sha256这两个自定义请求头。在真正的SigV4设计里它们叫x-amz-date和x-amz-content-sha256我这里改成了x-ca-前缀表示这是一套模仿SigV4思路的自定义签名方案。如果你对接的是真正的AWS服务需要把前缀改回去同时日期格式也要严格对齐AWS的规范。4.3 把工具类串起来跑通一个Demo工具类写完了先别急着往HttpClient上套我习惯先写一个main方法把签名结果打印出来肉眼检查一下格式是否正确。public class SigV4Demo { public static void main(String[] args) { SigV4Util signer new SigV4Util( test-access-key, test-secret-key, cn-north-1, custom-api); byte[] emptyBody new byte[0]; MapString, String query Map.of( page, 1, pageSize, 20 ); MapString, String headers new java.util.HashMap(); headers.put(host, api.example.com); String authHeader signer.buildAuthorizationHeader( GET, /v1/users, query, headers, emptyBody); System.out.println(authHeader); } }输出大概长这样AWS4-HMAC-SHA256 Credentialtest-access-key/20250601/cn-north-1/custom-api/aws4_request, SignedHeadershost;x-ca-content-sha256;x-ca-date, Signature4f6d7b...看到这个输出心里就有底了。如果服务端签名一直验不过先用这份格式化输出和服务端提供的测试用例比对很快能定位是时间戳问题、Header排序问题还是签名值计算问题。5. 集成到JDK17 HttpClient的完整流程5.1 封装签名请求构建器签名工具类的输出是一个Authorization头接下来的事情就简单了把它塞进JDK17的HttpClient请求里。我先封装一个SignedRequestFactory负责接收业务参数、自动计算签名、返回一个可以直接发送的HttpRequest。package com.example.sigv4; import java.net.URI; import java.net.http.HttpRequest; import java.net.http.HttpRequest.BodyPublishers; import java.nio.charset.StandardCharsets; import java.time.Duration; import java.util.HashMap; import java.util.Map; public class SignedRequestFactory { private final String baseUrl; private final SigV4Util sigV4Util; public SignedRequestFactory(String baseUrl, SigV4Util sigV4Util) { this.baseUrl baseUrl; this.sigV4Util sigV4Util; } public HttpRequest get(String path, MapString, String queryParams) { byte[] payload new byte[0]; MapString, String headers new HashMap(); headers.put(host, URI.create(baseUrl).getHost()); String fullPath buildPath(path, queryParams); String authorization sigV4Util.buildAuthorizationHeader( GET, fullPath, queryParams, headers, payload); return HttpRequest.newBuilder() .uri(URI.create(baseUrl fullPath)) .timeout(Duration.ofSeconds(10)) .header(host, URI.create(baseUrl).getHost()) .header(x-ca-date, headers.get(x-ca-date)) .header(x-ca-content-sha256, headers.get(x-ca-content-sha256)) .header(Authorization, authorization) .GET() .build(); } public HttpRequest post(String path, String jsonBody) { byte[] payload jsonBody.getBytes(StandardCharsets.UTF_8); MapString, String headers new HashMap(); headers.put(host, URI.create(baseUrl).getHost()); headers.put(content-type, application/json); String authorization sigV4Util.buildAuthorizationHeader( POST, path, Map.of(), headers, payload); return HttpRequest.newBuilder() .uri(URI.create(baseUrl path)) .timeout(Duration.ofSeconds(10)) .header(host, URI.create(baseUrl).getHost()) .header(content-type, application/json) .header(x-ca-date, headers.get(x-ca-date)) .header(x-ca-content-sha256, headers.get(x-ca-content-sha256)) .header(Authorization, authorization) .POST(BodyPublishers.ofByteArray(payload)) .build(); } private String buildPath(String path, MapString, String queryParams) { if (queryParams null || queryParams.isEmpty()) { return path; } StringBuilder sb new StringBuilder(path).append(?); String canonicalQuery SignRequestBuilder.canonicalQueryString(queryParams); return sb.append(canonicalQuery).toString(); } }有几个点要提醒一下。第一我在GET请求构建签名时传入的fullPath是包含查询字符串的完整路径这样签名就能覆盖查询参数。但传给HttpRequest.newBuilder().uri()的URI中如果查询参数已经拼进路径就不要再额外传查询参数了否则会被HttpClient重复编码导致签名计算时用的QueryString和实际发出的QueryString不一致。第二buildAuthorizationHeader方法内部会自动往sortedHeaders里塞x-ca-date和x-ca-content-sha256所以我在外部创建headers时不需要手动传这两个值。但发送请求时这两个头必须显式添加到HttpRequest上否则签名计算的Header集合和实际发送的Header集合不一致服务端验签时排序得到的SignedHeaders对不上。第三host头这个细节要单拎出来说。JDK的HttpClient在发送时会自动加上Host头但这个自动添加发生在请求构建阶段之后。我在签名计算时用URI.create(baseUrl).getHost()手动取了Host并在请求构建时也显式设了Host头这样能确保签名和实际发送保持一致。5.2 用JDK17 HttpClient发送签名请求Factory写完之后实际发送就只剩几行代码了。package com.example.sigv4; import java.net.http.HttpClient; import java.net.http.HttpResponse; import java.util.Map; public class ApiClient { private final HttpClient httpClient HttpClient.newBuilder() .version(HttpClient.Version.HTTP_1_1) .connectTimeout(java.time.Duration.ofSeconds(5)) .build(); private final SignedRequestFactory requestFactory; public ApiClient(SignedRequestFactory requestFactory) { this.requestFactory requestFactory; } public String queryUsers(int page, int pageSize) throws Exception { var request requestFactory.get(/v1/users, Map.of( page, String.valueOf(page), pageSize, String.valueOf(pageSize) )); HttpResponseString response httpClient.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); } public String createUser(String jsonBody) throws Exception { var request requestFactory.post(/v1/users, jsonBody); HttpResponseString response httpClient.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); } }这个ApiClient已经把签名、发送、响应解析都串起来了。业务方法里不再出现任何签名相关的代码调用方只需要关心业务参数就行。这里我特意把HttpClient的版本设置为HTTP_1_1可能有人会问为什么不直接用默认的HTTP/2。原因很简单HTTP/2的请求头是二进制的签名计算时没法简单地拼成字符串。虽然真正做起来可以用:scheme等伪头字段来拼但大多数开放平台网关对HTTP/2的支持都还没有那么完善。为了稳定我建议对接外部API时先强制HTTP/1.1等确认服务端完全支持HTTP/2再升级。5.3 异步场景下的签名注意点JDK17的原生HttpClient有很好的异步支持sendAsync返回一个CompletableFuture可以配合thenApply做链式处理。但在异步场景下签名计算逻辑本身和同步没有区别密钥、时间戳、请求体哈希都是请求发送前就已经确定的。要注意的是时间戳。SigV4Util.buildAuthorizationHeader内部获取的是当前系统时间如果你多次调用这个方法时间戳会自然递增。但在异步请求的场景下如果程序在短时间内发送大量请求时间戳秒级精度不会成为问题。真正需要担心的是把签名时间和准星对齐多台机器部署时需要配置NTP时间同步。另外如果你用同一个SigV4Util实例在多线程下并发调用TreeMap和HexFormat都是线程安全的不会出问题。我的代码里没有维护任何可变状态所有临时对象都在方法内部创建这一点对生产环境很重要。6. 常见问题与排查技巧实录6.1 请求重定向导致认证信息丢失使用JDK HttpClient时有个默认行为容易让人栽跟头HttpClient默认会跟随重定向但你可以通过HttpClient.Builder.followRedirects()来设置策略。如果你不显式设置JDK11到JDK17的默认值是NEVER。也就是说除非你主动配置HttpClient不会自动跟随重定向。但你要是配置了NORMAL或ALWAYS问题就来了。签名绑定的是原始请求的Host、路径和Header一旦服务端返回302HttpClient自动重定向到另一个地址Host变了、路径变了、签名自然就失效了。因为签名头还在原来的Authorization里但服务端重新验签时发现目标Host和签名目标Host不一致直接拒绝。我自己遇到过类似的场景是API网关在鉴权前会先重定向一次到某个统一入口。解决思路有两种如果重定向是增加路径前缀可以在签名前手动把最终的目标URI算好直接请求最终地址绕开重定向。如果确实没法预判重定向目标就必须关闭自动重定向拿到302响应后从Location头解析新地址重新执行签名流程再发起一次新请求。这本质上不是签名算法的问题而是HTTP客户端状态机和签名状态不一致的问题。每次重定向本质上是发起一个全新的请求必须重新签名。6.2 请求体读取与签名顺序这个坑非常隐蔽。很多HTTP客户端框架允许你通过拦截器Interceptor统一加签名但你如果想在拦截器里读取请求体来计算哈希就可能会发现请求体被读完一次之后真正发送时变成了空内容。JDK的HttpRequest在设计上是不允许重复读取Body的。BodyPublisher是一次性的流不能被消费两次。所以在拦截器里先签名再发送如果你的代码在签名时把请求体完全读出来做了哈希那么发送时请求体就已经没了。我的解决方案是始终在构建请求前就准备好请求体的byte[]把哈希计算放在请求体还不属于HttpClient的情况下。SignedRequestFactory里先拿到byte[] payload用它计算哈希再通过BodyPublishers.ofByteArray(payload)创建Publisher这样同一个byte数组可以被哈希和使用互不影响。如果请求体是文件流那就先把流读成byte[]再做后续操作绝不能把流直接传给BodyPublishers后再去读取流来做哈希。6.3 时钟不同步、URL编码、Header大小写我在排错过程中遇到的绝大多数签名失败都集中在下面三个细节上。一是系统时间不同步。签名里带着时间戳如果服务器本地时间和标准UTC时间差超过服务端允许的窗口一般是5到15分钟签名直接无效。我遇到过最诡异的情况是本地开发环境时间正常但测试服务器因为没做NTP同步时间慢了三分钟导致线上一直验签失败。排查这个问题的办法很简单在签名工具类里临时打印时间戳手动差一下和标准时间的差值。二是URL编码规则不一致。这个问题我在4.1小节里说过再强调一次Java的URLEncoder不是为签名场景设计的你必须手动把替换成%20把*替换成%2A同时保留~。更麻烦的是不同的服务端实现可能对编码的要求还有细微差别有的要求对!、、(、)也做编码这取决于服务端用的规范化规则。如果你的服务端文档里没有明确细节先用最简单的ASCII字符测试再逐步增加特殊字符。三是Header名称大小写。HTTP Header名称本来不区分大小写但签名算法要求必须把参与签名的Header名称统一转成小写。如果你构造请求时用了Host签名时却是host服务端按小写解析后会认为你签名的Header和实际发送的Header不一致。解决办法是buildCanonicalHeaders和signedHeaders两个方法里都对Header名称做toLowerCase我代码里已经处理了但你自己如果扩展新的Header要注意这一条。我再整理一个排查速查表方便你逐个排除现象可能原因排查方向返回403 Forbidden签名值错误先打印签名值比对服务端文档的测试用例返回400 InvalidSignature时间戳超范围检查系统时间和UTC时间差检查时区设置返回URI未授权URI编码不一致对比CanonicalURI和实际路径检查斜杠是否被转义服务端只报缺少签名头Authorization头未发送检查HttpClient请求构建时是否漏掉自定义Header重定向后签名失效开启了自动重定向关闭followRedirects手动重新签名并发送异步发送大量请求部分失败多线程复用Mac实例确保Mac每次new不能缓存共享6.4 请求签名的性能开销有同学可能会担心HMAC-SHA256的计算量会不会拖慢接口响应。我可以负责任地说这个担心是多余的。我做过简单压测本机环境下HMAC-SHA256计算一次签名大约在几微秒到几十微秒级别相对一次网络请求动辄几十毫秒的耗时完全可以忽略不计。真正影响性能的是请求体的SHA-256哈希计算。如果请求体有几十MB哈希计算确实会占用一些CPU时间。但这种场景下Hash过程是流式的可以边读边算不需要把整个请求体先读入内存。不过JDK自带的HttpClient对请求体并没有提供流式签名的钩子所以我建议还是先把请求体转成byte[]如果内存压力大可以考虑用分片上传接口替代。安全方面还有一个额外建议签名计算用的SecretKey不要硬编码在代码里也不要放在配置文件后提交到Git仓库。推荐的做法是通过环境变量或密钥管理服务注入在运行时读取。我在示例代码里图省事直接传了字符串但在生产环境至少要用System.getenv(API_SECRET_KEY)来获取。7. 结束语说了这么多最后分享一点我自己的实践体会。第一次接触签名算法时我对那套复杂规则是有点抵触的觉得不如直接上OAuth2或者简单的Token。但用完之后我反而喜欢上了这种签名方式的直白——它不依赖全局的会话状态不需要专门的服务端存储两边只要共享一套密钥和一套规则就能完成双向验证。如果你现在也在做类似的事情我的建议是小步快跑。先把算法跑通再逐步加上自定义Header、异常重试、多线程发送这些进阶功能。签名这个东西最怕的就是一步到位写得花里胡哨结果出现问题后根本不知道是哪一环算错了。把日志打清楚每一步的输入输出都记录下来调试起来会轻松很多。