PHP 介面開發:聯調、鑑權和錯誤處理

介面品質取決於五件事:契約清楚、鑑權可靠、校驗嚴格、錯誤可查、聯調順暢。先把請求/響應/錯誤碼定死,再寫程式碼,能減少大半返工。

資訊中心: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/。
  • 欄位只增不刪,廢棄欄位標注。
  • 破壞性變更提前通知。
  • 保留過渡期。

十、驗收

  • 每個介面有文件和示例。
  • 鑑權和越權測試通過。
  • 參數校驗覆蓋。
  • 冪等和併發測試。
  • 錯誤碼統一。
  • 日誌能定位。
  • 限流生效。
  • 壓測達標。

報價和週期

按“介面數量 + 鑑權方式 + 對接系統 + 文件/測試 + 驗收標準”評估。只按“一個介面多少錢”報價,後期容易因聯調和變更超支。

相關閱讀: