PHP 開發的 API 多版本管理實踐

遇到的情況

本文針對移動網際網路客戶端需要相容舊版的情況，強制升級到最新版本的 app 不在討論之列。

在 bugtags.com 專案中，我們的版本遵循下面規範。 1.0.1 大功能.小更新.bug 修正 我們的版本列表如下：

1.0、1.1、1.2、1.3、1.4 2.0、2.1、2.2、2.3 3.0、3.1 … 5.0

這樣一個版本結構，所有版本都可以用，跨度最大時，1.0 使用者要跟 5.0 使用者並存。 以 /api/user/info 介面舉例，經過這麼多版本的迭代，版本 1.0 跟 3.0 的返回資料結構可能已經完全不同了。 對於這樣一個系統，如何設計一個完備的版本架構非常重要。

理解其中的困難

移動網際網路，有別於傳統的 web 開發。其快速迭代、版本升級與傳統的 web 開發相比，有如下困難：

使用者獲取困難，留存率低 客戶端升級成本高，部分使用者拒絕升級 多個版本伺服器端程式碼量大，急劇拉高維護成本 架構的目的及要求

簡化版本管理流程,易配置管理 縮小伺服器端的 php 程式碼規模 儘量不要引入新的要素 微信群裡的討論

請求形式的約定

使用域名，如 v1.api.bugtags.com 來區分介面的版本 將版本資訊放到 url 的 pathinfo 中，如 api.bugtags.com/v1/ 將版本資訊放到請求引數中，如 api.bugtags.com/user/1?_ver=1.0.1 將版本資訊放到 http header 中，如 API_VER: 1.0.1 版本號用域名是比較不被認同的方案，主要原因是域名管理往往跨部門，增加了溝通成本。 http 頭是我個人最贊同的一種方式，可以保持 url 的整潔。 url 引數中攜帶版本號的方式也很好，但是要注意不要跟業務邏輯的引數名重複。

兩種常見的管理程式碼的方式

git/svn 的 tag 管理方式

優點，隨時切換分支成本低，尤其在 git 管理程式碼時。 缺點，如果多個版本需要修改時，程式碼合併工作量大。

只有一個分支，在程式碼中根據版本資訊做判斷

優點，程式碼的總體規模小（只有一份程式碼） 缺點，在需要判斷版本的地方會有大量的分支語句

我總結的解決辦法

最後的解決辦法充分利用了 php 的 autoload 載入機制和名稱空間。

假設 base 是所有業務的基礎，是第一個版本，也是生命週期最長的版本。 v10 對版本 1.x.x 提供服務，最大限度消除業務點上的版本邏輯判斷，但是不絕對拒絕。 v20/v30 基於 v10 版本開發 v40 版本基於 v30 版本開發

舉例說明

v10 提供 a,b,c 三個介面 v20 提供 a1,b,c 三個介面, a1 是 a 的修改 v30 提供 a,b1,c 三個介面, b1 是 b 的修改

用下面三段程式碼來具體描述

配置版本：

基礎目錄 base 存放大部分公共程式碼 版本目錄 v10/v20 都是版本目錄，裡面存放此版本與 基礎版本不同的邏輯 版本區別以檔案為最小粒度，以上面三段程式碼可以看出。 使用者要訪問 /api/user/info?ver=3.0.1 此時，類的載入順序依次為:

在 v30 下嘗試載入 Config.php 失敗 在 v10 下嘗試載入 Config.php 失敗 在 Base 下嘗試載入 Config.php 成功 執行相關邏輯 這是限制只能繼承一層的原因是儘可能的降低系統的複雜度。這種方式管理程式碼已經在幾個專案中得到一些驗證。系統程式碼的複雜度可以很大程度上降低，尤其是多個版本迭代、又不能強制升級的系統中。另外需要注意的就是 :

使用這個方式處理載入時，在經過幾個版本的沉澱後，應該將通用部分漸漸沉澱到BASE版本中 釋出系統最好帶有刪除檔案功能，否則被部分沉澱後，高版本會依舊使用高版本的程式碼。 筆者在開發和運營 bugtags.com ，這是一款能夠極大的提升 app 開發者測試效率的 SDK 產品，歡迎使用、轉發推薦。

我們團隊長期求 PHP 後端，有興趣請加下面公眾號勾搭：