PHP 介面開發怎麼驗收:文件、冪等和錯誤碼

介面驗收不看“能不能調通”,而看“重複呼叫會不會出錯、出錯時能不能立刻判斷原因”。

資訊中心:PHP 介面開發怎麼驗收:文件、冪等和錯誤碼

四項驗收標準

標準 說明
文件 第三方不看程式碼能自測
冪等 重複請求不產生重複資料
錯誤碼 每類失敗可區分
日誌 每次呼叫可追溯

文件怎麼驗

  • 是否列出全部欄位與類型。
  • 是否標明必填與可選。
  • 是否給出請求示例與返回示例。
  • 是否說明錯誤碼含義。

標準是:拿文件給另一個人,他能在 30 分鍾內跑通一次呼叫。

冪等怎麼驗

  • 同一請求連續發送兩次,觀察資料是否重複。
  • 網路超時重試後,是否產生兩條記錄。
  • 支付、下單、庫存類介面是否用唯一標識去重。

常見做法:用戶端傳唯一請求號,服務端按請求號判重。

錯誤碼怎麼驗

  • 參數錯誤、權限不足、資源不存在、業務衝突、系統異常,是否各有獨立碼。
  • 是否區分“可重試”與“不可重試”。
  • 返回資訊是否足夠定位,但不泄露內部細節。

日誌怎麼驗

  • 每次呼叫是否記錄請求號、耗時、結果狀態。
  • 失敗呼叫是否能查到入參與出參摘要。
  • 日誌是否可按請求號串聯。

驗收清單

  1. 文件欄位完整、示例可直接跑。
  2. 重複呼叫不產生重複資料。
  3. 錯誤碼分類清晰且有含義說明。
  4. 日誌可定位單次呼叫全過程。
  5. 超時與限流有明確返回。
  6. 敏感資訊不在日誌中明文出現。

常見不合格表現

  • 所有錯誤都返回同一條“操作失敗”。
  • 文件只有欄位名,沒有示例。
  • 重試導致重複下單。
  • 日誌只在成功時寫。

邊界

驗收標準按常規 HTTP 介面整理。涉及第三方對接或金融類業務,需按其規範補充安全與對賬要求。

相關閱讀: