Postman 怎样用前置脚本生成请求签名

Postman 前置脚本可以在请求发送前执行 JavaScript，因此很适合处理每次都会变化的时间戳、随机数和请求签名。实际项目里，关键不在于“把一段 HMAC 代码贴进去”，而在于先和服务端约定完全一致的待签名字符串，再把生成结果写入请求头。

官方入口：https://www.postman.com/

官方脚本文档：https://learning.postman.com/docs/tests-and-scripts/write-scripts/pre-request-scripts/

下面用一个通用的 HTTP 请求演示：读取当前环境的 api_secret，将请求方法、路径、时间戳和 nonce 拼成规范字符串，使用 HMAC-SHA256 计算签名，最后写入 X-Timestamp、X-Nonce 和 X-Signature。示例不包含真实密钥，服务端仍需按相同规则复算。

一、先把签名所需的变量放进当前环境

打开目标 Collection 下的请求，在右上角选择一个当前环境。先在环境变量中新增 api_secret，只填写本地或私有值，不要把密钥写死在请求 URL、示例响应或共享脚本里。请求本身可以先保留一个普通地址，例如 {{base_url}}/v1/orders。

操作路径是：左侧 Collections → 打开请求 → 右上角 Environment 选择环境 → 环境编辑器新增 api_secret。如果还需要切换测试地址，可以同时准备 base_url；签名脚本读取的是当前选中的环境，而不是列表中任意一个环境。

二、进入 Pre-request 标签并固定签名格式

选中请求后点击 Scripts → Pre-request，脚本会在点击 Send 之前运行。先把签名格式写在纸面或接口文档中，例如下面的四行顺序：

• 第一行：HTTP 方法，统一转成大写。
• 第二行：解析变量后的请求路径和查询字符串。
• 第三行：当前毫秒时间戳。
• 第四行：本次请求的随机 nonce。

换行符、大小写、是否包含查询参数、时间戳单位都属于协议的一部分。只要客户端和服务端有一处不一致，签名就会失败，所以不要在脚本里临时改变顺序。

三、用前置脚本计算 HMAC 并更新请求头

在 Pre-request 编辑器粘贴下面的示例。它只使用环境变量读取密钥，使用当前请求对象读取方法和 URL，再通过 headers.upsert 写入或更新请求头。重复发送同一个请求时，旧签名会被替换，不会叠加多个同名字段。

// 读取当前环境中的密钥，避免把敏感值直接写入共享请求。
const secret = pm.environment.get("api_secret");
if (!secret) {
  throw new Error("当前环境缺少 api_secret");
}

// 让每次请求都有新的时间戳和 nonce，服务端可据此做时效与重放判断。
const timestamp = String(Date.now());
const nonce = pm.variables.replaceIn("{{$guid}}");

// 解析变量后的 URL，只把路径和查询串纳入签名，避免主机切换影响协议格式。
const resolvedUrl = pm.variables.replaceIn(pm.request.url.toString());
const parsedUrl = new URL(resolvedUrl);
const pathWithQuery = parsedUrl.pathname + parsedUrl.search;
const canonical = [
  pm.request.method.toUpperCase(),
  pathWithQuery,
  timestamp,
  nonce,
].join("\n");

// Postman Sandbox 提供 crypto-js，用约定的密钥计算十六进制 HMAC-SHA256。
const CryptoJS = require("crypto-js");
const signature = CryptoJS.HmacSHA256(canonical, secret)
  .toString(CryptoJS.enc.Hex);

// upsert 会更新同名字段，避免重复发送时残留上一轮签名。
pm.request.headers.upsert({ key: "X-Timestamp", value: timestamp });
pm.request.headers.upsert({ key: "X-Nonce", value: nonce });
pm.request.headers.upsert({ key: "X-Signature", value: signature });

// 只记录可用于排查的摘要，不在 Console 输出密钥或完整规范字符串。
console.log("signature ready", { timestamp, nonce, signatureLength: signature.length });

如果你的服务端要求 Base64 签名，把最后的编码方式改成协议约定的 Base64；不要只凭习惯把十六进制和 Base64 互换。若服务端签名的是完整 URL、请求体或经过排序的参数，也要同步调整 canonical，并明确空值、编码和换行规则。

四、发送前后怎样确认签名已经写入请求

保存脚本后点击 Send。回到请求的 Headers 面板，确认能看到三个由脚本生成的字段；再打开 Postman Console，检查 signature ready 日志和签名长度。这里核对的是“脚本有没有写入请求”，不是把签名当作服务端验签成功的证明。

服务端验签时还应检查时间窗口、nonce 是否重复、请求方法和路径是否完全一致。Postman 侧看到字段，只能说明前置脚本完成了本地组装；如果返回 401 或签名错误，优先把客户端和服务端各自参与签名的原始字符串打印成脱敏摘要，再逐项比较。

五、常见不生效情况

相关问题

密钥应该放在脚本还是环境变量里？

放在当前环境的私有值中更容易按环境切换，也能避免把敏感值随 Collection 共享。共享 Collection 前应清理示例值，并按团队权限管理真实密钥。

为什么只改了请求体，签名却没有变化？

因为示例的规范字符串没有包含请求体。若接口协议要求签名覆盖 Body，需要先确定序列化和编码规则，再把稳定的 Body 摘要加入规范字符串，不能直接把格式化前后的 JSON 当成同一个输入。

Postman Console 能证明服务端验签成功吗？

不能。Console 只能帮助确认前置脚本执行并写入请求；最终是否通过，还要看服务端按协议复算后的结果和时间窗口。

这套做法的核心是三点：把密钥留在环境变量中、把待签名字符串固定成双方都能复算的格式、用 upsert 更新而不是叠加请求头。先在一个接口上完成对照，再把稳定的前置脚本提升到文件夹或 Collection 层级复用。