{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Rest Graphql Debug

调试 REST/GraphQL API：状态码、认证、Schema、复现。

Skill 元数据


来源	可选 — 通过 `hermes skills install official/software-development/rest-graphql-debug` 安装
路径	`optional-skills/software-development/rest-graphql-debug`
版本	`1.2.0`
作者	eren-karakus0
许可证	MIT
标签	`api`, `rest`, `graphql`, `http`, `debugging`, `testing`, `curl`, `integration`
相关 skill	`systematic-debugging`、`test-driven-development`

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。

API 测试与调试

通过 Hermes 工具驱动 REST 和 GraphQL 诊断 —— terminal 用于 curl，execute_code 用于 Python requests，web_extract 用于查阅厂商文档。在猜测修复方案之前，先隔离出故障层。

适用场景

API 返回意外的状态码或响应体

认证（auth）失败（token 刷新后仍 401/403、OAuth、API key）

Postman 中正常但代码中失败

Webhook / 回调集成调试

构建或审查 API 集成测试

限流或分页问题

以下场景跳过本 skill（向上升级）：UI 渲染、DB 查询调优、DNS/防火墙基础设施。

核心原则

先隔离层，再修复。 200 OK 可能隐藏损坏的数据。500 可能掩盖一个字符的认证拼写错误。按顺序逐层排查，不要跳过任何步骤。

1. 连通性       → 能否访问到主机？
1.5 超时        → 连接慢还是读取慢？
2. TLS/SSL      → 证书是否有效且受信任？
3. 认证         → 凭据是否正确且未过期？
4. 请求格式     → payload 结构是否符合服务端预期？
5. 响应解析     → 代码是否能接受返回的内容？
6. 语义         → 数据含义是否符合我们的假设？

5 分钟快速上手

通过 terminal 调试 REST

通过 terminal 调试 GraphQL

GraphQL 注意事项： 即使查询失败，服务端通常也会返回 HTTP 200。无论状态码如何，始终检查 errors 字段：

通过 execute_code 使用 Python（requests）

分层调试流程

第 1 步 — 连通性

常见故障：DNS 无法解析、防火墙、需要 VPN、缺少代理。

第 1.5 步 — 超时

区分无法到达与到达但响应慢：

在 Python 中，始终传入元组超时 —— requests 没有默认值，会永久挂起：

诊断：time_connect 高说明是网络/防火墙问题；time_connect 低但 time_starttransfer 高说明是服务端响应慢。

第 2 步 — TLS/SSL

常见故障：证书过期、自签名证书、主机名不匹配、缺少 CA bundle。-k 仅用于临时调试，不得写入代码。

第 3 步 — 认证

检查清单：

Token 是否过期？（JWT 中的 exp 声明）

认证方案是否正确？Bearer vs Basic vs Token vs X-Api-Key

环境是否正确？将 Staging 的 key 用于 prod 是常见错误

API key 是放在请求头还是查询参数（?api_key=…）中？

第 4 步 — 请求格式

Content-Type 与请求体不匹配 —— 静默的 415/400：

常见问题：表单编码 vs JSON、缺少必填字段、HTTP 方法错误、查询参数未编码。

第 5 步 — 响应解析

调用 .json() 前始终检查 content-type：

常见故障：期望 JSON 却收到 HTML 错误页、响应体为空、字符集错误。

第 6 步 — 语义验证

解析成功 —— 但数据正确吗？

"status": "active" 的含义是否符合代码预期？

响应中的 ID 是否与请求的 ID 一致？

时间戳是否在预期时区？

分页是否返回了全部结果，还是只有第 1 页？

HTTP 状态码处理手册

401 Unauthorized — 凭据缺失或无效

Authorization 请求头是否实际存在？（用 curl -v 确认）

Token 是否正确且未过期？

认证方案是否正确？（Bearer vs Basic vs Token）

部分 API 使用查询参数（?api_key=…）而非请求头。

403 Forbidden — 已认证但无权限

Token 是否具有所需的 scope/权限？

资源是否属于其他账户？

IP 白名单是否将你拦截？

浏览器中的 CORS 问题？（检查 Access-Control-Allow-Origin）

404 Not Found — 资源不存在或 URL 错误

路径是否正确？（末尾斜杠、拼写错误、版本前缀）

资源 ID 是否存在？

API 版本是否正确（/v1/ vs /v2/）？

Base URL 是否正确（staging vs prod）？

409 Conflict — 状态冲突

资源是否已存在（重复创建）？

ETag / If-Match 是否过期？

是否有其他进程并发修改？

422 Unprocessable Entity — JSON 合法但数据无效

错误响应体通常会指出有问题的字段。检查：

字段类型（string vs int、日期格式）

必填 vs 可选

枚举值是否在允许范围内

429 Too Many Requests — 触发限流

检查 Retry-After 和 X-RateLimit-* 响应头。指数退避：

5xx — 服务端问题，通常不是你的错

500 — 服务端 bug。记录 correlation ID，向服务商提交工单。

502 — 上游服务宕机。退避后重试。

503 — 过载 / 维护中。查看状态页。

504 — 上游超时。减小 payload 或增大超时时间。

所有 5xx：带抖动的退避重试，持续出现时发出告警。

分页与幂等性

分页。 确认你获取了全部结果。查找 next_cursor、next_page、total_count。两种常见模式：

偏移量（?limit=100&offset=200）—— 简单，但数据变动时可能跳过条目。

游标（?cursor=abc123）—— 适用于实时或大数据集，推荐使用。

幂等性。 对于非幂等操作（POST），发送 Idempotency-Key: <uuid>，确保重试不会重复扣款或重复创建。支付和订单场景必须使用。

契约验证

在进入生产前捕获 schema 漂移：

在 API 升级后、接入新第三方时，或在 CI 冒烟测试中运行。

Correlation ID

始终记录服务商的请求 ID —— 这是联系厂商支持的最快途径：

厂商 bug 报告模板：

Endpoint:    POST /api/v1/orders
Request ID:  req_abc123xyz
Timestamp:   2026-03-17T14:30:00Z
Status:      500
Expected:    201 with order object
Actual:      500 {"error":"internal server error"}
Repro:       curl -X POST … (auth: <REDACTED>)

回归测试模板

将以下内容放入 tests/ 目录，通过 terminal('pytest tests/test_api_smoke.py -v') 运行：

安全

Token 处理

不要记录完整 token。脱敏处理：Bearer <REDACTED>。

不要在脚本中硬编码 token。从环境变量（os.environ["API_TOKEN"]）或 ~/.hermes/.env 读取。

如果 token 出现在日志、错误信息或 git 历史中，立即轮换。

安全日志记录

泄露检查清单

URL 中的凭据。 查询字符串中的 API key 会出现在服务器日志、浏览器历史、Referer 请求头中 —— 请使用请求头传递。

错误响应中的 PII。 404 on /users/123 不应暴露该用户是否存在（枚举攻击）。

生产环境中的堆栈跟踪。 500 响应不应泄露文件路径、框架版本。

内部主机名/IP。 错误响应体中出现 10.x.x.x、internal-api.corp.local。

Token 被回显。 部分 API 会在错误详情中包含认证 token。请验证其不会如此。

冗余的 Server / X-Powered-By。 技术栈信息泄露。记录以供安全审查。

Hermes 工具使用模式

terminal — 用于 curl、dig、openssl

execute_code — 用于多步骤 Python 流程

当调试跨越认证 → 请求 → 分页 → 验证多个环节时，使用 execute_code。变量在脚本内持久存在，结果打印到 stdout，不会在上下文中产生 token 污染：

web_extract — 用于查阅厂商 API 文档

直接拉取你正在调试的端点的规范，而不是靠猜测：

delegate_task — 用于完整的 CRUD 测试扫描

输出格式

报告调试结论时：

## Finding
Endpoint: POST /api/v1/users
Status:   422 Unprocessable Entity
Req ID:   req_abc123xyz

## Repro
curl -X POST https://api.example.com/api/v1/users \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <REDACTED>' \
  -d '{"name":"test"}'

## Root Cause
Missing required field `email`. Server validation rejects before processing.

## Fix
-d '{"name":"test","email":"test@example.com"}'

"Rest Graphql Debug — 调试 REST/GraphQL API：状态码、认证、Schema、复现"

Rest Graphql Debug#

Skill 元数据#

参考：完整 SKILL.md#

API 测试与调试#

适用场景#

核心原则#

5 分钟快速上手#

通过 terminal 调试 REST#

通过 terminal 调试 GraphQL#

通过 execute_code 使用 Python（requests）#

分层调试流程#

第 1 步 — 连通性#

第 1.5 步 — 超时#

第 2 步 — TLS/SSL#

第 3 步 — 认证#

第 4 步 — 请求格式#

第 5 步 — 响应解析#

第 6 步 — 语义验证#

HTTP 状态码处理手册#

401 Unauthorized — 凭据缺失或无效#

403 Forbidden — 已认证但无权限#

404 Not Found — 资源不存在或 URL 错误#

409 Conflict — 状态冲突#

422 Unprocessable Entity — JSON 合法但数据无效#

429 Too Many Requests — 触发限流#

5xx — 服务端问题，通常不是你的错#

分页与幂等性#

契约验证#

Correlation ID#

回归测试模板#

安全#

Token 处理#

安全日志记录#

泄露检查清单#

Hermes 工具使用模式#

terminal — 用于 curl、dig、openssl#

execute_code — 用于多步骤 Python 流程#

web_extract — 用于查阅厂商 API 文档#

delegate_task — 用于完整的 CRUD 测试扫描#

输出格式#

相关 Skill#

Rest Graphql Debug

Skill 元数据

参考：完整 SKILL.md

API 测试与调试

适用场景

核心原则

5 分钟快速上手

通过 terminal 调试 REST

通过 terminal 调试 GraphQL

通过 execute_code 使用 Python（requests）

分层调试流程

第 1 步 — 连通性

第 1.5 步 — 超时

第 2 步 — TLS/SSL

第 3 步 — 认证

第 4 步 — 请求格式

第 5 步 — 响应解析

第 6 步 — 语义验证

HTTP 状态码处理手册

401 Unauthorized — 凭据缺失或无效

403 Forbidden — 已认证但无权限

404 Not Found — 资源不存在或 URL 错误

409 Conflict — 状态冲突

422 Unprocessable Entity — JSON 合法但数据无效

429 Too Many Requests — 触发限流

5xx — 服务端问题，通常不是你的错

分页与幂等性

契约验证

Correlation ID

回归测试模板

安全

Token 处理

安全日志记录

泄露检查清单

Hermes 工具使用模式

terminal — 用于 curl、dig、openssl

execute_code — 用于多步骤 Python 流程

web_extract — 用于查阅厂商 API 文档

delegate_task — 用于完整的 CRUD 测试扫描

输出格式

相关 Skill