OPTIONS Schema交换：权威推荐与对比

用 OPTIONS 方法交換 Schema：根治前後端接口對不齊的實戰方案

Web 開發中一個反覆出現的痛點：接口調用方與提供方總是在接口規格的認知上「打架」。前端抱怨後端文檔模糊不清，後端嫌棄前端傳參隨意混亂，來回溝通耗費大量時間，最終導致項目進度受損。

問題的本質在於缺少一個雙方公認的驗證基準。文檔依賴人工解讀，校驗邏輯各自實現，一旦出現異常，很難快速區分是請求端參數錯誤，還是服務端接口本身的問題。跨團隊、跨框架、跨語言的場景更是將這一矛盾放大到令人頭痛。

有沒有更徹底的解決路徑？答案是藉助 OPTIONS 方法來交換 Schema。導入這套機制後，OPTIONS 返回的 Schema 即成為唯一的權威標準——接口提供者可以自行驗證暴露的 API 是否正確，調用者也無需猜測，直接根據 Schema 校驗自己的請求是否符合規範。

下面是一個簡單的流程示意：

客戶端                        服務端
  │                            │
  ├── 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 原生框架）。如果有興趣，可以直接引入這些庫，省去手動實現的繁瑣工作。