必须用 hmac-sha256 而非 md5 或拼接字符串，因其可防篡改与鉴权，避免密钥泄露、重放攻击及长度扩展攻击；md5 无密钥、不安全，拼接方式易被逆向；hmac-sha256 是生产环境事实标准，python hmac 模块原生支持且密钥不传输。
签名验证为什么必须用 HMAC-SHA256 而不是 MD5 或拼接字符串
因为 API 签名的核心目标是防篡改 + 鉴权，不是简单混淆。用 MD5 或直接拼接 secret_key + params 会暴露密钥、易被重放、无法抵御长度扩展攻击。生产环境必须用带密钥的哈希算法，HMAC-SHA256 是事实标准——Python 的 hmac 模块原生支持，且密钥不参与明文传输。
常见错误现象：signature mismatch 却反复检查参数顺序，实际是服务端用了 HMAC-SHA256，客户端却用 hashlib.md5((key+data).encode()).hexdigest() 计算，结果必然不一致。
- 签名原文必须严格按服务端约定排序（通常是字典序）并拼接，例如
a=1&b=2&c=3，不能用json.dumps()或 URL 编码后的乱序字符串 - 所有参数值必须先做
urllib.parse.quote_plus()（不是quote()），空格转+，否则和 Java/Go 服务端行为不一致 - 密钥
secret_key绝对不能硬编码在代码里，应从环境变量读取：os.getenv("API_SECRET")
requests 发送前自动加签：封装一个可复用的 sign_request 函数
别每次手写签名逻辑。把签名过程抽成函数，输入 method、url、params、body、api_key、secret_key，输出带 Authorization 或 X-Signature 头的 requests.Request 对象。
关键点在于：GET 请求签名原文 = method + "\n" + path + "\n" + sorted_query_string + "\n"；POST/JSON 请求则需先 json.dumps(body, separators=(",", ":")) 去空格，再参与签名，且 Content-Type: application/json 必须包含在签名原文中（有些平台要求）。
import hmac, hashlib, urllib.parse, json
def sign_request(method, url, params=None, body=None, api_key="", secret_key=""):
parsed = urllib.parse.urlparse(url)
path = parsed.path
query = urllib.parse.urlencode(sorted(params.items())) if params else ""
# 签名原文：换行分隔，不含 scheme 和 host
sig_base = f"{method.upper()}\n{path}\n{query}\n"
if body and isinstance(body, dict):
body_str = json.dumps(body, separators=(",", ":"))
sig_base += body_str
elif isinstance(body, str):
sig_base += body
# 计算 HMAC-SHA256 并转十六进制
signature = hmac.new(
secret_key.encode(),
sig_base.encode(),
hashlib.sha256
).hexdigest()
return {
"headers": {
"Authorization": f"HMAC-SHA256 {api_key}:{signature}",
"Content-Type": "application/json"
},
"params": params,
"json": body if isinstance(body, dict) else None,
"data": body if isinstance(body, str) else None
}
时间戳和随机串（nonce）不是可选项，而是防重放的必要条件
没有 timestamp 和 nonce 的签名等于没签。服务端必须校验 timestamp 是否在 ±5 分钟内，且 nonce 在窗口期内未出现过。客户端不传，或传了但格式错（如 timestamp=1717023456.123 带毫秒，而服务端只接受整数秒），都会导致 401 Unauthorized。
-
timestamp必须用int(time.time())，不是datetime.now().isoformat() -
nonce推荐用secrets.token_urlsafe(16)（Python 3.6+），不用uuid.uuid4().hex，避免熵不足 - 这两个字段必须参与签名原文计算，且和服务端约定位置一致（通常放在
params最前面或最后面）
调试时怎么快速比对签名原文是否和服务端一致
最有效的方法：在客户端签名函数里加一行 print(repr(sig_base))，同时让后端开发把他们收到并用于计算的 sig_base 也打日志（脱敏后）。90% 的签名失败问题出在两端对“签名原文”的定义不一致——比如一方对 params 做了 quote_plus，另一方用了 quote；或者一方把 body 当字符串拼，另一方当 JSON 对象序列化。
不要依赖在线 HMAC 工具验证，那些工具没法模拟 urllib.parse.quote_plus("a b") → "a+b" 这种细节。本地写个最小脚本，把服务端文档给的示例请求完整复现一遍，逐字符比对 sig_base 输出。
容易被忽略的地方：某些 API 要求签名原文末尾带换行符（\n），少一个就失败；还有些强制要求所有参数名小写，哪怕你传了 APIKey，服务端也会转成 apikey 再签名——这些细节必须抠到文档字缝里。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
