设置

如果 ~/postman/ 目录不存在，请静默读取 setup.md 并自然启动。

适用场景

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

架构

所有数据存放在 ~/postman/ 目录中。结构定义详见 memory-template.md。

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

速查表

核心规则

1. 优先定义集合结构

在创建请求前，先明确集合的结构：

• 文件夹层级应反映 API 的组织逻辑
• 使用描述性名称，例如 Users > Create User，而非 POST 1
• 将相关端点按逻辑分组

2. 始终使用环境变量

禁止硬编码随环境变化的值：

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

在请求中统一使用 {{base_url}}。标准环境包括：dev、staging、prod。

3. 认证逻辑置于 Pre-request Script

通过 Pre-request Script 处理认证，避免手动操作：

// 获取 token 并设置到当前 collection
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. 每个请求必须包含测试断言

每个请求至少需包含基础断言：

pm.test("Status 200", () => pm.response.to.have.status(200));
pm.test("Has data", () => pm.expect(pm.response.json()).to.have.property("data"));

5. 使用 Newman 支持 CI/CD

通过 Newman 无界面运行集合：

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

退出码为 0 表示全部测试通过，可直接集成至 CI 流水线。

集合格式

最小化集合示例

{
  "info": {
    "name": "My API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Get Users",
      "request": {
        "method": "GET",
        "url": "{{base_url}}/users",
        "header": [
          { "key": "Authorization", "value": "Bearer {{token}}" }
        ]
      }
    }
  ]
}

含测试脚本的请求示例

{
  "name": "Create User",
  "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('Created', () => pm.response.to.have.status(201));",
          "pm.test('Has ID', () => pm.expect(pm.response.json().id).to.exist);"
        ]
      }
    }
  ]
}

环境格式

{
  "name": "Development",
  "values": [
    { "key": "base_url", "value": "http://localhost:3000", "enabled": true },
    { "key": "token", "value": "", "enabled": true }
  ]
}

Newman 命令速查

常见陷阱

• 硬编码 URL → 测试在不同环境间失效。务必使用 {{base_url}}。
• 缺失断言 → 测试“通过”但未做任何验证。请至少添加状态码 + 响应体检查。
• 在集合中存储密钥 → 导致凭据泄露。应仅通过环境变量管理，并确保 environments/ 目录被 .gitignore 排除。
• 隐式顺序依赖 → 测试随机失败。请显式使用 setNextRequest()，或设计为完全独立的测试用例。
• 遗漏 Content-Type → POST/PUT 请求可能静默失败。务必显式设置 Content-Type: application/json。

动态变量

Postman 内置测试数据变量：

OpenAPI 转 Postman

导入 OpenAPI/Swagger 规范：

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

或通过 CLI 执行：

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