跳轉到主要內容

用 OpenAPI 規範生成支付接口客戶端:類型、SDK、Postman 與契約測試

如何用 OpenAPI 規範生成支付接口客戶端:TypeScript 類型、用 OpenAPI Generator 生成 SDK、導入 Postman,以及契約測試。

發佈於 約 3 分鐘閲讀

手繪插畫:一個 openapi.json 文件送進生成器,輸出 TypeScript、Python 和一個 Postman 集合,旁邊一個人雙手插兜
本文目錄
  1. 去哪裏拿 OpenAPI 規範
  2. 規範裏有什麼
  3. 方式一:只生成 TypeScript 類型
  4. 方式二:生成完整的客戶端 SDK
  5. 方式三:導入 Postman
  6. 契約測試:讓客戶端與接口保持同步
  7. 生成的客戶端不會替你做的事
  8. 總結

OpenAPI 規範是一份機器可讀的接口描述:每個端點、參數、請求體、響應和錯誤都在裏面。有了它,你可以生成接口客戶端——用你自己的語言寫好的類型化模型和方法——而不用手寫 HTTP 調用、再從文檔裏抄字段名。對支付接口來説這比平時更重要:字段拼錯、枚舉值寫錯,就是一筆失敗的支付,而不只是一個筆誤。

這篇文章介紹如何從 KukoPay 的 OpenAPI 規範生成客戶端:去哪裏拿、裏面有什麼、如何生成 TypeScript 類型或完整 SDK、如何在 Postman 裏使用,以及如何用契約測試讓生成的客戶端保持準確。

去哪裏拿 OpenAPI 規範

商戶接口完整的 OpenAPI 3.1 描述是公開的:

curl https://api.kukopay.com/v1/openapi.json -o kukopay.v1.json

它由服務端代碼直接生成,所以裏面的枚舉值(訂單、退款和拒付狀態,事件類型,資金流水類型)、錯誤碼和限額總是與線上接口的實際行為一致。新增了什麼,規範也會隨之變化。

規範裏有什麼

  • 一個服務地址:https://api.kukopay.com/v1,沙箱和正式環境共用——環境由 API 密鑰決定,所以不需要配置第二個基礎地址。見 沙箱與正式環境的區別。
  • 一種鑑權方式:放在 X-Api-Key 請求頭裏的 API 密鑰。
  • 寫請求上的 Idempotency-Key 請求頭,見 冪等鍵是什麼。
  • 穩定的 operation id——createOrder、retrieveOrder、listOrders、createRefund、listBalanceTransactions、createWebhookEndpoint 等——按標籤分組(Orders、Refunds、Disputes、Balance、PaymentLinks、Webhooks、Events、Logs)。生成器會把它們變成方法名。
  • 每個對象和錯誤響應的 Schema,包括錯誤碼目錄,見 支付接口錯誤處理。

方式一:只生成 TypeScript 類型

如果你已經有 HTTP 客戶端,只想讓編譯器檢查請求和響應,就生成類型:

npx openapi-typescript https://api.kukopay.com/v1/openapi.json -o src/kukopay.d.ts

你會得到每個接口的請求和響應結構,枚舉值是字符串聯合類型——所以 status === "payed" 編譯不過。

方式二:生成完整的客戶端 SDK

如果除了模型還要生成方法,用 OpenAPI Generator 並選擇你的語言:

npx @openapitools/openapi-generator-cli generate \
  -i https://api.kukopay.com/v1/openapi.json \
  -g python \
  -o ./kukopay-client

把 -g python 換成 typescript-fetch、go、java、php 或其他生成器即可。這份規範是 OpenAPI 3.1;請確認你選擇的生成器和版本對 3.1 的支持足以滿足你的語言,並在依賴它之前通讀一遍生成的代碼。

無論用什麼生成,客戶端的配置都一樣:基礎地址 https://api.kukopay.com/v1,從服務端密鑰存儲裏讀取的 X-Api-Key 請求頭,以及在可能重試的寫請求上帶 Idempotency-Key。

方式三:導入 Postman

在 Postman 裏 Import 規範地址,就能得到一個每個接口一條請求的集合。在集合級別設置 kuko_test_ 開頭的 X-Api-Key,就可以手動創建沙箱訂單、退款和 Webhook 端點——寫代碼之前用來摸索很方便。不要把正式密鑰放進共享工作區。

契約測試:讓客戶端與接口保持同步

生成的客戶端只會和它所依據的規範一樣準確。兩個習慣能讓它保持準確:

  • 在 CI 裏重新生成。 拉取 openapi.json、重新生成,如果生成的代碼有變化卻沒有提交,就讓構建失敗——新的枚舉值或字段會以 diff 的形式出現在你面前,而不是在生產環境裏給你一個意外。
  • 在沙箱測試裏校驗響應。 對沙箱運行集成測試,並用你所用語言的 OpenAPI 校驗工具,按規範的 Schema 校驗每個響應。不匹配時,問題出在你的映射代碼,而不是某筆支付。

生成的客戶端不會替你做的事

  • Webhook。 校驗 X-KukoPay-Signature 和事件去重的代碼要你自己寫,見 Webhook 驗簽怎麼做。
  • 重試與調用頻率。 按錯誤類型決定哪些要重試,並遵守 429 響應的 Retry-After,見 API 調用頻率限制。
  • 分頁。 用 starting_after 循環直到 has_more 為 false,見 游標分頁詳解。
  • 記錄 request_id。 每個響應都要保存,客服排查時要的就是它。

總結

  • 有了 OpenAPI 規範,就可以生成接口客戶端,而不用手寫 HTTP 調用;
  • KukoPay 的 OpenAPI 3.1 規範公開在 https://api.kukopay.com/v1/openapi.json,由服務端代碼生成,枚舉值和錯誤碼與線上接口一致;
  • 用 openapi-typescript 生成 TypeScript 類型,用 OpenAPI Generator 生成完整 SDK,或導入 Postman;
  • 一個基礎地址同時服務沙箱和正式環境,用 X-Api-Key 鑑權;寫請求帶 Idempotency-Key;
  • 在 CI 裏重新生成,按規範校驗沙箱響應,Webhook 驗簽、重試和分頁仍然要自己寫。

在沙箱裏把它跑通

註冊商戶後即可申請測試密鑰,不需要等待資質審核。