HMAC-SHA256 请求签名与验签实践（Python 可直接复用）

• 目标：沉淀一套“能复制即用”的签名/验签规范与代码，解决接口防篡改与防伪造。
• 关键规则：
  • 待签名串：METHOD + "\n" + Content-MD5 + "\n" + URI_PATH + [ "?" + sorted_query ]
  • Content-MD5：对“原始请求体字节”计算 MD5，hex 小写
  • Query：对 key 做升序排序；同 key 多值取第一个；拼接为 k=v&k2=v2
  • 签名：HMAC-SHA256(secret_bytes, utf8(string_to_sign)) → hex 小写

签名规范

• 待签名串
  • METHOD 使用大写，如 POST、GET
  • URI_PATH 仅路径，不包含协议/域名/端口，例如 /open_api/query/template
  • 若无 query，省略 ? 部分
• Content-MD5
  • 取“原始 body 字节”做 MD5；空 body 视为空字节
  • JSON 场景需使用“紧凑 JSON”序列化：separators=(',', ':'), ensure_ascii=False，UTF-8 编码
• Query 处理
  • key 升序；多值取第一个；不做 URL 编码二次处理（与客户端保持一致）
• 签名算法
  • HMAC-SHA256，密钥为字节串，输出十六进制小写

可直接复用代码（签名 + 验签）

import hmac
import hashlib
import json
from typing import Dict, Iterable, Tuple, Union, Optional
from urllib.parse import urlparse, parse_qsArgsType = Optional[Dict[str, Union[str, Iterable[str]]]]def _compact_json_bytes(body: Optional[dict]) -> bytes:"""将字典转为“紧凑 JSON”UTF-8字节；None/空字典→空字节"""if not body:return b""raw = json.dumps(body, separators=(",", ":"), ensure_ascii=False)return raw.encode("utf-8")def _sorted_query(args: ArgsType) -> str:"""将 query 参数按 key 升序拼接为 k=v&k2=v2。多值取第一个。None 或空返回 ""。"""if not args:return ""keys = sorted(args.keys())pairs = []for k in keys:v = args[k]if isinstance(v, (list, tuple, set)):v = list(v)[0] if v else ""pairs.append(f"{k}={v}")return "&".join(pairs)def build_string_to_sign(http_method: str,uri_path: str,args: ArgsType,body_bytes: bytes,
) -> Tuple[str, str]:"""构造待签名串与 content_md5（hex 小写）返回: (string_to_sign, content_md5)"""method = http_method.upper()content_md5 = hashlib.md5(body_bytes).hexdigest()qs = _sorted_query(args)uri_and_qs = f"{uri_path}?{qs}" if qs else uri_pathstring_to_sign = f"{method}\n{content_md5}\n{uri_and_qs}"return string_to_sign, content_md5def generate_signature(http_method: str,uri_path: str,args: ArgsType,body: Optional[dict],secret: Union[str, bytes],
) -> Tuple[str, bytes, str]:"""生成签名返回: (signature_hex, body_bytes, string_to_sign)"""if isinstance(secret, str):secret = secret.encode("utf-8")body_bytes = _compact_json_bytes(body)string_to_sign, _ = build_string_to_sign(http_method, uri_path, args, body_bytes)signature = hmac.new(secret, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()return signature, body_bytes, string_to_signdef verify_signature(http_method: str,uri_path: str,args: ArgsType,raw_body_bytes: bytes,provided_signature_hex: str,secret: Union[str, bytes],
) -> bool:"""验签。注意 raw_body_bytes 必须是请求体原始字节（未二次序列化）。"""if isinstance(secret, str):secret = secret.encode("utf-8")string_to_sign, _ = build_string_to_sign(http_method, uri_path, args, raw_body_bytes)expected = hmac.new(secret, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()# 常量时间比较，避免时序侧信道return hmac.compare_digest(provided_signature_hex, expected)

 

 

 

客户端请求示例（Python requests，可直接复制）

import os
import requests
from urllib.parse import urljoin, urlparse, parse_qs# 引入上方的 generate_signature
# from sign_utils import generate_signature

BASE_URL = os.getenv("API_BASE_URL", "https://api.example.com")
URI_PATH = "/open_api/query/template"
URL = urljoin(BASE_URL, URI_PATH)APP_ID = os.getenv("MY_APP_ID", "your_app_id_here")
SECRET = os.getenv("MY_SECRET", "your_secret_here")  # 建议使用环境变量配置

body = {"template_id": "your_template_id"}# 解析 query（若 URL 上还有 ?k=v，可从这里带入参与签名）
args = parse_qs(urlparse(URL).query)sign, body_bytes, string_to_sign = generate_signature(http_method="POST",uri_path=URI_PATH,args=args,body=body,secret=SECRET,
)headers = {"WX-SIGN": sign,"WX-APPID": APP_ID,"Content-Type": "application/json; charset=utf-8",# "WX-DEBUG": "true",  # 调试时可开启
}# 以原始字节发送，确保与签名一致
resp = requests.post(URL, data=body_bytes, headers=headers, timeout=10)
print("status:", resp.status_code)
print("resp:", resp.text)
# 调试输出
print("string_to_sign:", repr(string_to_sign))