📮

Postman

API DEVELOPMENT PLATFORM · 从入门到专家

📑 目录

认识 Postman — 不只是发请求的工具
macOS 安装 & 首次配置
请求构造 — 从简单 GET 到复杂 GraphQL
Collections — 组织、共享、文档化
环境变量 & 动态数据 — 告别硬编码
脚本与自动化 — Pre-request & Tests
Mock Server — 前后端并行开发
高级实战 — Monitors、Newman CLI、Interceptors

认识 Postman

Postman 是什么？

Postman 是全球最流行的 API 开发协作平台。它的核心定位不是"发请求的 GUI 工具"，而是覆盖 API 全生命周期的协作平台：

设计 → 用 OpenAPI/Swagger 定义 API 规范
测试 → 构造请求、编写自动化测试脚本、参数化测试
调试 → 查看完整的请求/响应细节（Headers、Cookies、TLS 证书链）
文档 → 自动生成 API 文档并发布为网页
Mock → 无需后端就提供模拟 API
监控 → 定时运行 Collection，监控 API 健康

核心概念速览

概念	说明
Request	单个 HTTP 请求（GET/POST/PUT/DELETE/PATCH/OPTIONS/HEAD）
Collection	一组请求的集合，按文件夹组织。是 Postman 的核心组织单元
Folder	Collection 内的分组，可以设置 Folder-level 的 Pre-request Script 和 Auth
Environment	键值对变量集。切换环境就切换了所有变量值（dev/staging/prod）
Variables	Postman 支持 5 层变量作用域：Global → Collection → Environment → Data → Local
Pre-request Script	请求发送前执行的 JavaScript（如生成签名、设置时间戳）
Tests Script	请求完成后执行的 JavaScript（如断言响应、提取数据给下一个请求）
Runner	批量运行 Collection 中所有或选中的请求
Flow	可视化编排多个 API 调用的流程控制（无需写代码）

macOS 安装 & 首次配置

安装方式

macOS — 3 种安装方式

# 方式1：官网下载 .dmg（推荐，功能最全）
# https://www.postman.com/downloads/
# 下载 macOS (Apple Silicon / Intel) 版本，拖到 Applications

# 方式2：Homebrew
brew install --cask postman

# 方式3：Postman CLI（纯命令行，用于 CI/CD）
curl -o- "https://dl-cli.pstmn.io/install/osx_arm64.sh" | sh
# 验证安装
postman --version

首次配置

① 创建工作区（Workspace）：启动后创建你的第一个 Workspace。Workspace 就像是"项目目录"，你可以把相关 Collections、Environments 都放里面。
② 关闭 SSL 验证（仅本地开发用）：Settings → General → SSL certificate verification → OFF。本地开发或自签证书环境可以关闭。生产环境建议保持开启。
③ 设置代理（如果公司有代理）：Settings → Proxy → 配置 HTTP/HTTPS Proxy。
④ 配置字体大小：Settings → General → Editor Font Size → 14（macOS 默认偏小）。

macOS 快捷键速查

超高频快捷键（macOS）

⌘ + Enter        发送当前请求
⌘ + S             保存请求
⌘ + /             添加注释（在 Script 编辑区）
⌘ + B             切换侧边栏
⌘ + \             切换底部 Console 面板
⌘ + Option + C    打开 Postman Console（调试神器）
⌘ + T             新建 Tab
⌘ + W             关闭当前 Tab
⌘ + Shift + F     全局搜索
⌘ + ,             打开设置

请求构造 — 从简单 GET 到复杂场景

Level 1：基础 GET/POST

实战：RESTful API 请求

# GET 请求 — 查询用户列表
GET https://jsonplaceholder.typicode.com/users
Headers: Accept: application/json

# POST 请求 — 创建新用户
POST https://jsonplaceholder.typicode.com/users
Headers:
  Content-Type: application/json
Body (raw JSON):
{
  "name": "Levi Zhang",
  "email": "levi@morningstar.club",
  "phone": "138-0000-0001"
}

# PUT 请求 — 全量更新用户
PUT https://jsonplaceholder.typicode.com/users/1
Body: { "name": "Levi Updated", ... }

# PATCH — 部分更新
PATCH https://jsonplaceholder.typicode.com/users/1
Body: { "email": "newemail@morningstar.club" }

# DELETE — 删除
DELETE https://jsonplaceholder.typicode.com/users/1

Level 2：Query Params 与 Path Variables

不同传参方式对比

# Query Params（在 URL ? 后面，适合过滤/分页/搜索）
GET https://api.example.com/users?page=2&limit=50&status=active
# Postman 操作：点击 Params tab，逐个添加 key-value

# Path Variables（在 URL 路径中，适合标识资源）
GET https://api.example.com/users/{{userId}}/orders/{{orderId}}
# userId 和 orderId 是路径变量，在 Params tab 的 Path Variables 区域设置

# Headers（元数据，适合认证/格式声明）
Authorization: Bearer {{accessToken}}
X-Request-ID: {{$guid}}
Accept-Language: zh-CN

Level 3：认证方式全解析

Postman 内置支持所有主流认证方式。在 Request 的 Authorization tab 中选择：

Type	适用场景	Postman 配置要点
No Auth	公开 API	默认
Bearer Token	JWT/OAuth2 Access Token	粘贴 Token 字符串即可
Basic Auth	简单用户名密码	填入 Username + Password，Postman 自动生成 Base64 编码的 Authorization Header
API Key	第三方 API（如 Stripe）	设置 Key 名（如 X-API-Key）和值，可选择加在 Header 或 Query Param
OAuth 2.0	授权码/客户端凭证/密码/隐式	Postman 自动打开浏览器完成授权流程，回调后自动填入 Token
Digest Auth	旧式企业系统	填入用户名密码，Postman 自动完成 challenge-response
Hawk	HMAC 签名认证	填入 ID、Key、Algorithm

Level 4：文件上传、表单、GraphQL

multipart/form-data 上传文件

# Body → form-data
Key: file        Type: File    Value: 选择本地文件（或拖拽）
Key: description Type: Text    Value: "用户头像"

# 同时，在 Headers 中不要手动设置 Content-Type
# Postman 会自动生成含 boundary 的正确 multipart header

GraphQL 查询

# Body → GraphQL
POST https://api.example.com/graphql

query GetUserWithOrders($userId: ID!) {
  user(id: $userId) {
    name
    email
    orders(limit: 10) {
      id
      total
      status
    }
  }
}

# GraphQL Variables（在下方单独区域填写）
{ "userId": "123" }

# Postman 的 GraphQL 模式支持：
#   - 自动补全 schema 字段
#   - 内联文档（Ctrl+Space 看字段描述）

Collections — 组织、共享、文档化

Collection 是你的 API 知识库

不要把你的请求散落在几十个 Tab 里。Collection 是 Postman 的核心组织单元，它让你：

• 分组：按业务模块用 Folder 组织（如 User、Order、Payment）
• 共享：导出为 JSON 文件分享给团队，或发布到 Postman Workspace
• 自动化：Collection Runner 批量运行所有请求
• 文档化：View Documentation 自动生成漂亮的 HTML API 文档

Collection 级别的配置

在 Collection 上右键 → Edit，可以设置：
Pre-request Script：Collection 里所有请求发送前都会执行（如自动刷新 token）
Tests：Collection 里所有请求完成后都会执行
Authorization：所有请求共享认证方式（如整个 Collection 都用 Bearer Token）
Variables：Collection 级别的变量（如 baseUrl）

Collection 变量示例 — 定义一次，到处使用

# Collection Variables 定义
baseUrl: https://api.morningstar.club
apiVersion: v1
defaultPageSize: 50

# 所有请求使用：
GET {{baseUrl}}/{{apiVersion}}/users?limit={{defaultPageSize}}

# 切换环境时，只需改变量值，不改任何请求

一键生成 API 文档

Collection → View Documentation → 自动生成带请求/响应示例、参数说明的完整文档。可以 Publish 为公开链接，发给前端团队或外部合作方。

💡 最佳实践

每个 Request 的描述字段认真填！它会出现在自动生成的文档里。写清楚：① 这个接口做什么 ② 必填参数 ③ 可能的错误码 ④ 调用频率限制。你的团队会感谢你。

环境变量 & 动态数据

5 层变量作用域

Postman 变量有严格的优先级（高→低）：Local > Data > Environment > Collection > Global。同名变量，外层永远被内层覆盖。

实战：构建 dev / stg / prod 三套环境

# 创建三个 Environment

# Dev Environment
baseUrl: http://localhost:3000
dbHost: localhost
logLevel: debug

# Staging Environment
baseUrl: https://stg-api.morningstar.club
dbHost: stg-db.internal
logLevel: info

# Production Environment
baseUrl: https://api.morningstar.club
dbHost: prod-db.internal
logLevel: error

# 后续切换环境只需右上角下拉选择，所有请求自动适配

动态变量（Dynamic Variables）

Postman 内置大量动态变量，用双花括号引用，每次执行自动生成随机值：

常用动态变量（无需定义，直接用）

{{$guid}}            UUID v4，如 611c2b56-823a-4f2a-b4d3-c7b4e4bc3a91
{{$timestamp}}       当前 Unix 时间戳（秒）
{{$isoTimestamp}}    ISO 8601 格式时间戳
{{$randomInt}}       0-1000 之间的随机整数
{{$randomAlphaNumeric}} 随机 16 位字母数字
{{$randomEmail}}     随机 email
{{$randomFirstName}} 随机英文名
{{$randomPhoneNumber}} 随机手机号

# 实战用法：避免测试数据冲突
POST {{baseUrl}}/users
Body: {
  "name": "测试用户-{{$randomAlphaNumeric}}",
  "email": "{{$randomEmail}}",
  "requestId": "{{$guid}}"
}

脚本与自动化 — Pre-request & Tests

脚本运行时机

Postman 在两个时机执行你的 JavaScript 脚本：
Pre-request Script：请求发送前 → 用于生成签名、刷新 Token、设置动态 Header
Tests Script：响应返回后 → 用于断言响应、提取数据、设置环境变量传给下一个请求

Pre-request Script 实战

实战1：自动刷新 Token（生产环境最常用的脚本）

// 检查 token 是否过期（存为变量 + 时间戳）
const tokenExpiry = pm.environment.get("tokenExpiry");
const now = Date.now();

if (!pm.environment.get("accessToken") || now > tokenExpiry) {
    // Token 过期，重新获取
    pm.sendRequest({
        url: pm.environment.get("authUrl"),
        method: "POST",
        header: { "Content-Type": "application/json" },
        body: {
            mode: "raw",
            raw: JSON.stringify({
                client_id: pm.environment.get("clientId"),
                client_secret: pm.environment.get("clientSecret"),
                grant_type: "client_credentials"
            })
        }
    }, (err, res) => {
        const body = res.json();
        pm.environment.set("accessToken", body.access_token);
        pm.environment.set("tokenExpiry", now + body.expires_in * 1000);
        console.log("Token refreshed: " + body.access_token.substring(0, 10) + "...");
    });
}

实战2：生成 HMAC 签名

// 在 Pre-request Script 中动态计算签名并设为 Header
const secret = pm.environment.get("apiSecret");
const timestamp = Date.now().toString();
const body = pm.request.body ? pm.request.body.raw : "";
const signature = CryptoJS.HmacSHA256(timestamp + body, secret).toString();

pm.request.headers.add({ key: "X-Signature", value: signature });
pm.request.headers.add({ key: "X-Timestamp", value: timestamp });

Tests Script 实战 — 断言与链式调用

完整测试脚本模板

// 1. 状态码断言
pm.test("Status code is 200", () => {
    pm.response.to.have.status(200);
});

// 2. 响应时间断言
pm.test("Response time < 500ms", () => {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// 3. JSON 结构断言
pm.test("Response has correct structure", () => {
    const json = pm.response.json();
    pm.expect(json).to.have.property("data");
    pm.expect(json.data).to.be.an("array");
    pm.expect(json.data.length).to.be.greaterThan(0);
});

// 4. 提取数据设置变量（链式调用）
pm.test("Extract first user ID for next request", () => {
    const json = pm.response.json();
    const firstUserId = json.data[0].id;
    pm.environment.set("createdUserId", firstUserId);
    console.log("Created user ID: " + firstUserId);
});

// 5. Header 断言
pm.test("Content-Type is JSON", () => {
    pm.response.to.have.header("Content-Type");
    pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");
});

// 6. JSON Schema 校验
const schema = {
    type: "object",
    required: ["id", "name", "email"],
    properties: {
        id: { type: "number" },
        name: { type: "string" },
        email: { type: "string", format: "email" }
    }
};
pm.test("Schema is valid", () => {
    pm.response.to.have.jsonSchema(schema);
});

💡 Postman Console — 调试神器

⌘ + Option + C 打开 Console。你的 console.log() 输出、完整的请求/响应 raw data、脚本错误信息全部在这里。脚本调试必开。

Mock Server — 前后端并行开发

什么场景需要 Mock？

后端 API 还没开发完，前端已经需要联调了。传统方案是自己写 JSON 文件，但 Postman Mock Server 可以：
• 根据 Collection 里的保存的 Example Response 自动生成 Mock API
• 支持路径参数、Query String、动态响应
• 生成一个公网可访问的 URL，前端直接调

创建 Mock Server（实战）

3 步创建一个 Mock API

# Step 1：在 Request 中 Save Response → Save as Example
GET {{baseUrl}}/users/123
Response Body (保存为 Example):
{
  "id": 123,
  "name": "Levi Zhang",
  "email": "levi@morningstar.club",
  "status": "active"
}

# Step 2：可以保存多个 Example，返回不同场景
#   Example "Success" → 200 + 正常用户数据
#   Example "Not Found" → 404 + 错误信息

# Step 3：Collection → ... → Mock Collection
#   勾选 "Save the mock server URL as an environment variable"
#   生成 URL: https://a1b2c3d4-e5f6.mock.pstmn.io

# 前端直接使用:
fetch("https://a1b2c3d4-e5f6.mock.pstmn.io/users/123")
  .then(r => r.json())  // 返回你定义的 Example

💡 Mock 进阶

可以用 Pre-request Script 在 Mock 请求到达时动态生成响应（如返回随机用户数据），而不是返回固定的 Example。在 Mock 的 Collection 中编写 Script，根据请求参数动态构建响应。

高级实战 — Monitors、Newman CLI、Interceptors

Monitor — 定时监控你的 API

Postman Monitor 在云端定时运行你的 Collection，监控 API 可用性和正确性。相当于云端版 Collection Runner。

设置 Monitor

# Collection → Monitors → Create a Monitor
Name: Production API Health Check
Schedule: Every 5 minutes
Region: Asia Pacific
Retry: Retry once if failed
Notifications: Email on failure

# Monitor Dashboard 会显示运行历史、成功率、平均响应时间

Newman — 命令行运行 Collection（CI/CD 集成）

Newman 是 Postman 的 CLI 工具，让你在终端/CI/CD Pipeline 中运行 Collection。

macOS 安装 & 使用 Newman

# 安装
npm install -g newman

# 导出 Collection + Environment
# Postman → Collection → Export → v2.1
# Postman → Environment → Export

# 运行（基础）
newman run MyAPI.postman_collection.json \
  --environment Production.postman_environment.json

# 运行（带异步刷新 Token 支持）
newman run MyAPI.postman_collection.json \
  --environment Production.postman_environment.json \
  --iteration-count 3 \
  --delay-request 200 \
  --reporters cli,htmlextra \
  --reporter-htmlextra-export ./reports/api-test-report.html

# Jenkins / GitHub Actions 集成示例
newman run collection.json -e env.json --reporters cli,junit \
  --reporter-junit-export results.xml
# CI 通过 results.xml 的测试结果判断 pipeline 成功/失败

Interceptors — 捕获浏览器流量

Postman Interceptor 是一个 Chrome 扩展，连接浏览器和 Postman Desktop，让你：
• 捕获浏览器发出的所有 HTTP 请求（包括 Cookie、Auth Header）
• 把真实浏览器的 Cookies 同步到 Postman（解决复杂的认证 Cookie 问题）
• 前端调试时，直接重放浏览器里看到的某个请求

Flow Runner — 可视化流程编排

Postman Flows 让你用拖拽方式编排 API 调用流程，不需要写代码。适合：
• 快速搭建 API 调用链（不需要写在 Tests 里做链式调用）
• 展示给非技术同事看的 API 流程
• 复杂条件分支（if-else、循环）的可视化

学习路径

📚 从小白到专家的推荐路线

Week 1：安装 → 发第一个 GET/POST → 理解 Headers/Body/Params → 用 jsonplaceholder 练习所有 HTTP 方法
Week 2：创建 Collection 组织请求 → 创建 dev/stg/prod Environment → 学会变量引用 → 学会不同认证方式
Week 3：写 Tests Script 做自动化断言 → 写 Pre-request Script 处理 Token → Console 调试
Week 4：Collection Runner 批量运行 → 导出 Collection + Newman CLI → Mock Server
Advanced：CI/CD 集成 → Flow Runner → API 文档发布 → Monitor 搭建线上监控

HTTPRESTGraphQL CollectionEnvironmentOAuth2 NewmanMock ServerMonitor ScriptsCI/CD

← 返回技能树