Postman

Postman 是主流的 API 开发与测试平台，提供图形化界面发送 HTTP 请求、管理 Collection、编写断言脚本，支持团队协作与 CI/CD 集成（Newman）。

国内替代/增强版：Apifox（集 API 文档、Mock、测试于一体，中文友好）。

核心概念

概念	说明
Collection	请求集合，按业务模块组织
Environment	环境变量集合（dev / test / prod）
Variable	变量，支持 Global / Collection / Environment / Local 四个作用域
Pre-request Script	请求发送前执行的 JS 脚本
Tests	响应返回后执行的断言脚本
Mock Server	基于 Collection Example 自动生成的 Mock 接口
Newman	Postman 的 CLI 运行器，用于 CI/CD 集成

发送请求

基本请求

在地址栏选择 HTTP 方法，输入 URL，点击 Send：

GET    https://api.example.com/users
POST   https://api.example.com/users
PUT    https://api.example.com/users/1
DELETE https://api.example.com/users/1
PATCH  https://api.example.com/users/1

请求 Body

格式	适用场景
none	GET / DELETE（无 body）
form-data	文件上传、multipart 表单
x-www-form-urlencoded	传统表单提交
raw / JSON	REST API（最常用）
binary	直接上传文件字节流
GraphQL	GraphQL 查询

{
  "username": "alice",
  "email": "alice@example.com",
  "role": "admin"
}

请求头

Content-Type: application/json
Authorization: Bearer {{token}}
X-Request-ID: {{$guid}}

{{变量名}} 引用 Postman 变量，{{$guid}} 是内置随机 UUID 生成器。

认证（Authorization）

认证类型	使用场景
No Auth	公开接口
API Key	通过 Header 或 Query 传递 key
Bearer Token	JWT 认证，填入 token 值
Basic Auth	用户名 + 密码（Base64 编码）
OAuth 2.0	第三方授权，支持自动刷新 token

在 Collection 级别设置认证后，Collection 内所有请求自动继承，无需逐个配置。

环境变量与变量作用域

四级作用域（优先级从高到低）

Local > Environment > Collection > Global

作用域	生命周期	适用场景
Global	永久	所有集合共享的变量
Collection	永久	该集合专用的配置
Environment	永久	区分 dev / test / prod 的差异配置
Local	单次请求	脚本中临时计算的值

脚本中操作变量

// 设置
pm.environment.set("token", "eyJhbG...");
pm.collectionVariables.set("userId", "123");
 
// 读取
const token = pm.environment.get("token");
const baseUrl = pm.collectionVariables.get("baseUrl");

在 URL / Header / Body 中引用：

{{baseUrl}}/api/{{apiVersion}}/users/{{userId}}

Pre-request Script

在请求发送前执行，常用于动态生成签名、刷新 token：

const timestamp = Date.now().toString();
const secret = pm.environment.get("appSecret");
const sign = CryptoJS.HmacSHA256(timestamp, secret).toString();
 
pm.request.headers.add({ key: "X-Timestamp", value: timestamp });
pm.request.headers.add({ key: "X-Sign", value: sign });

Postman 内置 CryptoJS、moment、uuid 等常用库，无需额外安装。

Tests（响应断言）

// 状态码
pm.test("Status is 200", () => {
    pm.response.to.have.status(200);
});
 
// 响应时间
pm.test("Response time < 500ms", () => {
    pm.expect(pm.response.responseTime).to.be.below(500);
});
 
// Body 字段
pm.test("User has correct name", () => {
    const body = pm.response.json();
    pm.expect(body.data.username).to.eql("alice");
    pm.expect(body.code).to.eql(0);
});
 
// 从响应提取值存入环境变量（登录接口获取 token）
pm.environment.set("token", pm.response.json().data.token);

Collection Runner

批量运行 Collection 内所有请求，支持：

• 设置迭代次数（Iterations）
• 上传 CSV / JSON 数据文件，实现参数化测试
• 设置请求间隔延迟

username,password
alice,pass123
bob,pass456

Newman（CLI 集成 CI/CD）

Newman 是 Postman Collection 的命令行运行器：

# 安装
npm install -g newman
 
# 运行（先从 Postman 导出 collection.json 和 environment.json）
newman run collection.json -e environment.json
 
# 生成 HTML 报告
npm install -g newman-reporter-htmlextra
newman run collection.json -e environment.json -r htmlextra

GitHub Actions 示例：

- name: Run API Tests
  run: |
    npm install -g newman
    newman run postman/collection.json \
      -e postman/env-test.json \
      --bail

Mock Server

基于 Collection 自动创建 Mock 接口，供前端在后端未完成时调用：

1. 在 Collection 上右键 → Mock Collection
2. 为每个请求配置 Example Response（示例响应体和状态码）
3. 获得 Mock URL，前端直接调用

常用技巧

导入 cURL / OpenAPI

File → Import → 支持 cURL、OpenAPI (Swagger)、RAML、WSDL

将 curl 命令粘贴进 Postman，自动解析为可视化请求：

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"alice"}'

内置动态变量

{{$guid}}        随机 UUID
{{$timestamp}}   当前时间戳（秒）
{{$randomInt}}   随机整数
{{$randomName}}  随机姓名

相关链接

• Apifox — 集 API 文档、Mock、测试于一体，Postman 的国产增强替代
• Git — Collection 导出 JSON 后纳入版本控制，团队共享
• Swagger — 从 OpenAPI 规范直接导入 Postman Collection