API开发调试

技能简介

本技能覆盖HTTP API的完整生命周期，包括接口脚手架搭建、自动化测试、文档生成与线上问题排查。支持REST与GraphQL两种协议，提供命令行工具链实现快速验证与持续集成。

业务背景

API开发调试技能帮助团队高效完成接口全生命周期管理。从快速搭建接口脚手架、编写自动化测试脚本，到生成标准化文档与线上故障排查，覆盖REST与GraphQL双协议。通过命令行工具链实现本地快速验证与CI/CD流水线集成，降低联调成本，保障接口质量与交付效率。

落地案例：某前端团队需对接后端新用户模块，使用curl快速验证GET/POST接口响应格式；随后用Python脚本批量测试边界场景，自动生成测试报告。发现某接口时延异常后，通过分析响应头定位到CDN缓存策略问题。最终输出OpenAPI文档供协作方调用，并用Mock服务隔离未就绪的支付接口，确保迭代进度不受阻塞。

能做什么

• 用curl执行GET/POST/PUT/PATCH/DELETE请求并解析响应
• 编写Bash或Python脚本进行批量接口测试
• 生成并校验OpenAPI/Swagger规范文档
• 搭建Mock服务隔离外部依赖
• 分析HTTP时延、状态码与响应头定位故障
• 执行简单的负载压测

使用说明

前置条件：系统需安装curl、Node.js或Python 3任一环境。

基础请求示例：

# 带认证的GET请求
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/users | jq .

# POST JSON数据
curl -s -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com"}' | jq .

调试技巧：

# 查看完整请求响应链
curl -v https://api.example.com/health 2>&1

# 仅输出响应头
curl -sI https://api.example.com/health

# 请求耗时分解
curl -s -o /dev/null -w "DNS:%{time_namelookup}s\nConnect:%{time_connect}s\nTLS:%{time_appconnect}s\nTTFB:%{time_starttransfer}s\nTotal:%{time_total}s" \
  https://api.example.com/health

自动化测试：将上述Bash或Python测试脚本保存为可执行文件，通过./api-test.sh http://localhost:3000运行，返回非零退出码表示存在失败用例。

输入与输出

见下方输入与输出表格。

风险提示

• 生产环境调试时避免使用-v参数暴露敏感Token
• Mock服务未验证真实下游行为，上线前需回归测试
• 脚本中的硬编码凭证应迁移至环境变量或密钥管理系统
• 高频curl请求可能触发服务端限流或IP封禁

来源信息

原始链接：https://github.com/openclaw/skills/tree/main/skills/gitgoodordietrying/api-dev/SKILL.md
来源类型：GitHub仓库