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 開發相比，有如下困難：

1. 使用者擷取困難，留存率低
2. 用戶端升級成本高，部分使用者拒絕升級
3. 多個版本伺服器端代碼量大，急劇拉高維護成本

架構的目的及要求

1. 簡化版本管理流程,易組態管理
2. 縮小伺服器端的 php 代碼規模
3. 盡量不要引入新的要素

群裡的討論請求形式的約定

1. 使用網域名稱，如 v1.api.bugtags.com 來區分介面的版本
2. 將版本資訊放到 url 的 pathinfo 中，如 api.bugtags.com/v1/
3. 將版本資訊放到請求參數中，如 api.bugtags.com/user/1?_ver=1.0.1
4. 將版本資訊放到 http header 中，如 API_VER: 1.0.1

版本號碼用網域名稱是比較不被認同的方案，主要原因是網域名稱管理往往跨部門，增加了溝通成本。
http 頭是我個人最贊同的一種方式，可以保持 url 的整潔。
url 參數中攜帶版本號碼的方式也很好，但是要注意不要跟商務邏輯的參數名重複。

兩種常見的管理代碼的方式git/svn 的 tag 管理方式

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

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

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

我總結的解決辦法

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

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

舉例說明

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

用下面三段代碼來具體描述

<?php/** * View/Api/Base/Config/Config.php */namespace View\Api\Config;class Config {    function index(){echo __METHOD__;}}?>

<?php/** * View/Api/V10/Config/Config.php */namespace View\Api\Config;class Config {    function index(){echo __METHOD__;}}?>

<?php/** * View/Api/V20/Config/Config.php */namespace View\Api\Config;class Config {    function index(){echo __METHOD__;}}?>

配置版本：

訪問版本	代碼版本
v10	base
v11	base
v20	v10
v30	v10

• 基礎目錄 base 存放大部分公用代碼
• 版本目錄 v10/v20 都是版本目錄，裡面存放此版本與 基礎版本不同的邏輯
• 版本區別以檔案為最小粒度，以上面三段代碼可以看出。

使用者要訪問 /api/user/info?ver=3.0.1 此時，類的載入順序依次為:

1. 在 v30 下嘗試載入 Config.php 失敗
2. 在 v10 下嘗試載入 Config.php 失敗
3. 在 Base 下嘗試載入 Config.php 成功
4. 執行相關邏輯

這是限制只能繼承一層的原因是儘可能的降低系統的複雜度。這種方式管理代碼已經在幾個項目中得到一些驗證。系統代碼的複雜度可以很大程度上降低，尤其是多個版本迭代、又不能強制升級的系統中。另外需要注意的就是 :

1. 使用這個方式處理載入時，在經過幾個版本的沉澱後，應該將通用部分漸漸沉澱到BASE版本中
2. 發布系統最好帶有刪除檔案功能，否則被部分沉澱後，高版本會依舊使用高版本的代碼。

筆者在開發和運營 bugtags.com ，這是一款能夠極大的提升 app 開發人員測試效率的 SDK 產品，歡迎使用、轉寄推薦。

?

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