punchnet-android/Sign.md

接口签名算法说明

概述

本接口使用 HMAC-MD5 算法对请求参数进行签名，以确保请求的合法性与完整性，防止请求被篡改或伪造。 生成的sign值放在header中，key=X-sign，value=加密值。

---

签名生成流程

请求参数
    │
    ▼
① 参数递归排序（ksort）
    │
    ▼
② 构造签名字符串（key=value&key=value...）
    │   数组/对象类型 → JSON 字符串
    ▼
③ HMAC-MD5(query_string, secret_key)
    │
    ▼
sign（签名结果）

---

详细步骤

第一步：参数递归排序

对所有请求参数按照键名字典序（ksort）进行递归排序，嵌套数组也需同样处理，以保证双方构造字符串的顺序一致。

第二步：构造签名字符串

遍历排序后的参数，按以下规则拼接为字符串：

参数类型	处理方式
普通值（字符串、数字等）	直接使用原始值
数组 / 对象	转为 JSON 字符串（中文不转义，JSON_UNESCAPED_UNICODE）

拼接格式：

key1=value1&key2=value2&key3=value3

⚠️ 注意：参数值不做 URL encode，与 http_build_query 的行为不同。数组参数也不展开为 key[0]=... 形式，而是整体转为 JSON 字符串。

第三步：计算签名

使用 secret_key 对上一步得到的字符串执行 HMAC-MD5 计算：

sign = HMAC-MD5(query_string, secret_key)

---

示例

原始请求参数

{
  "uid": 1001,
  "amount": 100,
  "currency": "CNY",
  "items": [
    { "id": 1, "name": "商品A" }
  ]
}

第一步：排序后的参数顺序

amount, currency, items, uid

第二步：构造签名字符串

amount=100&currency=CNY&items=[{"id":1,"name":"商品A"}]&uid=1001

第三步：计算签名

sign = HMAC-MD5("amount=100&currency=CNY&items=[{\"id\":1,\"name\":\"商品A\"}]&uid=1001", "your_secret_key")

---

注意事项

项目	说明
排序方式	字典序递归排序，嵌套数组也要排序
数组参数	转为 JSON 字符串，中文不转义（JSON_UNESCAPED_UNICODE）
URL 编码	参数值不做 URL encode
数组展开	不展开为 key[0]=... 形式
密钥管理	secret_key 需双方提前约定，严禁在请求中传输
算法	HMAC-MD5，输出为 32 位十六进制小写字符串

---

密钥： H6p*2RfEu4ITcL