Api Toolkit

SKILL.md

---
slug: api-toolkit
name: api-toolkit
version: "1.0.0"
displayName: API工具箱(专业版)
summary: 企业级API测试调试全套件，含批量回归、Mock服务、性能压测、契约校验与团队协作。
license: Proprietary
edition: pro
description: |-
  API工具箱专业版是面向研发团队的全功能API测试调试套件。在免费版的请求模板、认证范式、错误诊断基础上，解锁批量回归测试集、本地Mock服务器、性能压测、OpenAPI契约校验、按服务细分的完整错误码字典、团队协作空间六大高级能力，覆盖从联调到上线再到持续回归的完整生命周期。Use when 需要代码生成、编程辅助、调试测试、开发部署时使用。不适用于无明确技术栈的模糊需求。
tags:
- API测试
- 接口调试
- 回归测试
- 性能压测
- 契约校验
tools:
  - - read
- exec
# API工具箱（专业版）
---
# API工具箱(专业版)

## 核心能力

### 功能1：回归测试集（批量测试）
**解决痛点**：接口改动后，靠人工回归既慢又容易漏，团队成员各测各的没有沉淀。

**专业版能力**：
- YAML声明式定义测试集，支持setup/teardown与变量提取
- 依赖编排：步骤间变量传递（`（根据实际场景填充）`），自动拓扑排序
- 断言链：状态码、响应体字段、响应时间、Header多维度断言
- 数据驱动：CSV/JSON数据源，同一测试用多组数据跑
- 失败重试：网络层错误自动重试，业务错误不重试
- 报告生成：HTML/JSON/JUnit XML三种格式，可入CI

**断言DSL示例**：

```yaml
assert:
  - status == 200
  - response.body.code == 0
  - response.body.data | length > 0
  - response.body.data[0].id ~= /^\d+$/
  - headers['Content-Type'] contains 'application/json'
  - time_total < 500  # 响应时间小于500ms
```

**输入**: 用户提供功能1：回归测试集（批量测试）所需的指令和必要参数。
### 功能2：本地Mock服务器
**解决痛点**：前端等后端、后端等前端，串行开发慢；第三方API联调期不稳定。

**专业版能力**：
- 基于OpenAPI Spec自动生成Mock响应，无需手写
- 状态码注入：`?mock_status=500` 模拟错误响应
- 延迟注入：`?mock_delay=2000` 模拟慢接口
- 场景切换：`?mock_scenario=empty` / `?mock_scenario=error`
- 录制回放：录制真实请求，离线回放用于调试
- 状态持久化：Mock数据变更可保存，重启不丢失

```bash
api-toolkit mock start --spec ./openapi.yaml --scenario edge-case

api-toolkit mock record --target https://api.example.com --port 8080

api-toolkit mock replay --recording ./recordings/2026-07.json
```

**处理**: 按照skill规范执行功能2：本地Mock服务器操作,遵循单一意图原则。
### 功能3：性能压测
**解决痛点**：上线前才知道接口扛不住，或压测工具太重不会用。

**专业版能力**：
- 阶梯并发：10→50→100→200逐步加压，定位拐点
- 恒定并发：固定QPS持续压测，验证稳定性
- 峰值压测：突发流量模拟，验证限流与降级
- 多维指标：QPS曲线、P50/P95/P99延迟、错误率热力图
- 资源监控：可选采集目标服务CPU/内存（需agent配合）
- 报告导出：HTML交互式报告，含瓶颈分析与优化建议

**典型压测报告结构**：

```text
Load Test Report - 2026-07-18
================================
Target: https://api.example.com/v1/users
Duration: 300s | Total Requests: 150,000

Concurrency | QPS  | P95(ms) | P99(ms) | Error%
10          | 95   | 85      | 120     | 0.0%
50          | 420  | 180     | 320     | 0.1%
100         | 780  | 450     | 820     | 1.2%  ← 拐点
200         | 920  | 1800    | 3500    | 8.5%  ← 降级触发

Bottleneck: P95在并发100时突破500ms阈值
Suggestion: 检查DB连接池配置，建议限流阈值设为800 QPS
```

### 功能4：OpenAPI契约校验
**解决痛点**：接口实现悄悄改了字段类型，前端没被告知，上线后炸。

**专业版能力**：
- Spec与实际响应结构差异比对
- 字段类型、必填性、枚举值、格式（date/email/uuid）校验
- 遗漏字段与多余字段检测
- CI卡点：契约不通过则流水线失败
- 历史漂移追踪：字段变更时间线

```bash
api-toolkit contract-check \
  --spec ./openapi.yaml \
  --endpoint /v1/users \
  --method GET \
  --response ./sample-response.json

api-toolkit contract-check --spec ./openapi.yaml --ci-mode
```

**输出示例**：

> 详细代码示例已移至 `references/detail.md`

**处理**: 按照skill规范执行功能4：OpenAPI契约校验操作,遵循单一意图原则。
### 错误恢复步骤
**解决痛点**：第三方API的业务错误码散落在文档各处，排查时翻半天。

**专业版能力**：80+服务、1000+业务错误码的结构化字典，支持按服务、按错误类型检索。

```bash
api-toolkit error-dict --service stripe --search "card_declined"

Stripe Error: card_declined
HTTP Status: 402
Meaning: 顾客的银行卡被拒
Common Causes: 余额不足、卡过期、风控触发
Recovery: 提示用户更换支付方式，或使用Idempotency-Key执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
Doc: 搜索 "Stripe card_declined codes"
```

**输出**: 返回错误处理的执行结果,包含操作状态和输出数据。

- 执行`错误处理`操作,处理输入数据并返回结果
- 验证执行结果,确认输出符合预期格式
- 异常时参考错误处理章节进行恢复
- 关键参数: `错误处理` 选项

### 功能6：团队协作空间
**解决痛点**：测试集散落各人电脑，接口改动没人通知，回归结果无法对比。

**专业版能力**：
- 测试集云端仓库：Git版本化，支持分支与PR评审
- 结果diff：两次回归结果对比，标记新增失败项
- 变更追踪：接口Spec变更自动通知相关测试集owner
- 权限管理：读/写/管理员三角色
- Webhook：测试失败自动通知Slack/钉钉/飞书

- 参考`功能6：团队协作空间`相关配置参数进行设置
### 能力覆盖范围

本skill还覆盖以下能力场景: 企业级、测试调试全套件、含批量回归、契约校验与团队协、工具箱专业版是面、向研发团队的全功、测试调试套件、在免费版的请求模、认证范式、错误诊断基础上、解锁批量回归测试、按服务细分的完整、错误码字典、团队协作空间六大、高级能力、覆盖从联调到上线、再到持续回归的完、整生命周期、需要代码生成、编程辅助、调试测试、开发部署时使用、不适用于无明确技、术栈的模糊需求。这些能力在上述核心功能中均有对应处理逻辑。
## 适用场景

### 场景一：前后端并行开发（前端+后端角色）
**痛点**：前端等后端接口才能开工，串行开发周期长。

**专业版方案**：
1. 后端先输出OpenAPI Spec（哪怕只有字段定义）
2. 前端用 `api-toolkit mock start --spec ./openapi.yaml` 启动Mock
3. 前端基于Mock开发，`?mock_scenario=empty` 测试空数据，`?mock_scenario=error` 测试错误态
4. 后端接口ready后，前端切换BaseURL，用 `api-toolkit contract-check` 验证实现是否符合Spec
5. 契约不一致项以issue形式反馈给后端

**效果**：前后端并行开发，整体交付周期缩短约30%。

### 场景二：上线前性能验收（SRE/后端角色）
**痛点**：上线后才发现接口扛不住大促流量，回滚损失大。

**专业版方案**：
1. 用 `api-toolkit load-test` 跑阶梯压测，定位QPS拐点
2. 查看P95/P99延迟，确认是否满足SLA（如P95<500ms）
3. 检查错误率热力图，识别哪个并发档开始降级
4. 根据报告建议设置限流阈值（如800 QPS）与降级策略
5. 压测报告作为上线评审材料归档

**效果**：上线前量化性能边界，避免线上事故。

### 场景三：API契约持续校验（测试工程师角色）
**痛点**：后端悄悄改了字段类型，前端没被告知，集成时炸。

**专业版方案**：
1. OpenAPI Spec作为"契约"纳入Git版本控制
2. CI流水线加入 `api-toolkit contract-check --ci-mode`
3. 后端PR触发流水线，契约校验不通过则PR无法合并
4. 字段变更需同时更新Spec，Spec变更触发前端测试集重跑
5. 历史漂移追踪：字段变更时间线可查

**效果**：契约漂移从"上线后才发现"变为"合并前被拦截"。

### 场景四：第三方API联调期解耦（全栈角色）
**痛点**：对接第三方API，对方环境不稳定，自己的开发被阻塞。

**专业版方案**：
1. 用 `api-toolkit mock record --target <第三方API>` 录制一次正常响应
2. 离线开发时用 `api-toolkit mock replay --recording ./recordings/详情见说明.json`
3. 第三方API升级时，对比录制与实际响应差异
4. 错误码字典查第三方业务错误码，写好降级逻辑
5. 上线前用 `api-toolkit load-test` 压测第三方API配额

**效果**：第三方不稳定不再阻塞本地开发。

### 场景五：SaaS多租户接口测试（测试工程师角色）
**痛点**：多租户系统接口容易串数据，回归测试要覆盖多租户隔离。

**专业版方案**：
1. 测试集中用数据驱动注入多组租户凭证（CSV）
2. 每个租户跑同一套接口，断言响应中不含其他租户数据
3. 用 `api-toolkit contract-check` 校验不同租户的响应结构一致
4. 压测时模拟多租户并发，验证资源隔离
5. 错误码字典覆盖租户相关的业务错误（如 `tenant_quota_exceeded`）

**效果**：多租户隔离从手工抽查变为自动化回归。

## 使用流程

### 基础搭建（<60秒）：继承免费版能力
专业版完全兼容免费版的所有模板与范式。首次使用时，直接对Agent说：

Agent会按免费版的模板规则输出curl命令，并额外提示：是否要把这个请求加入回归测试集？

> 详细内容已移至 `references/detail.md` - ### 标准搭建（<120秒）：跑优秀个回归测试集
### 完整搭建（<300秒）：启用Mock与压测
启动Mock服务器（基于OpenAPI Spec）：

```bash
api-toolkit mock start --spec ./openapi.yaml --port 8080
```

运行阶梯压测：

```bash
api-toolkit load-test \
  --target https://api.example.com/v1/users \
  --duration 300s \
  --concurrency 10,50,100,200 \
  --rampup 30s \
  --report ./reports/load-$(date +%Y%m%d).html
```

### 命令参数说明

1. `--concurrency`: 命令参数,用于指定操作选项
2. `--endpoint`: 命令参数,用于指定操作选项
3. `--report`: 命令参数,用于指定操作选项
4. `--method`: 命令参数,用于指定操作选项
5. `-Key执行ping命令测试网络连通性`: 命令参数,用于指定操作选项

### 命令参数说明

- `--duration`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `-case`: 命令参数,用于指定操作选项
- `--search`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项

### 命令参数说明

- `-Key执行ping命令测试网络连通性`: 命令参数,用于指定操作选项
- `-response`: 命令参数,用于指定操作选项
- `-dict`: 命令参数,用于指定操作选项
- `--rampup`: 命令参数,用于指定操作选项
- `--response`: 命令参数,用于指定操作选项

### 命令参数说明

- `--service`: 命令参数,用于指定操作选项
- `--on-failure`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `--schedule`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项

### 命令参数说明

- `-Type`: 命令参数,用于指定操作选项
- `-Key执行ping命令测试网络连通性`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项

### 命令参数说明

- `-X`: 命令参数,用于指定操作选项
- `-Key执行ping命令测试网络连通性`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项

### 命令参数说明

- `-X`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `-Key执行ping命令测试网络连通性`: 命令参数,用于指定操作选项

### 命令参数说明

- `-Type`: 命令参数,用于指定操作选项
- `-Key执行ping命令测试网络连通性`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项

### 命令参数说明

- `-X`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `-Key执行ping命令测试网络连通性`: 命令参数,用于指定操作选项

## 输入格式

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| content | string | 是 | 相关说明 |
| content | string | 否 | 相关说明, 默认: 默认值 |
| content | string | 否 | 相关说明, 可选值: json/text/markdown |
| style | string | 否 | 输出风格, 参考 `references/style.md` |

## 输出格式

```json
{
  "success": true,
  "data": {
    result: "相关说明",
    result: "相关说明",
    result: "相关说明",
    "metadata": {
      "template_used": "reviewer",
      "word_count": 0,
      "style": "专业"
    }
  },
  "error": null
}
```

输出模板参考: `assets/output.json`

## 错误处理

| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| 输入content为空 | 用户未提供必要信息 | 提示用户提供content, 并给出示例格式 |
| 输入内容过长(>5000字) | 超出单次处理能力 | 建议分段处理, 每段不超过2000字 |
| 风格参数不识别 | 传入不支持的风格 | 列出支持的风格选项, 使用默认风格 |
| 生成内容不达标 | 质量校验未通过 | 自动执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令1次, 仍不达标则标注问题返回 |
| 其他异常 | 内部处理异常 | 检查输入后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令 |

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux
- **Node.js**: 18+（用于CLI工具）
- **Python**: 3.8+（用于压测引擎与数据驱动）

### 依赖说明
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent平台内置LLM提供（专业版路由GPT-4o） |
| Node.js 18+ | 运行时 | 必需 | 从nodejs.org安装 |
| curl | 工具 | 推荐 | 系统自带或从curl.se安装 |
| jq | 工具 | 可选 | 从jqlang.github.io安装 |
| OpenAPI Spec | 文件 | Mock/契约校验必需 | 由团队维护 |
| Git | 工具 | 协作空间必需 | 系统自带或从git-scm.com安装 |

### API Key 配置
- 协作空间需配置团队Token：`api-toolkit collab login`
- 压测第三方API需配置目标服务Token（存环境变量）
- 所有Token通过环境变量配置，禁止硬编码
- 建议将Token存储在 `~/.api-toolkit/credentials/` 目录（已gitignore）

### 可用性分类
- **分类**: MD+EXEC（）
- **说明**: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行API测试与质量保障任务

## 案例展示

### 与CI/CD集成

> 详细代码示例已移至 `references/detail.md`

### 与开发工具集成
```json
{
  "editor.apiToolkit": {
    "enabled": true,
    "mockOnSave": true,
    "contractCheckOnSave": true,
    "defaultAssertTimeout": 500
  }
}
```

### 与团队协作平台集成
```text
1. 回归测试失败 → 自动通知Slack/钉钉/飞书对应频道
2. 契约校验不通过 → 自动在PR评论差异详情
3. 压测报告生成 → 自动上传到Confluence/Notion
4. 错误码字典更新 → 自动推送changelog到团队群
```

### 与监控告警集成
```bash
api-toolkit test run ./tests/smoke.yaml --schedule "*/5 * * * *" \
  --on-failure "curl -X POST $ALERT_WEBHOOK -d 'API冒烟测试失败'"
```

## 常见问题

### Q1：免费版与专业版有什么区别？
免费版聚焦"个人联调能跑通"，提供请求模板、认证范式、错误诊断与服务索引。专业版聚焦"团队级API质量基础设施"，新增六大高级功能：回归测试集、Mock服务器、性能压测、契约校验、完整错误码字典、团队协作空间。此外提供多角色场景指南、性能优化策略、多平台集成示例与版本迁移指南。

### Q2：回归测试集支持哪些断言？
支持状态码、响应体字段（含JSONPath）、Header、响应时间四类断言。DSL支持相等（`==`）、包含（`contains`）、正则（`~=`）、长度（`| length`）、数值比较（`<` `>`）等操作符。复杂断言可用JS表达式。

### Q3：Mock服务器能模拟任意API吗？
可以，前提是有OpenAPI Spec。Mock基于Spec自动生成符合Schema的响应。对于无Spec的API，可用record模式录制真实响应回放。Mock支持状态码注入、延迟注入、场景切换。

### Q4：性能压测会压垮生产环境吗？
有风险，建议在预发环境压测。专业版提供熔断保护：错误率超阈值（默认5%）自动停止。压测前应评估目标API的配额与限流策略，避免触发风控。生产压测建议在低峰期，并提前报备。

### Q5：契约校验和单元测试有什么区别？
单元测试验证"代码逻辑是否正确"，契约校验验证"接口实现是否符合Spec约定"。契约校验关注的是接口契约的稳定性，防止后端悄悄改字段类型或删除必填字段而前端不知情。两者互补，不能替代。

### Q6：错误码字典怎么保证准确性？
字典由社区贡献+官方文档同步双通道维护。每个错误码标注来源（官方文档/社区验证）、最后核实时间。用户发现释义不准可通过协作空间提交修正。专业版每月同步一次官方文档更新。

### Q7：团队协作空间支持多少成员？
专业版默认支持20人团队。更大团队可联系销售升级企业版。协作空间支持读/写/管理员三角色，测试集用Git版本化，支持分支与PR评审。

### Q8：回归测试集能复用免费版的curl命令吗？
可以。用 `api-toolkit test import --from-curl ./cmds.sh` 可批量导入curl命令为测试集steps。导入后需补充断言。专业版也支持从Postman Collection、Insomnia导出文件导入。

### Q9：Mock录制会泄露敏感数据吗？
录制数据默认存本地，可配置脱敏规则（如对 `Authorization` 头、`email` 字段脱敏）。录制数据不应提交到Git，建议加入 `.gitignore`。协作空间上传前会自动扫描敏感字段并提示。

### Q10：压测报告包含哪些指标？
包含QPS曲线、P50/P95/P99延迟、错误率热力图、并发档位对比、瓶颈分析、优化建议。报告为HTML交互式格式，可缩放查看曲线细节，可导出PDF归档。

### Q11：能在CI/CD中完全自动化吗？
可以。专业版CLI支持CI模式（退出码非0即失败），提供GitHub Actions/GitLab CI/Jenkins的集成示例。典型流水线：PR触发契约校验→合并触发回归测试→定期触发压测。

### Q12：专业版支持私有化部署吗？
支持。团队协作空间可私有化部署到企业内网，不依赖公网。Mock服务器与压测工具本身就在本地运行。错误码字典可离线包形式分发。联系销售获取私有化部署包。

## 已知限制

- 需要API Key，无Key环境无法使用
- 本地运行，不支持多设备同步