API 请求签名算法文档

1. 概述

为了保证 API 请求数据的完整性、防止请求参数被篡改，接口采用：

HMAC-SHA1
Base64 编码

作为请求签名算法。

客户端调用 API
时，需要按照约定规则对请求参数进行排序、拼接，然后使用应用密钥（Secret）计算签名。

服务端收到请求后，使用相同算法重新计算签名，并与客户端提交的签名进行比对。

2. 签名流程

3. 应用认证信息

参数类型说明

appId String 应用唯一标识
secret String 应用密钥，用于签名计算
version String API版本号，默认 1.0

Secret 只能保存在服务端，不允许暴露给客户端。

4. 请求签名参数

参数类型必填说明

appId String 是应用ID
nonce String 是随机字符串
timestamp Long 是 Unix时间戳（秒）
data String 是业务数据
version String 是接口版本
signature String 是签名结果

示例：

{
    "appId": "test_app_001",
    "nonce": "abc123",
    "timestamp": 1754870400,
    "version": "1.0",
    "data": "{\"userId\":10001}",
    "signature": "xxxxxxxx"
}

5. 签名生成算法

5.1 参数排序

所有参与签名的参数按照参数名称 ASCII 升序排序。

排序示例：

appId
data
nonce
timestamp
version

5.2 参数拼接

按照：

key=value

格式生成字符串。

多个参数使用：

连接。

示例：

appId=test_app&data=hello&nonce=abc&timestamp=1754870400&version=1.0

5.3 HMAC-SHA1计算

计算：

HMAC-SHA1(secret, plainText)

5.4 Base64编码

最终签名：

signature = Base64(HMAC-SHA1结果)

6. 签名生成伪代码

function makeSign(params, secret){

    const plainText = Object.keys(params)
        .sort()
        .map(key => `${key}=${params[key]}`)
        .join("&");

    const sha1 = HmacSHA1(
        plainText,
        secret
    );

    return Base64(sha1);
}

7. 请求参数生成规则

data处理

如果 data 是对象：

JSON.stringify(data)

转换为字符串后参与签名。

timestamp

单位：

秒

生成：

Math.floor(Date.now() / 1000)

8. 服务端验签流程

收到请求

|
↓

检查 timestamp 是否有效

|
↓

移除 signature 字段

|
↓

重新计算签名

|
↓

比较 signature

|
↓

一致: 请求合法

不一致: 拒绝请求

9. 时间有效性校验

默认有效时间：

90秒

规则：

当前时间戳 - 请求timestamp <= 90

超过有效时间：

拒绝请求

10. nonce规则

nonce 用于防止请求重放攻击。

建议：

项目推荐

长度 >=16字符
类型随机字符串
使用次数单次请求唯一

11. data一致性要求

参与签名的 data 必须保持完全一致。

例如：

{"a":1,"b":2}

和：

{"b":2,"a":1}

虽然 JSON 含义相同，但是字符串不同，会导致签名不一致。

客户端和服务端必须统一序列化规则。

12. 签名字段总结

参与签名：