資訊中心:PHP 介面開發怎麼驗收:文件、冪等和錯誤碼
四項驗收標準
| 標準 | 說明 |
|---|---|
| 文件 | 第三方不看程式碼能自測 |
| 冪等 | 重複請求不產生重複資料 |
| 錯誤碼 | 每類失敗可區分 |
| 日誌 | 每次呼叫可追溯 |
文件怎麼驗
- 是否列出全部欄位與類型。
- 是否標明必填與可選。
- 是否給出請求示例與返回示例。
- 是否說明錯誤碼含義。
標準是:拿文件給另一個人,他能在 30 分鍾內跑通一次呼叫。
冪等怎麼驗
- 同一請求連續發送兩次,觀察資料是否重複。
- 網路超時重試後,是否產生兩條記錄。
- 支付、下單、庫存類介面是否用唯一標識去重。
常見做法:用戶端傳唯一請求號,服務端按請求號判重。
錯誤碼怎麼驗
- 參數錯誤、權限不足、資源不存在、業務衝突、系統異常,是否各有獨立碼。
- 是否區分“可重試”與“不可重試”。
- 返回資訊是否足夠定位,但不泄露內部細節。
日誌怎麼驗
- 每次呼叫是否記錄請求號、耗時、結果狀態。
- 失敗呼叫是否能查到入參與出參摘要。
- 日誌是否可按請求號串聯。
驗收清單
- 文件欄位完整、示例可直接跑。
- 重複呼叫不產生重複資料。
- 錯誤碼分類清晰且有含義說明。
- 日誌可定位單次呼叫全過程。
- 超時與限流有明確返回。
- 敏感資訊不在日誌中明文出現。
常見不合格表現
- 所有錯誤都返回同一條“操作失敗”。
- 文件只有欄位名,沒有示例。
- 重試導致重複下單。
- 日誌只在成功時寫。
邊界
驗收標準按常規 HTTP 介面整理。涉及第三方對接或金融類業務,需按其規範補充安全與對賬要求。
相關閱讀: