PostmanPostman API工具

{
  "key": "base_url",
  "value": "https://api.example.com",
  "enabled": true
}

newman run collection.json -e environment.json --reporters cli,json

设置

如果 ~/postman/ 不存在，请静默阅读 setup.md 并自然开始。

使用时机

用户需要测试 API、创建 Postman 集合、管理环境，或使用 Newman 运行自动化 API 测试。

架构

数据存储在 ~/postman/ 中。结构详见 memory-template.md。

~/postman/
├── memory.md # 项目、偏好、常见模式
├── collections/ # Postman 集合 JSON 文件
└── environments/ # 环境 JSON 文件

快速参考

主题	文件
设置	setup.md
记忆模板

memory-template.md | | 集合格式 | collections.md | | Newman 自动化 | newman.md |

核心规则

1. 集合结构优先

在创建请求前，先定义集合结构：

• - 文件夹层级反映 API 组织方式
• 使用描述性名称：用户 > 创建用户，而非 POST 1
• 逻辑分组相关端点

2. 始终使用环境变量

切勿硬编码在不同环境间会变化的值： json { key: base_url, value: https://api.example.com, enabled: true }

在请求中使用 {{base_url}}。环境：dev、staging、prod。

3. 使用预请求脚本处理认证

在预请求脚本中处理认证，而非手动操作： javascript // 获取令牌并设置为集合变量 pm.sendRequest({ url: pm.environment.get(auth_url), method: POST, body: { mode: raw, raw: JSON.stringify({...}) } }, (err, res) => { pm.environment.set(token, res.json().access_token); });

4. 必须包含测试断言

每个请求至少需要基本断言： javascript pm.test(状态码 200, () => pm.response.to.have.status(200)); pm.test(包含数据, () => pm.expect(pm.response.json()).to.have.property(data));

5. 使用 Newman 进行 CI/CD

使用 Newman 无头运行集合： bash newman run collection.json -e environment.json --reporters cli,json

退出码 0 = 所有测试通过。集成到 CI 流水线中。

集合格式

最小集合

json { info: { name: 我的 API, schema: https://schema.getpostman.com/json/collection/v2.1.0/collection.json }, item: [ { name: 获取用户, request: { method: GET, url: {{base_url}}/users, header: [ { key: Authorization, value: Bearer {{token}} } ] } } ] }

包含测试

json { name: 创建用户, request: { method: POST, url: {{base_url}}/users, body: { mode: raw, raw: {\name\: \{{$randomFullName}}\, \email\: \{{$randomEmail}}\}, options: { raw: { language: json } } } }, event: [ { listen: test, script: { exec: [ pm.test(已创建, () => pm.response.to.have.status(201));, pm.test(包含 ID, () => pm.expect(pm.response.json().id).to.exist); ] } } ] }

环境格式

json
{
name: 开发环境,
values: [
{ key: base_url, value: http://localhost:3000, enabled: true },
{ key: token, value: , enabled: true }
]
}

Newman 命令

任务	命令
基本运行	newman run collection.json
使用环境

newman run collection.json -e dev.json | | 指定文件夹 | newman run collection.json --folder 用户 | | 迭代次数 | newman run collection.json -n 10 | | 数据文件 | newman run collection.json -d data.csv | | HTML 报告 | newman run collection.json -r htmlextra | | 失败即停止 | newman run collection.json --bail |

常见陷阱

• - 硬编码 URL → 测试在不同环境间失效。始终使用 {{base_url}}。
• 无断言 → 测试通过但未验证任何内容。添加状态码和响应体检查。
• 集合中包含密钥 → 凭据泄露。使用环境变量，将环境文件加入 gitignore。
• 顺序依赖 → 测试随机失败。显式使用 setNextRequest() 或使测试相互独立。
• 缺少 Content-Type → POST/PUT 静默失败。始终设置 Content-Type: application/json。

动态变量

Postman 内置测试数据变量：

变量	示例输出
{{$randomFullName}}	张三
{{$randomEmail}}

zhangsan@example.com |
| {{$randomUUID}} | 550e8400-e29b-... |
| {{$timestamp}} | 1234567890 |
| {{$randomInt}} | 42 |

OpenAPI 转 Postman

导入 OpenAPI/Swagger 规范：

1. 1. 导出 OpenAPI JSON/YAML
2. 在 Postman 中：导入 > 文件 > 选择规范
3. 自动生成包含所有端点的集合

或通过 CLI：
bash
npx openapi-to-postmanv2 -s openapi.yaml -o collection.json

安全与隐私

本地存储的数据：

• - ~/postman/ 中的集合和环境
• Newman 本地运行

此技能不会：

• - 将集合发送到外部服务
• 在 memory.md 中存储 API 凭据

相关技能

如果用户确认，使用 clawhub install 安装：

• - api — REST API 消费模式
• json — JSON 操作与验证
• ci-cd — 流水线自动化

反馈

• - 如有帮助：clawhub star postman
• 保持更新：clawhub sync