📚 课程目录第4章签名流程设计

4. 签名流程设计：客户端生成签名与服务端验证流程

签名流程到底怎么做？说白了，就是两端各自算一个相同的值。客户端算出来，塞进请求里；服务端收到请求，用自己的参数再算一遍。两个值对上，就放行；对不上，直接打回。

这个过程看似简单，但坑不少。我记得早年有个项目，就因为客户端和服务端排序方式不一致，线上排查了整整一个下午。嗯，从那儿以后，我再也不敢在签名算法上偷懒了。

4.1 整体流程概览

先看大图，后面再细拆每个步骤。

核心原则：签名是一种对称验证机制。不加密数据，只验证身份和数据的完整性。

4.2 客户端签名生成

客户端要做的事情可以拆成四个小步骤。每个步骤我都在生产环境里踩过坑，你注意看避坑指南。

步骤一：组装请求参数

把所有需要签名的业务参数，加上系统参数（比如 app_id、timestamp、nonce），全部收集到一个 Map 或字典里。

业务参数：比如转账金额、订单号、商品 ID。这些是请求的核心数据。
系统参数：app_id（告诉服务端你是谁）、timestamp（防重放）、nonce（防重放）。

我曾经遇到过一个坑：某个参数值为空时，团队有人把它传成了 null，有人传成了空字符串。服务端验证签名时永远对不上。记住，空值必须统一处理规则——要么丢弃，要么转为空字符串。

步骤二：参数排序与拼接

拿到参数列表后，按照参数名的字典序升序排列。然后拼接成 key1=value1&key2=value2 的字符串。

排序必须用字典序（ASCII 码顺序），大小写敏感。
去掉 sign 本身（签名参数不参与签名计算）。
去掉值为空或 null 的参数（提前约定好）。

你想想看，如果客户端按 a、b、c 排序，服务端按 c、b、a 排序，结果肯定不一样。所以这个排序规则必须是明文写在接口文档里的死约定。

步骤三：追加密钥并计算签名

在拼接好的字符串末尾，追加一个 &key=YOUR_SECRET_KEY。然后对这个完整的字符串做哈希计算，比如 MD5 或 SHA256。得到的结果就是最终签名。


// 伪代码示例：客户端生成签名
function generateSignature(params, secretKey) {
    // 1. 移除签名字段本身（如果有）
    delete params.sign
    
    // 2. 按字典序排序
    const sortedKeys = Object.keys(params).sort()
    
    // 3. 拼接成 key=value 格式
    const queryString = sortedKeys
        .map(key => `${key}=${params[key]}`)
        .join('&')
    
    // 4. 追加密钥
    const stringToSign = queryString + '&key=' + secretKey
    
    // 5. 计算 MD5 签名（实际项目中建议 SHA256）
    return md5(stringToSign).toUpperCase()
}

我个人的习惯：签名计算结果统一转成大写。MD5 或 SHA256 返回的十六进制串本来就有大小写，统一大写能减少不必要的比对失误。

步骤四：将签名放入请求

签名计算完成后，把它作为 sign 参数，和其他业务参数一起传入请求。

4.3 服务端签名验证

服务端收到请求后，并不是拿到参数直接验签就完事了。我个人建议按顺序走完下面这几步，缺一步都可能埋坑。

第一步：参数校验

检查必填参数是否存在：app_id、timestamp、nonce、sign。
检查 timestamp 是否在有效时间范围内（比如允许前后 5 分钟的时间差）。
检查 nonce 是否已经使用过（可以用 Redis 做去重，设置过期时间）。

我曾经见过一个线上事故：服务器时间比客户端慢了 10 分钟，所有合法请求都被拒了。嗯，后来我们在时间窗上加了 5 分钟的宽容度，并且在 NTP 服务挂了的时候有降级方案。

第二步：签名校验

服务端用与客户端完全相同的规则，重新计算一遍签名。然后拿计算出的签名和请求中的 sign 比对。


// 伪代码示例：服务端验证签名
function verifySignature(requestParams, secretKey) {
    // 1. 提取客户端签名
    const clientSign = requestParams.sign
    delete requestParams.sign  // 后续计算用不到
    
    // 2. 相同规则计算服务端签名
    const sortedKeys = Object.keys(requestParams).sort()
    const queryString = sortedKeys
        .map(key => `${key}=${requestParams[key]}`)
        .join('&')
    const stringToSign = queryString + '&key=' + secretKey
    const serverSign = md5(stringToSign).toUpperCase()
    
    // 3. 核心比对
    return serverSign === clientSign
}

第三步：时间窗 + Nonce 防重放

签名本身不能防止请求被拦截重发。你想想看，攻击者可以完整截获请求包，带上签名再次发送。这就靠 timestamp 和 nonce 来防范。

机制	说明	建议配置
timestamp	请求发起时间，用于判断是否在有效窗口内	允许 ±5 分钟误差
nonce	一次性随机字符串，每个请求唯一	Redis 存储，TTL 设为 10 分钟
双重检查	先过时间窗，再查 nonce 是否已用	两者必须同时通过

第四步：记录日志

不管是验证通过还是失败，建议把签名计算过程中的关键信息记录下来。出了问题，排查全靠日志。

收到原始参数列表
排序后的拼接字符串
计算出的服务端签名
客户端传入的签名
比对结果（通过/失败）

我个人习惯在日志里把拼接后的待签字符串也打出来，但要注意脱敏——密钥不要打明文。可以用 key=*** 代替真实密钥值。

4.4 关键实现细节

刚才说的是流程，现在聊几个我从实际项目里总结的细节。嗯，这几个点能帮你少走不少弯路。

签名算法选择

MD5 虽然快，但不够安全。SHA256 是目前比较主流的做法。你要是做金融级别的接口，可以考虑用 HMAC-SHA256。


// HMAC-SHA256 示例（推荐等级：高）
function generateHmacSignature(params, secretKey) {
    delete params.sign
    const sortedKeys = Object.keys(params).sort()
    const queryString = sortedKeys
        .map(key => `${key}=${params[key]}`)
        .join('&')
    
    // HMAC 直接把密钥作为 HMAC 密钥传入，不用拼到字符串末尾
    const hmac = crypto.createHmac('sha256', secretKey)
    hmac.update(queryString)
    return hmac.digest('hex').toUpperCase()
}

常见错误对照表

错误类型	现象	解决方案
排序不一致	客户端和服务端签名永远对不上	统一使用字典序，明确写出排序规则
空值处理不同	某个参数为空时签名不匹配	约定：空字符串保留，null 丢弃
类型不一致	数字 123 被拼成 "123" 或 123	所有值统一转字符串
编码不一致	URL 编码后的签名对不上	签名原始字符串用原始值，不做 URL 编码

4.5 总结性清单

我把上面的流程浓缩成操作清单，你自己开发的时候可以照着核对。

    事前约定：客户端和服务端同步相同的签名规则、密钥、排序方式、空值处理规则。
客户端动作：收集参数 → 字典排序 → 拼接 &key=secret → 哈希计算 → 放入请求。
服务端动作：校验必填 → 校验时间窗 → 校验 nonce → 相同规则重算签名 → 比对 → 返回结果。
防守机制：时间窗防重放 + nonce 唯一性 + 失败日志记录。

做签名认证这么多年，我最深的体会就是：规则越透明，线上越省心。把排序规则、空值处理、签名算法、密钥管理全都写进文档，开发时对照着来，基本不会出大问题。