2026-06-1614 分鐘閱讀

实用 API 除錯闭环：OpenAPI、Postman、HAR、jq 与 JSONPath

一篇更完整的 API 除錯教程，串起 OpenAPI 时序預覽、Postman 請求順序、HAR 瀑布流、jq/JSONPath 欄位提取和 HTTP 回應头檢查。

真實問題不是一个图能解决的

API 問題通常不只存在于一个文件里。OpenAPI 契約写的是一种行为，Postman 集合里可能是另一种請求順序，浏览器 HAR 又暴露了慢請求、重定向或第三方脚本。

所以这篇文章应该像一条除錯链路，而不是单纯介绍某个在线工具：先看契約，再看請求順序，再看浏览器网络瀑布流，最后用 jq 或 JSONPath 提取证据。

API 除錯闭环示意图 — 把契約、請求順序、HAR 时间线、回應欄位和 Header 檢查放在同一个除錯上下文里。

Demo 1：先从 OpenAPI 契約確認分支

很多线上問題不是 200 分支没写，而是 401、409、422、429 这些錯誤分支没人维护。先粘贴一个小的 OpenAPI 片段，比直接丢整个 spec 更容易定位。

預覽时重点看：接口是否有关键錯誤回應、錯誤码是否和前端处理一致、是否遗漏重试或幂等分支。

yaml

paths:
  /orders:
    post:
      summary: Create order
      responses:
        "201":
          description: Created
        "409":
          description: Duplicate payment intent
        "422":
          description: Invalid cart state

用 OpenAPI 預覽先確認契約里的成功和失敗分支。

Demo 2：用 Postman 集合檢查真實請求順序

Postman 集合更接近人工测试路径。契約可能是对的，但集合可能还在调用旧接口，或者漏了购物车校验、鉴权刷新这类中间步骤。

这个 demo 的目标不是画漂亮图，而是快速回答：請求順序是否符合真實產品流程。

json

{
  "item": [
    {"name": "Login", "request": {"method": "POST", "url": "https://api.example.com/auth/login"}},
    {"name": "Validate cart", "request": {"method": "POST", "url": "https://api.example.com/cart/validate"}},
    {"name": "Create order", "request": {"method": "POST", "url": "https://api.example.com/orders"}}
  ]
}

Postman 转时序图适合檢查集合是否已经过期。

Demo 3：HAR 里看慢請求和第三方影响

HAR 是浏览器视角的事实记录。它能告诉你：頁面慢到底是接口慢、静态资源慢、第三方脚本慢，还是某个 4xx/5xx 被前端吞掉了。

建议先截取最慢的几条 entry 做預覽，而不是把完整生产 HAR 丢进 Issue。

json

{
  "log": {
    "entries": [
      {"time": 92, "request": {"method": "GET", "url": "https://app.example.com/checkout"}, "response": {"status": 200}},
      {"time": 1280, "request": {"method": "POST", "url": "https://api.example.com/orders"}, "response": {"status": 201}},
      {"time": 430, "request": {"method": "GET", "url": "https://analytics.example.net/tag.js"}, "response": {"status": 200}}
    ]
  }
}

HAR 預覽应该让慢請求、状态码和 host 分布一眼可见。

Demo 4：用 jq 和 JSONPath 提取证据欄位

回應体很大时，不要让读者翻完整 payload。用 jq 或 JSONPath 抽出錯誤码、订单 ID、duration、retryCount 这些关键欄位。

jq 更适合转换 JSON，JSONPath 更像选择器，适合写进测试、监控和文件範例。

text

jq: .errors[].code
JSONPath: $.errors[*].code

{
  "errors": [
    {"code": "CART_EXPIRED", "message": "Cart was updated"},
    {"code": "PAYMENT_RETRY_REQUIRED", "message": "Retry with a new intent"}
  ]
}

把 jq 和 JSONPath 并排展示，比只放工具連結更像真正的除錯教程。

这条链路能发现哪些常见坑

Postman 集合仍然调用废弃接口；OpenAPI 只写了 201 和 500，却漏了前端每天遇到的 409；HAR 显示后端其实很快，真正慢的是第三方脚本；回應头缓存策略导致浏览器一直拿旧 schema。

这些具体錯誤案例，才是博客内容和普通工具頁拉开差距的地方。

發布除錯记录前的 checklist

至少保留一个契約片段、一个請求順序截图、一个 HAR 时间线截图、一个欄位提取範例。說明資料来自本地、测试環境还是生产環境。

截图用于快速阅读，源码用于重現。两者一起放进 PR、Issue 或博客里，可信度会高很多。