签名校验必须包含时间戳以防止重放攻击，服务端通过校验timestamp与当前时间差值（如>300秒则拒绝）确保请求时效性，要求客户端和服务端时钟误差在容忍范围内。
签名校验为什么必须包含时间戳
不加时间戳的签名只是防篡改，不是防重放。攻击者截获一次合法请求后，可以无限次重放，服务端无法识别这是旧请求还是新请求。
时间戳的作用是让签名具备“时效性”。服务端收到请求后，会比对 timestamp 与当前服务器时间的差值，超出阈值（如 300 秒）即拒绝。这要求客户端和服务端时钟尽量同步，但不必完全一致——只要误差控制在容忍范围内即可。
-
timestamp必须是秒级或毫秒级整数，推荐用int(time.time())（秒）或int(time.time() * 1000)（毫秒） - 服务端应使用系统本地时间（非 NTP 校准后的时间），避免引入额外依赖
- 客户端传
timestamp=1715823456，服务端收到后计算abs(server_time - 1715823456) > 300，超时则直接返回 401
Python 中生成标准 HMAC-SHA256 签名的写法
签名原文必须固定顺序、不可省略字段、不能带空格或换行。常见错误是拼接时用了字典默认遍历顺序（Python 3.7+ 虽然有序，但不显式排序仍属隐患），或漏掉 timestamp 和 nonce。
推荐签名原文格式：method|path|timestamp|nonce|body_md5（其中 body_md5 是请求体的 MD5 小写十六进制值，空体为 md5("").hexdigest()）
立即学习“Python免费学习笔记（深入）”；
import hmac
import hashlib
import json
<p>def gen_signature(secret_key: str, method: str, path: str, timestamp: int, nonce: str, body: bytes) -> str:
body_md5 = hashlib.md5(body).hexdigest()
msg = f"{method}|{path}|{timestamp}|{nonce}|{body_md5}".encode()
key = secret_key.encode()
sig = hmac.new(key, msg, hashlib.sha256).digest()
return sig.hex()</p>-
secret_key应从环境变量或配置中心加载，禁止硬编码 -
nonce每次请求唯一，建议用uuid.uuid4().hex或 16 字节随机字符串 - 若接口支持 GET 无 body，
body传b""即可，不要传None
Flask/FastAPI 中验证签名与时间戳的典型陷阱
验证逻辑必须放在中间件或装饰器最前侧，且在解析 JSON 之前完成。否则攻击者可能通过畸形 JSON 触发解析异常，绕过校验。
另一个高频问题是：从 request.headers 取 X-Signature 时未做大小写归一化，而某些代理（如 Nginx）会把下划线转成中划线或小写。
- 始终用
request.headers.get("X-Signature", "").strip()，并统一转小写比对 - 时间戳校验必须在签名比对之前做——如果先算签名再比时间，攻击者仍可重放旧签名
- FastAPI 中若用
Depends()做鉴权，需确保该依赖不依赖Body()，否则会提前触发解析 - Flask 示例中，
request.get_data(cache=True)必须调用一次，否则后续request.json会为空
body_md5 计算容易被忽略的边界情况
很多人直接对 request.get_json() 结果做 json.dumps 再哈希，这是错的：原始 body 可能含空格、换行、Unicode 转义，而 json.dumps 默认参数会导致输出不一致。
正确做法是直接读原始字节流，并注意编码。POST/PUT 的 body 不一定是 UTF-8，但绝大多数 API 约定为 UTF-8；若不确定，应以 Content-Type 中的 charset 为准，无声明时默认 UTF-8。
- 用
request.get_data()获取原始bytes，不要用.stream.read()后再 decode 再 encode - GET 请求没有 body，但签名公式里仍要参与
body_md5计算，此时必须是空字符串的 MD5："d41d8cd98f00b204e9800998ecf8427e" - 若前端发送的是
application/x-www-form-urlencoded，body 是键值对字符串（如a=1&b=2），也应原样哈希，不要解析后再拼
签名机制本身不难实现，真正难的是所有环节保持严格一致：客户端拼接顺序、编码方式、时间精度、空值处理——任一环节错位，服务端就验签失败。线上问题往往卡在某个字段多了一个空格，或时间戳用了毫秒却服务端按秒判断。
