1. 项目概述：为什么需要自研接口签名认证？

在微服务架构和前后端分离成为主流的今天，API接口的安全性变得至关重要。我们经常听到OAuth2、JWT这些“明星”方案，它们功能强大，生态完善，但随之而来的是复杂的配置、额外的依赖和陡峭的学习曲线。有时候，我们的项目可能只是一个内部系统、一个轻量级服务，或者一个对第三方依赖有严格管控的环境，引入一整套庞大的安全框架显得有些“杀鸡用牛刀”。

这就是我们今天要探讨的场景：不借助任何第三方安全框架（如Spring Security、Apache Shiro），仅凭Spring Boot自身的能力，实现一套轻量、可控、安全的接口签名认证机制。这听起来像是一个“轮子”，但在特定场景下，自己造的“轮子”可能更贴合业务的车辙。比如，你需要与一些硬件设备、遗留系统或者对协议有特殊要求的第三方进行对接，它们可能无法理解复杂的OAuth流程，但能很好地处理一个基于时间戳和签名的简单HTTP请求。

我最近在一个物联网数据采集项目中就遇到了类似情况。我们需要对接几十种不同厂商的传感器，这些设备计算能力有限，通信协议简单，要求接口调用必须快速、无状态且易于验证。如果强行上Spring Security，不仅设备端难以实现，服务端的性能开销也成了问题。最终，我们选择基于Spring Boot的拦截器和一些基础的加密工具类，自研了一套签名认证方案，稳定运行至今。接下来，我就把这套方案的思路、实现细节和踩过的坑，毫无保留地分享出来。

2. 核心思路与方案设计

2.1 签名认证的本质与核心流程

抛开那些复杂的术语，接口签名认证的核心目标就一个：确保请求是由合法的调用方发起，且在传输过程中未被篡改。它不关心你是谁（那是身份认证），只关心“你说的话是不是你原本要说的，并且我允许你说”。

一个典型的签名认证流程包含以下几个核心环节：

1. 客户端（调用方）：在发起请求前，将请求参数（包括公共参数和业务参数）按照既定规则拼接成一个字符串，然后使用双方预先共享的密钥（Secret Key）对这个字符串进行加密（通常是HMAC-SHA256），生成一个唯一的签名（Signature）。
2. 网络传输：客户端将业务参数、公共参数以及生成的签名，一并发送给服务端。
3. 服务端（接收方）：收到请求后，使用相同的规则拼接参数，并使用存储的对应密钥进行加密，生成服务端的签名。
4. 验证：比较客户端传来的签名和自己生成的签名是否一致。如果一致，则认为请求合法且未被篡改；否则，拒绝请求。

这个流程的关键在于“规则”和“密钥”的保密性。规则可以公开，但密钥必须绝对保密。

2.2 自研方案 vs. 第三方框架

为什么选择自研？我们通过一个简单的对比表格来看：

注意：自研方案并不意味着“更安全”。安全是一个系统工程，Spring Security等成熟框架经过了无数项目的检验和社区的安全审计。自研方案的安全性高度依赖于开发者的安全素养和代码质量。它更适合于对安全要求明确、边界清晰、且对轻量和灵活有极端要求的内部或特定场景。

2.3 我们的方案架构设计

基于以上分析，我们设计了一个简洁的架构，主要由三部分组成：

1. 签名生成器 (SignGenerator)：一个工具类，负责在客户端按照规则生成签名。
2. 签名验证拦截器 (SignAuthInterceptor)：一个Spring MVC的HandlerInterceptor，部署在服务端，对所有需要认证的接口请求进行拦截和验签。
3. 密钥管理服务 (SecretKeyService)：一个简单的服务，用于根据客户端标识（如appId）查询对应的密钥（secretKey）。在实际项目中，它可能对接数据库、配置中心或缓存。

整个请求验证的时序可以概括为：HTTP请求 → 拦截器拦截 → 提取参数和签名 → 调用密钥服务获取密钥 → 按规则生成服务端签名 → 比对签名 → 通过/拒绝。

3. 核心细节解析与实操要点

3.1 签名规则的设计：防重放与防篡改

签名规则是整套方案的心脏，设计不好，安全形同虚设。一个健壮的规则必须考虑防篡改（Integrity）和防重放（Replay Attack）。

我们的规则定义如下：

1. 参与签名的参数：所有非空的请求参数（Query String或Form Data）和自定义的公共参数。
2. 公共参数（必须包含）：
   • appId: 客户端应用标识，用于查找对应的secretKey。
   • timestamp: 请求发起的时间戳（毫秒级）。这是防重放的关键。
   • nonce: 随机字符串，一次性使用。与timestamp结合，进一步加强防重放。
3. 参数排序：将所有待签名的参数（包括公共参数和业务参数）按照参数名的ASCII码从小到大排序（字典序）。这一步是为了保证客户端和服务端拼接字符串的顺序绝对一致。
4. 参数拼接：将排序后的所有参数，用参数名=参数值的格式，用&字符连接起来，形成待签名字符串。例如：appId=test123&nonce=abc&timestamp=1678886400000&userId=1001。
5. 生成签名：使用HMAC-SHA256算法，以secretKey为密钥，对上一步得到的待签名字符串进行加密，并将结果转换为十六进制字符串（小写），即为最终的sign。

实操心得：参数编码与空值处理在拼接参数时，务必对参数名和参数值进行URL编码（UTF-8）。这是最容易踩的坑。假设参数值是a&b=c，如果不编码，拼接后会破坏参数结构。我们使用java.net.URLEncoder进行编码。同时，空值参数（null或空字符串）不参与签名，避免因客户端/服务端对空值处理不一致导致验签失败。

3.2 密钥的管理与存储

密钥（secretKey）是签名的灵魂，必须安全存储。在服务端，我们需要根据appId找到对应的secretKey。

• 存储选择：对于小型项目，可以放在配置文件中（不推荐）或数据库里。生产环境建议将appId和secretKey的映射关系存入数据库，并且secretKey列最好加密存储。对于性能要求高的场景，可以在应用启动时加载到内存缓存（如ConcurrentHashMap）或分布式缓存（如Redis）中。
• 密钥生成：secretKey必须是足够长度和随机性的字符串，建议使用安全的随机数生成器生成，例如java.security.SecureRandom生成一个32字节的Base64编码字符串。
• 定期轮换：像改密码一样，密钥也需要定期轮换以提升安全性。可以设计一个后台任务，定期生成新密钥并通知客户端更新。在过渡期内，可以支持新旧密钥同时验证。

3.3 防重放攻击的实现

即使签名正确，攻击者截获请求后原封不动地再次发送（重放攻击），也会被误认为是合法请求。我们通过timestamp和nonce来防御。

• 时间戳（timestamp）校验：服务端收到请求后，取出请求中的timestamp，与服务器当前时间进行比较。我们允许一个合理的时间误差窗口，比如5分钟。如果请求时间与服务器时间相差超过5分钟，则视为无效请求，直接拒绝。这样可以过滤掉很久以前或伪造未来时间的请求。

  // 在拦截器中校验时间戳 long clientTime = Long.parseLong(timestamp); long serverTime = System.currentTimeMillis(); if (Math.abs(serverTime - clientTime) > 5 * 60 * 1000) { // 抛出异常，返回“请求已过期”错误 }

• 随机数（nonce）校验：nonce是一个一次性使用的随机字符串。服务端需要维护一个短时间内（如时间戳校验窗口期）使用过的nonce缓存（可以用Redis或Guava Cache实现）。收到请求后，检查本次的nonce是否在缓存中存在。如果存在，说明是重放攻击，拒绝请求；如果不存在，则将本次nonce存入缓存，并设置一个短暂的过期时间（略大于时间戳窗口期）。

  // 使用Redis校验nonce (伪代码) String redisKey = “nonce:” + appId + “:” + nonce; Boolean isSet = redisTemplate.opsForValue().setIfAbsent(redisKey, “1”, Duration.ofMinutes(6)); if (Boolean.FALSE.equals(isSet)) { // nonce已存在，重放攻击！ }

两者结合，timestamp防止了“旧”请求，nonce防止了“同一时间窗口内”的重复请求，双管齐下，能有效抵御常见的重放攻击。

4. 实操过程与核心环节实现

4.1 第一步：创建签名生成工具类（客户端/服务端共用）

这个类负责核心的签名生成逻辑。为了确保客户端和服务端计算结果一致，这个工具类最好打成独立的Jar包供双方使用，或者将代码复制到两端。

import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import java.util.*; /** * 签名工具类 */ public class SignUtil { private static final String HMAC_SHA256 = “HmacSHA256”; /** * 生成签名 * @param params 所有待签名的参数（包含公共参数和业务参数） * @param secretKey 密钥 * @return 签名字符串（十六进制小写） * @throws Exception */ public static String generateSign(Map<String, String> params, String secretKey) throws Exception { // 1. 参数排序 List<String> keys = new ArrayList<>(params.keySet()); Collections.sort(keys); // 2. 拼接键值对 StringBuilder sb = new StringBuilder(); for (String key : keys) { String value = params.get(key); // 跳过空值参数 if (value == null || value.trim().isEmpty()) { continue; } // URL编码是关键！ String encodedKey = URLEncoder.encode(key, StandardCharsets.UTF_8.name()); String encodedValue = URLEncoder.encode(value, StandardCharsets.UTF_8.name()); if (sb.length() > 0) { sb.append(“&”); } sb.append(encodedKey).append(“=”).append(encodedValue); } String stringToSign = sb.toString(); // 3. 使用HMAC-SHA256计算签名 Mac mac = Mac.getInstance(HMAC_SHA256); SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA256); mac.init(secretKeySpec); byte[] hash = mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8)); // 4. 转换为十六进制字符串 return bytesToHex(hash).toLowerCase(); } /** * 字节数组转十六进制字符串 */ private static String bytesToHex(byte[] hash) { StringBuilder hexString = new StringBuilder(2 * hash.length); for (byte b : hash) { String hex = Integer.toHexString(0xff & b); if (hex.length() == 1) { hexString.append(‘0’); } hexString.append(hex); } return hexString.toString(); } /** * 模拟客户端生成签名（用于测试） */ public static void main(String[] args) throws Exception { Map<String, String> params = new HashMap<>(); params.put(“appId”, “your_app_id”); params.put(“timestamp”, String.valueOf(System.currentTimeMillis())); params.put(“nonce”, UUID.randomUUID().toString()); params.put(“page”, “1”); // 业务参数 params.put(“size”, “20”); // 业务参数 String secretKey = “your_secret_key_here”; String sign = generateSign(params, secretKey); System.out.println(“生成的签名: ” + sign); // 将sign放入请求头或参数中，随其他参数一起发送 params.put(“sign”, sign); } }

4.2 第二步：实现服务端签名验证拦截器

这是服务端的核心，我们通过实现HandlerInterceptor接口来创建拦截器。

import com.fasterxml.jackson.databind.ObjectMapper; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.redis.core.StringRedisTemplate; import org.springframework.stereotype.Component; import org.springframework.web.servlet.HandlerInterceptor; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.PrintWriter; import java.util.*; import java.util.concurrent.TimeUnit; /** * 签名认证拦截器 */ @Component public class SignAuthInterceptor implements HandlerInterceptor { @Autowired private SecretKeyService secretKeyService; // 密钥查询服务 @Autowired private StringRedisTemplate redisTemplate; // 用于nonce校验 @Autowired private ObjectMapper objectMapper; // JSON序列化 // 时间戳允许的误差（毫秒），例如5分钟 private static final long TIME_DIFF_TOLERANCE = 5 * 60 * 1000L; // nonce在Redis中的过期时间，略大于时间窗口 private static final long NONCE_EXPIRE_SECONDS = 6 * 60L; @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 1. 获取所有请求参数（兼容GET/POST） Map<String, String> paramMap = getAllRequestParams(request); // 2. 提取必要的公共参数 String appId = paramMap.get(“appId”); String timestampStr = paramMap.get(“timestamp”); String nonce = paramMap.get(“nonce”); String clientSign = paramMap.get(“sign”); // 客户端传来的签名 // 3. 基础参数校验 if (isEmpty(appId) || isEmpty(timestampStr) || isEmpty(nonce) || isEmpty(clientSign)) { returnError(response, 400, “缺少必要的认证参数”); return false; } // 4. 时间戳校验 long timestamp; try { timestamp = Long.parseLong(timestampStr); } catch (NumberFormatException e) { returnError(response, 400, “时间戳格式错误”); return false; } long currentTime = System.currentTimeMillis(); if (Math.abs(currentTime - timestamp) > TIME_DIFF_TOLERANCE) { returnError(response, 400, “请求已过期”); return false; } // 5. Nonce防重放校验 String nonceKey = “sign:nonce:” + appId + “:” + nonce; Boolean isNonceSet = redisTemplate.opsForValue().setIfAbsent(nonceKey, “1”, NONCE_EXPIRE_SECONDS, TimeUnit.SECONDS); if (Boolean.FALSE.equals(isNonceSet)) { returnError(response, 400, “请求重复”); return false; } // 6. 获取服务端存储的密钥 String serverSecretKey = secretKeyService.getSecretKeyByAppId(appId); if (serverSecretKey == null) { returnError(response, 401, “无效的应用标识”); return false; } // 7. 生成服务端签名（注意：签名时要去除sign参数本身） paramMap.remove(“sign”); // 移除客户端签名，不参与服务端签名计算 String serverSign; try { serverSign = SignUtil.generateSign(paramMap, serverSecretKey); } catch (Exception e) { returnError(response, 500, “服务器签名计算错误”); return false; } // 8. 签名比对 if (!serverSign.equalsIgnoreCase(clientSign)) { // 忽略大小写比较 returnError(response, 401, “签名验证失败”); return false; } // 9. 验证通过，将appId放入请求属性，供后续业务使用 request.setAttribute(“authAppId”, appId); return true; } /** * 从HttpServletRequest中获取所有参数（支持Query String和Form Data） */ private Map<String, String> getAllRequestParams(HttpServletRequest request) { Map<String, String> paramMap = new HashMap<>(); // 获取URL上的参数 Enumeration<String> paramNames = request.getParameterNames(); while (paramNames.hasMoreElements()) { String paramName = paramNames.nextElement(); paramMap.put(paramName, request.getParameter(paramName)); } // 注意：如果是POST JSON，这种方式获取不到。需要额外处理，见下文“注意事项”。 return paramMap; } /** * 返回错误信息（JSON格式） */ private void returnError(HttpServletResponse response, int httpStatus, String message) throws IOException { response.setStatus(httpStatus); response.setContentType(“application/json;charset=UTF-8”); Map<String, Object> error = new HashMap<>(); error.put(“code”, httpStatus); error.put(“message”, message); error.put(“timestamp”, System.currentTimeMillis()); String json = objectMapper.writeValueAsString(error); PrintWriter writer = response.getWriter(); writer.write(json); writer.flush(); } private boolean isEmpty(String str) { return str == null || str.trim().isEmpty(); } }

4.3 第三步：配置拦截器与密钥服务

1. 注册拦截器到Spring MVC创建一个配置类，将我们写好的拦截器注册到需要保护的URL路径上。

import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.InterceptorRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; @Configuration public class WebConfig implements WebMvcConfigurer { @Autowired private SignAuthInterceptor signAuthInterceptor; @Override public void addInterceptors(InterceptorRegistry registry) { // 拦截所有以 /api/ 开头的请求，进行签名认证 // 排除登录、公开接口等路径 registry.addInterceptor(signAuthInterceptor) .addPathPatterns(“/api/**”) .excludePathPatterns(“/api/public/**”, “/api/login”); } }

2. 实现简单的密钥服务这里用一个模拟的内存服务来演示，实际项目中请替换为从数据库或缓存中读取。

import org.springframework.stereotype.Service; import java.util.concurrent.ConcurrentHashMap; @Service public class SecretKeyService { // 模拟一个存储appId和secretKey的Map，实际应从数据库读取 private static final ConcurrentHashMap<String, String> KEY_STORE = new ConcurrentHashMap<>(); static { // 初始化测试数据 KEY_STORE.put(“test_app_001”, “d2f4a5c8e7b1a093c6d8f2e5b7a4c901”); KEY_STORE.put(“iot_device_123”, “a8e7f2b5d1c4a093c6d8f2e5b7a4c567”); } public String getSecretKeyByAppId(String appId) { // 这里可以加入缓存逻辑，比如先从Redis读，没有再查DB return KEY_STORE.get(appId); } // 可以添加刷新缓存、更新密钥等方法 }

4.4 第四步：客户端调用示例

客户端在调用受保护的接口时，需要按照规则组装参数并计算签名。以下是一个使用Java HttpClient的示例：

import org.apache.http.client.methods.HttpGet; import org.apache.http.client.utils.URIBuilder; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import java.net.URI; import java.util.*; public class ApiClient { private static final String APP_ID = “test_app_001”; private static final String SECRET_KEY = “d2f4a5c8e7b1a093c6d8f2e5b7a4c901”; private static final String BASE_URL = “http://localhost:8080/api/user/list”; public static void main(String[] args) throws Exception { // 1. 构建业务参数和公共参数 Map<String, String> params = new HashMap<>(); params.put(“appId”, APP_ID); params.put(“timestamp”, String.valueOf(System.currentTimeMillis())); params.put(“nonce”, UUID.randomUUID().toString().replace(“-”, “”)); // 业务参数 params.put(“page”, “1”); params.put(“size”, “10”); params.put(“status”, “active”); // 2. 生成签名 String sign = SignUtil.generateSign(params, SECRET_KEY); params.put(“sign”, sign); // 将签名加入请求参数 // 3. 构建带参数的URL (GET请求示例) URIBuilder uriBuilder = new URIBuilder(BASE_URL); for (Map.Entry<String, String> entry : params.entrySet()) { uriBuilder.addParameter(entry.getKey(), entry.getValue()); } URI uri = uriBuilder.build(); // 4. 发送请求 try (CloseableHttpClient httpClient = HttpClients.createDefault()) { HttpGet httpGet = new HttpGet(uri); // 执行请求并处理响应... // HttpResponse response = httpClient.execute(httpGet); System.out.println(“请求URL: ” + uri); } } }

对于POST请求（特别是application/json），签名逻辑不变，但需要特别注意：签名参数应包含请求体（Body）中的JSON内容。常见的做法是，将JSON字符串作为一个特殊的参数（如body）参与签名，或者将JSON对象扁平化为键值对。这需要客户端和服务端约定一致的处理规则。

5. 常见问题与排查技巧实录

在实际开发和联调中，签名认证最容易出现的问题就是客户端和服务端生成的签名不一致。下面是我总结的排查清单和技巧。

5.1 签名不一致问题排查表

当验签失败时，可以按照下表顺序逐一排查：

5.2 调试与日志记录技巧

为了快速定位问题，必须在关键位置打日志。

在服务端拦截器中，增加详细日志：

// 在SignAuthInterceptor的preHandle方法中关键节点加入日志 log.info(“[SignAuth] 接收到请求。URI: {}, Params: {}”, request.getRequestURI(), paramMap); log.info(“[SignAuth] 客户端签名: {}”, clientSign); log.info(“[SignAuth] 服务端根据appId: {} 查到的密钥: {}”, appId, serverSecretKey); // 在调用SignUtil.generateSign之前，打印出待签名的参数Map log.info(“[SignAuth] 参与服务端签名的参数: {}”, paramMap); log.info(“[SignAuth] 服务端计算出的签名: {}”, serverSign);

在客户端，同样记录生成签名前的状态：

// 在调用SignUtil.generateSign之前 System.out.println(“[Client] 签名前的参数Map: ” + params); System.out.println(“[Client] 使用的密钥: ” + SECRET_KEY);

通过对比双方日志中的“参与签名的参数”和“计算出的签名”，绝大多数问题都能一目了然。

5.3 关于POST JSON请求的签名处理

这是一个需要特别关注的场景。我们的拦截器默认的getAllRequestParams方法只能获取Query String和Form Data，无法直接获取Request Body中的JSON内容。

解决方案有两种：

方案一：将整个JSON字符串作为一个参数

1. 客户端在发送前，将JSON请求体转换为字符串。
2. 将这个字符串作为一个特殊的参数（如_body）放入签名参数Map中。
3. 服务端拦截器需要读取HttpServletRequest的输入流，获取JSON字符串，同样以_body为key放入参数Map。
4. 注意：请求体流只能读一次，需要配合ContentCachingRequestWrapper这类包装类来重复读取。

方案二：将JSON对象扁平化为键值对

1. 客户端将JSON对象递归展开，变成{“user.name”: “张三”, “user.age”: 20}这样的Map。
2. 将这个Map合并到总的签名参数Map中。
3. 服务端做同样的扁平化处理。
4. 这种方式更复杂，但签名粒度更细。

我的建议是：对于内部系统或性能要求不高的场景，使用方案一，简单可靠。关键是要在技术文档中明确约定这个特殊参数的key（如_body或payload）。

5.4 性能与扩展性考量

• 性能：HMAC-SHA256计算是轻量级的，主要开销在于网络I/O和可能的缓存查询（如Redis查nonce）。在网关或拦截器层面，确保密钥和nonce缓存的命中率，对性能至关重要。
• 扩展性：
  • 多算法支持：可以在appId对应的配置信息中增加一个signType字段，标识该客户端使用的签名算法（如HMAC-SHA256,MD5等），拦截器根据类型调用不同的验证逻辑。
  • 差异化配置：不同的appId可以配置不同的TIME_DIFF_TOLERANCE（时间容差）或是否强制校验nonce，以适应不同客户端（如设备、浏览器、其他服务）的时钟同步能力和请求特性。
  • 监控与告警：记录验签失败的日志，并监控失败频率。短时间内来自同一appId的大量验签失败，可能是密钥泄露或攻击行为，应及时告警。

这套自研的签名认证方案，从设计到实现，每一个环节都需要仔细考量。它没有黑魔法，所有的安全都建立在“规则一致”和“密钥保密”这两个基石之上。在那些不适合引入重型框架的场景下，它提供了一个清晰、可控、高效的安全选择。记住，无论方案多么简单，严谨的测试和充分的日志是它在生产环境稳定运行的保障。