正确构造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()。
立即学习“Python免费学习笔记（深入）”；
示例（标准流程）：
import hmac
import hashlib
import urllib.parse
<p>params = {
"appid": "abc123",
"timestamp": "1718234567",
"nonce": "xYz9AbC",
"data": "hello 世界"
}</p><h1>1. 按 key 排序并 url-quote value（保留斜杠，不编码 /）</h1><p>sorted_items = sorted(params.items())
query_string = "&".join(f"{k}={urllib.parse.quote(v, safe='')}" for k, v in sorted_items)</p><h1>2. 密钥处理：假设 secret 是 base64 编码的字节串</h1><p>secret_b64 = "dGhpcyBpcyBhIHNlY3JldA=="
secret_bytes = base64.b64decode(secret_b64)</p><h1>3. 计算签名（注意 msg 也必须是 bytes）</h1><p>signature = hmac.new(
key=secret_bytes,
msg=query_string.encode('utf-8'),
digestmod=hashlib.sha256
).digest()</p><h1>4. 通常要求 base64 编码结果（不是 hex）</h1><p>signature_b64 = base64.b64encode(signature).decode('ascii')</p>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))，也别靠猜。
