資訊中心:PHP 介面開發:聯調、鑑權和錯誤處理
一、先定契約
每個介面寫清:
- 資源和方法:
GET /api/v1/orders。 - 請求參數:位置、類型、必填、範圍。
- 響應結構:欄位、類型、示例。
- 錯誤碼:HTTP 狀態 + 業務碼。
- 鑑權方式。
- 冪等規則。
- 版本策略。
示例:
{
"code": 0,
"message": "ok",
"data": {
"id": 1001,
"status": "paid"
},
"trace_id": "req_abc123"
}
二、鑑權
常見方式:
- Session/Cookie:適合約域後台。
- Bearer Token:適合前後端分離。
- HMAC 簽名:適合服務端對服務端。
- OAuth2:適合第三方授權。
要點:
- 每個介面明確權限。
- 不只在前端隱藏按鈕。
- Token 有效期和重新整理機制。
- 金鑰不進程式碼庫。
- 失敗返回統一錯誤,不泄露細節。
三、參數校驗
- 類型、長度、範圍、枚舉。
- 必填和預設值。
- 檔案類型和大小。
- 防注入:預處理語句、輸出轉義。
- 防越權:資源歸屬校驗。
- 防批次賦值:只接收白名單欄位。
校驗失敗返回 4xx,不要 500。
四、冪等與併發
- 創建訂單/支付等介面支援冪等鍵。
- 重複請求返回同一結果。
- 資料庫唯一索引兜底。
- 併發更新用版本號或行鎖。
- 避免“先查後寫”的競態。
五、錯誤處理
統一結構:
| 欄位 | 說明 |
|---|---|
| code | 業務碼,0 成功 |
| message | 可讀資訊 |
| data | 成功資料或 null |
| trace_id | 排障追蹤 |
HTTP 狀態建議:
- 200 成功。
- 400 參數錯誤。
- 401 未登入。
- 403 無權限。
- 404 不存在。
- 409 衝突。
- 422 業務校驗失敗。
- 429 限流。
- 500 服務異常。
不要把異常堆棧返回給前端。
六、日誌與監控
- 記錄請求 ID、使用者、介面、耗時、狀態。
- 敏感欄位脫敏。
- 慢介面告警。
- 錯誤率告警。
- 保留可追溯時間。
七、限流與安全
- 按 IP/使用者/介面限流。
- 防重放:時間戳 + nonce。
- 防 SSRF:限制回呼地址。
- 上傳:類型、大小、儲存隔離。
- CORS 白名單。
- HTTPS。
八、聯調
給前端/對方:
- 介面文件。
- 環境地址。
- 測試帳號。
- 示例請求和響應。
- 錯誤碼表。
- Mock 資料。
- 變更通知。
聯調問題多半是契約不清,不是程式碼不會寫。
九、版本與相容
- URL 版本:
/api/v1/。 - 欄位只增不刪,廢棄欄位標注。
- 破壞性變更提前通知。
- 保留過渡期。
十、驗收
- 每個介面有文件和示例。
- 鑑權和越權測試通過。
- 參數校驗覆蓋。
- 冪等和併發測試。
- 錯誤碼統一。
- 日誌能定位。
- 限流生效。
- 壓測達標。
報價和週期
按“介面數量 + 鑑權方式 + 對接系統 + 文件/測試 + 驗收標準”評估。只按“一個介面多少錢”報價,後期容易因聯調和變更超支。
相關閱讀: