通過OPTIONS交換schema

透過 OPTIONS 交換 Schema：終結前後端接口扯皮的實戰方案

Web 開發裡有個老生常談的痛點：接口的調用方和提供方，總是在對接口規格的理解上「打架」。前端覺得後端文檔不明確，後端覺得前端傳參不規範，一來一回，時間和精力都耗在扯皮上了。

說到底，根源在於缺乏一個統一的驗證標準。文檔靠人腦解讀，校驗邏輯各寫各的，一旦出錯，很難快速定位是調用方傳參問題，還是服務端接口錯誤。而跨團隊、跨框架、跨語言的場景，更是把這個問題放大到讓人心煩。

有沒有辦法徹底化解這種尷尬？答案是用 OPTIONS 方法來交換 Schema。一旦導入這套方案，OPTIONS 返回的 Schema 就是唯一的標準——提供者自己可以驗證暴露的 API 是否正確，而調用者也能直接校驗自己的請求是否合乎規範。

來看一個簡單的流程示意：

客戶端                        服務端
  │                            │
  ├── OPTIONS /api/v1/users ──►│
  │◄── MetaMessage Schema ────┤
  │    (struct definition)      │
  │                            │
  ├── POST /api/v1/users ─────►│
  │◄── MetaMessage Response ──┤

服務端的每個接口都綁定了這個 Schema，只有符合定義的請求才算合法；而客戶端發出的請求，也必須對應這個 Schema。因為 OPTIONS 接口和正常數據接口是同時提供的，客戶端可以先通過 OPTIONS 獲取 Schema，再用它校驗自己的請求。

一旦 Schema 成為中介，客戶端和服務端的請求和響應格式就能完全對齊，格式不一致導致的怪問題自然消失。

當然，實戰中還得考慮一個關鍵問題：每次請求之前都要發一次 OPTIONS 嗎？這顯然不現實。

解法很簡單——快取 Schema。對服務端而言，接口程式啟動後通常不會變動，只需快取一次，後續每次請求直接返回即可，開銷基本為零。服務端返回的 Header 裡會帶上 Access-Control-Max-Age 和 Schema-Md5 兩個字段。

客戶端靠 Access-Control-Max-Age 知道服務端建議的快取時長（比如 24 小時），在這段時間內就不用重複發 OPTIONS 請求。如果服務端內部更新了 Schema（透過 Schema-Md5 變化來發現），會返回錯誤信息提示客戶端重新獲取，客戶端再次發起 OPTIONS 更新本地快取即可。

簡單說：只要把 Access-Control-Max-Age 設為 24 小時，客戶端一天內只會觸發一次 OPTIONS 請求；萬一中間 Schema 變了，服務端返回錯誤信號，客戶端自動重新拉取。這樣既減少了網路開銷，又保證了校驗的及時性。

這套思路在實踐中已經有對應的庫可以用，比如 Python 生態下的 mm-web-py（支援 FastAPI、Flask、Django），以及 Go 生態下的 mm-web-go（支援 Gin、Echo、Fiber、Chi、net/http 原生框架）。有興趣的話可以直接拿來整合，省去手擼的功夫。