核心原則
- URL 中顯式帶版本：`/api/v1.0/...`、`/api/v2.0/...`，老版本不變，新版本新路徑，平滑過渡；
- 請求頭或參數標識平台：`os=android` / `os=ios` / `os=web`，或在 Header `X-Client-Platform` 傳遞，服務端據此返回差異化字段/邏輯；
- 統一響應格式：
{ "code": 0, "msg": "ok", "data": {...} }，`code` 非 0 即錯誤，前端統一攔截處理；
- 字段級版本兼容：新增字段不刪舊字段，舊版本客戶端忽略未知字段（JSON 天然支持）；
- 業務邏輯下沉：Controller 薄，Service 層封裝核心邏輯，便於多版本復用。
路由示例
GET /api/v1.0/users/profile?os=android
POST /api/v2.0/orders?os=ios
版本棄用策略
- Header `Sunset: Sat, 01 Jan 2025 00:00:00 GMT` 告知客戶端棄用時間；
- 運行期監控各版本調用量，低於閾值才下線。
擴展性設計 Tips
- 使用策略模式隔離平台差異邏輯（如支付、分享、推送）；
- 配置中心管理功能開關，實現灰度發布、AB 測試；
- API 文檔自動生成，強制字段描述、示例、廢棄標記。
總結
版本在 URL，平台在參數，格式統一，字段只增不減，邏輯服務化——這套組合拳能應對 90% 的移動端 API 演進場景。
