正确构造HMAC-SHA256签名需严格按字典序排序参数、URL-safe编码（quote非quote_plus）、密钥与消息均转bytes；timestamp和nonce须符合服务端时效与唯一性要求。

Python 接口签名用 HMAC 实现并不难，但参数顺序、编码方式、密钥处理稍有偏差就会返回 401 Unauthorized 或 signature mismatch —— 这类问题 80% 出在字符串拼接前没统一编码或忽略空格/换行。

如何正确构造 HMAC-SHA256 签名字符串

签名本质是「对确定顺序的参数做确定方式的摘要」。服务端和客户端必须严格一致：参数先按 key 字典序排序，再拼成 key1=value1&key2=value2 形式，且所有 value 必须做 URL-safe 的 urllib.parse.quote（不是 quote_plus），空格要编码为 %20 而非 +。

常见错误：

• 用 json.dumps() 直接序列化 dict → 键顺序不固定，且引号、空格、斜杠编码不匹配
• 拼接时漏掉必填字段（如 timestamp、nonce），或传了服务端未约定的字段
• value 中含中文但没 encode('utf-8') 就喂给 hmac.new() → Python 3 下会报 TypeError: key must be bytes or bytearray

Python 中调用 hmac.new() 的关键写法

hmac.new() 的 key 和 msg 都必须是 bytes，且服务端通常要求密钥是原始字节（不是 base64 解码后、也不是 hex 解码后）。如果 API 文档给的是 base64 格式的 secret，得先 base64.b64decode()；如果是十六进制字符串（如 "a1b2c3..."），得用 bytes.fromhex()。

示例（标准流程）：

import hmac
import hashlib
import urllib.parse
params = {
"appid": "abc123",
"timestamp": "1718234567",
"nonce": "xYz9AbC",
"data": "hello 世界"
}
1. 按 key 排序并 url-quote value（保留斜杠，不编码 /）
sorted_items = sorted(params.items())
query_string = "&".join(f"{k}={urllib.parse.quote(v, safe='')}" for k, v in sorted_items)
2. 密钥处理：假设 secret 是 base64 编码的字节串
secret_b64 = "dGhpcyBpcyBhIHNlY3JldA=="
secret_bytes = base64.b64decode(secret_b64)
3. 计算签名（注意 msg 也必须是 bytes）
signature = hmac.new(
key=secret_bytes,
msg=query_string.encode('utf-8'),
digestmod=hashlib.sha256
).digest()
4. 通常要求 base64 编码结果（不是 hex）
signature_b64 = base64.b64encode(signature).decode('ascii')

timestamp 和 nonce 的实际约束不能忽略

很多接口要求 timestamp 是秒级 Unix 时间戳，且与服务器时间偏差不超过 300 秒；nonce 必须每次唯一（常用 uuid.uuid4().hex[:16] 或 secrets.token_urlsafe(16)），服务端会缓存最近 N 个 nonce 防重放。这两项若校验失败，签名即使完全正确也会被拒。

调试建议：

• 先用固定 timestamp 和 nonce（如 "1718234567" 和 "testnonce"）跑通一次，排除动态值干扰
• 把最终拼出的 query_string 打印出来，和服务端日志里的原始待签名串比对（注意空格、编码、大小写）
• 确认服务端是否对参数做了额外清洗（例如自动 trim 空格、强制小写 key）

为什么签名总对不上？优先检查这三处

绝大多数签名失败不是算法写错，而是「输入不一致」：

• urllib.parse.quote(value, safe='') != urllib.parse.quote_plus(value)：后者把空格变 +，前者变 %20，多数接口要求后者
• 密钥用了字符串直接传入 hmac.new() → 必须显式 .encode('utf-8') 或 base64.b64decode()
• 拼接前没排序，或排序用了 dict.keys()（无序），或用了 json.dumps(dict, sort_keys=True)（带空格和引号）

只要 query_string 字符串和服务端完全一致，HMAC 结果就一定一致。调试时宁可多打一行 print(repr(query_string))，也别靠猜。