服務(wù)API版本控制設(shè)計與實踐

作者：vivo互聯(lián)網(wǎng)服務(wù)器團(tuán)隊-Song jie

一、前言

筆者曾負(fù)責(zé)vivo應(yīng)用商店服務(wù)器開發(fā)，有幸見證應(yīng)用商店從百萬日活到幾千萬日活的發(fā)展歷程。應(yīng)用商店客戶端經(jīng)歷了大大小小上百個版本迭代后，服務(wù)端也在架構(gòu)上完成了單體到服務(wù)集群、微服務(wù)升級。

下面主要聊一聊在業(yè)務(wù)快速發(fā)展過程中，產(chǎn)品不斷迭代，服務(wù)端在兼容不同版本客戶端的API遇到的問題的一些經(jīng)驗和心得。一方面讓團(tuán)隊內(nèi)童鞋對已有的一些設(shè)計思想有一個更徹底的理解，另一方面也是希望能引起一些遇到類似場景同行的共鳴，提供解決思路。

二、通用解決方案

應(yīng)用商店客戶端迭代非常頻繁，發(fā)布新的APP版本的時候，勢必導(dǎo)致出現(xiàn)多版本，這樣服務(wù)端就會導(dǎo)致多個不同的客戶端請求。強(qiáng)制用戶升級APP，可能會導(dǎo)致用戶流失，因此采用多版本共存就是必須的。以下是業(yè)界討論過的的一些SOA服務(wù)API版本控制方法參考[1]。在實際開發(fā)中原則上離不開以下三個方案。

方案一：The Knot 無版本——即平臺的API永遠(yuǎn)只有一個版本，所有的用戶都必須使用最新的API，任何API的修改都會影響到平臺所有的用戶。（如下圖1）

方案二：Point-to-Point——點對點，即平臺的API版本自帶版本號，用戶根據(jù)自己的需求選擇使用對應(yīng)的API，需要使用新的API特性，用戶必須自己升級。（如下圖2）

方案三：Compatible Versioning——兼容性版本控制，和The Knot一樣，平臺只有一個版本，但是最新版本需要兼容以前版本的API行為。（如下圖3）

（引用自：The Costs of Versioning an API）

簡單分析，The Knot只維護(hù)最新版本，對服務(wù)端而言維護(hù)有一定簡化了，但是要求服務(wù)使用者及時適配最新的版本，這種做法不太適用用戶產(chǎn)品，目前內(nèi)部服務(wù)比較適用。Point-Point針對不同客戶的版本提供獨立的服務(wù)，當(dāng)隨著版本的增加開發(fā)和運維的維護(hù)成本會增加，這種在后面我們面對“協(xié)議升級”的時候有使用。

方案三應(yīng)該是最常用的情況，服務(wù)端向后兼容。后面案例也主要采用這種思想，具體的做法也是有很多種，會結(jié)合具體的業(yè)務(wù)場景使用不同策略，這個會是接下來討論的重點。

三、具體業(yè)務(wù)場景面臨的挑戰(zhàn)和探索

3.1 The Knot 無版本和Point-to-Point模式的應(yīng)用場景

上圖是我們應(yīng)用商店迭代變化的一個縮影，業(yè)務(wù)發(fā)展到一定階段面臨以下挑戰(zhàn)：

1）業(yè)務(wù)發(fā)展前期，作為服務(wù)提供方，服務(wù)端不僅要支撐多個版本應(yīng)用商店客戶端，同時服務(wù)于軟件側(cè)的PC助手；

2）產(chǎn)品形態(tài)變化多樣，服務(wù)端接口變更和維護(hù)面臨多版本客戶端兼容的挑戰(zhàn)；

3）架構(gòu)邏輯上，服務(wù)端采用早期傳統(tǒng)架構(gòu)，開發(fā)和維護(hù)成本比較高；服務(wù)端與客戶端進(jìn)行交互的協(xié)議優(yōu)化升級；以及服務(wù)拆分勢在必行。

所以服務(wù)端協(xié)議、框架升級以及公共服務(wù)拆分是首要解決的方向。改造經(jīng)歷了兩個過程：

• 階段一新版本新的接口一律采用新的JSON協(xié)議；已有功能接口進(jìn)行兼容處理，根據(jù)客戶端版本進(jìn)行區(qū)分，返回不同協(xié)議的格式內(nèi)容。

  
  

  
  

• 階段二隨著業(yè)務(wù)迭代，新的版本商店依賴的所有接口都完成了協(xié)議升級后，為了提升服務(wù)的穩(wěn)定性，舊的協(xié)議性能無法明顯提升，一方面升級后端架構(gòu)和框架，提升開發(fā)效率和可維護(hù)性。同時拆分和獨立新的工程，實現(xiàn)歷史工程只提供給歷史版本使用。我們針對大流量高并發(fā)、以及基礎(chǔ)服務(wù)場景比如首頁、詳情、下載進(jìn)行獨立服務(wù)獨立拆分。同時也提取一些公共的內(nèi)部RPC服務(wù)，比如獲取應(yīng)用詳情、過濾服務(wù)等。

  
  

經(jīng)過改造，服務(wù)端架構(gòu)如上圖所示。

1）至此Old-Service后續(xù)只用進(jìn)行相應(yīng)的維護(hù)工作即可，對應(yīng)Point-to-Point版本。

2）內(nèi)部的RPC服務(wù)由于只提供內(nèi)部服務(wù)，服務(wù)端和客戶端可以隨時同步升級，只要維護(hù)最新的版本就可以，采用The Knot模式。這里需要注意的是服務(wù)的升級需要注意保持向下兼容，在擴(kuò)展字段或者修改字段的時候需要特別小心，不然可能在服務(wù)升級的時候會引起客戶端調(diào)用的異常。

3.2 Compatible Versioning：兼容性版本控制

兼容性版本控制應(yīng)該是最常見的版本控制方式，特別是在C/S架構(gòu)當(dāng)中，具體的兼容性版本不同的策略總結(jié)有API版本、客戶端版本號、功能參數(shù)標(biāo)志等。

場景一：API版本號控制

隨著互聯(lián)網(wǎng)發(fā)展的，用戶體驗要求也是越來越高，產(chǎn)品形式也會隨之每年有不一樣的變化。除了避免審美疲勞外，也是在不斷探索如何提升屏效、點擊率和轉(zhuǎn)化。就拿應(yīng)用商店首頁列表舉例。

應(yīng)用列表在形態(tài)上經(jīng)歷過單一的應(yīng)用雙排 -> 單排  -> 單排 穿插的布局。內(nèi)容上也經(jīng)歷了不同商業(yè)化模式、人工排期到算法等演進(jìn)。

每個版本接口內(nèi)部邏輯變化是十分大的，有明顯差異。如果只是簡單在service層根據(jù)版本進(jìn)行判斷處理，會導(dǎo)致處理邏輯會變得異常復(fù)雜，并且還可能導(dǎo)致對低版本產(chǎn)生影響。同時商店首頁是十分重要的業(yè)務(wù)場景，結(jié)合風(fēng)險考慮，類似這樣對場景，在接口URL上新增版本字段，不同對版本使用不同的值，在控制層根據(jù)不同的版本進(jìn)行不同的處理邏輯會更加合理，簡單有效。具體策略也有比如在URL上新增接口版本字段/{version}/index、請求頭攜帶版本參數(shù)等。

場景二：客戶端版本號控制

類似首頁列表，商店的穿插Banner也經(jīng)歷了多個版本的迭代。如下圖所示。這些穿插樣式都是在不同版本下出現(xiàn)的，在樣式布局，支持跳轉(zhuǎn)能力等方面各個版本的支持程度不一樣，接口返回時需要進(jìn)行相應(yīng)的處理適配、過濾等處理。

這類場景如果采用場景一的方案升級新的接口也能夠解決，但是會存在大量重復(fù)代碼，而且新增接口對于客戶端接口改造、特別是一些接口路徑會影響到大數(shù)據(jù)埋點統(tǒng)計，也是有比較高的溝通和維護(hù)成本在里面。

為了提升代碼復(fù)用性。使用客戶端版本號控制是首選考慮策略。但是需要注意，如果只是簡單的在代碼層面根據(jù)客戶端版本號進(jìn)行判斷，會存在以下問題需要考慮：

1）代碼層面會存在各種判斷，造成的代碼可讀性差，有沒有更加優(yōu)雅的方法；

2）存在一個客觀情況。那就是客戶端的版本號是存在不確定性的。由于客戶端采用火車發(fā)布模式 參考[2]，多版本并行開發(fā)，導(dǎo)致版本號存在變動、版本跳躍不連續(xù)的情況時有發(fā)生，也給服務(wù)端開發(fā)帶來了不少困擾。

如何思考解決這些問題呢？其實對于不同的產(chǎn)品形態(tài)涉及的一些資源或者產(chǎn)品模塊本身出現(xiàn)在不同的迭代周期，可以認(rèn)為他們具備了版本或者時間的屬性。站在程序員視角，把某個資源支持對應(yīng)的客戶端版本作為這個資源對象的一個成員屬性。每種資源具有這種屬性后，也有相應(yīng)的邏輯行為來對應(yīng)成員方法---根據(jù)屬性進(jìn)行過濾。這樣的設(shè)計賦予資源了屬性和行為后，資源具備了統(tǒng)一的、靈活的過濾能力，而不再是簡單的硬編碼根據(jù)版本進(jìn)行if-else判斷。

有了方案后，實施起來就比較容易了。開發(fā)分配資源ID，并且設(shè)置對應(yīng)支持客戶端版本范圍。過濾邏輯統(tǒng)一到資源對象。

代碼層面可以將過濾邏輯統(tǒng)一封裝到一個工具類（示例代碼），在各個業(yè)務(wù)接口返回進(jìn)行過濾。更加優(yōu)雅的方案是建立統(tǒng)一的資源上層類，封裝資源過濾方法，所有資源位的資源對象實現(xiàn)該上層類，統(tǒng)一在獲取資源邏輯完成過濾能力。

場景三：新增功能標(biāo)識參數(shù)

應(yīng)用商店業(yè)務(wù)主要提供用戶發(fā)現(xiàn)和下載新應(yīng)用、更新手機(jī)已安裝的應(yīng)用。商店有增量更新可以減小更新包體積，因此也叫省流量更新，有效提升用戶體驗。前期我們使用開源的增量算法，但是發(fā)現(xiàn)該算法在部分機(jī)器合成拆分包會耗時很長，甚至引起crash。

于是項目組尋求更加高效拆分算法。類似在這些已有接口的進(jìn)行功能增強(qiáng)的場景，除了提供新的API或者內(nèi)部簡單通過客戶端版本判斷進(jìn)行擴(kuò)展外，有沒有更好的方案呢？因為除了這些方案已知的弊端外，需要從長遠(yuǎn)考慮，比如前面提到的算法，后續(xù)還會不會存在升級的可能，下載接口會不會有更多能力的增強(qiáng)。

結(jié)合上面思考，在原來接口基礎(chǔ)上新增標(biāo)志參數(shù)字段，表示該請求發(fā)出的客戶端支持的能力。為了后續(xù)擴(kuò)展，字段類型為整數(shù)值，不只是簡單的boolean，服務(wù)端通過位運算完成判斷邏輯。客戶端也擺脫某個功能與版本的強(qiáng)一致性，不用去記錄某個版本具有某種能力。

四、關(guān)于接口設(shè)計的更多思考

最后補(bǔ)充一些踩過的坑和反思。服務(wù)端在提供接口時，不能僅僅關(guān)注接口的實現(xiàn)，更多的時候需要關(guān)注接口的使用方，他們使用的場景、調(diào)用時機(jī)等等。否則開發(fā)在對接口問題排查、維護(hù)花費的時間會比實際開發(fā)的耗時要多上好幾倍。

1）場景化：具體到什么是場景化呢，拿商店客戶端的幫助用戶檢測手機(jī)安裝的應(yīng)用版本是否最新的服務(wù)舉例，檢測時機(jī)是存在不同的場景的，比如用戶啟動、用戶切換wlan環(huán)境、定時檢測等。當(dāng)需要進(jìn)行精細(xì)化分析，哪些請求是有效的，哪些會引起集中請求時，這個時候如果請求上沒有場景區(qū)分，那么分析將無從下手。所以在與客戶端溝通接口設(shè)計時，請帶上場景這個因素。接口設(shè)計上可參考如/app/{scene}/upgrade，定義好各個場景名稱，在路徑上帶上具體的場景，這樣對線上不同來源請求量級、問題分析都會有很大好處。

2）鑒權(quán)和服務(wù)隔離：除了場景需要考慮外，接口調(diào)用在分配時做好記錄和鑒權(quán)以及服務(wù)隔離。比如商店的部分接口服務(wù)不僅提供給客戶端，同時也會提供給手機(jī)系統(tǒng)應(yīng)用調(diào)用。目前vivo上億的存量用戶體量，這里要十分小心，系統(tǒng)應(yīng)用的調(diào)用量控制不當(dāng)，并發(fā)可比商店本身要大的多。首先前期與服務(wù)調(diào)用方評估溝通、做好設(shè)計，避免出問題。即使在出問題時，也要有機(jī)制能夠快速發(fā)現(xiàn)問題、能夠分析出問題的來源，降低問題帶來的損失。

至此上面解決問題的思路，都與具體業(yè)務(wù)以及背景有一定關(guān)系。隨著技術(shù)不斷迭代和發(fā)展，在移動端APP頁面動態(tài)性，目前業(yè)界也有了更多高效的技術(shù)方案，比如谷歌的Flutter、Weex等。這些技術(shù)能夠?qū)崿F(xiàn)靈活擴(kuò)展，多端統(tǒng)一，性能也能夠接近native。不僅減少了客戶端發(fā)版頻次，也減少了服務(wù)端兼容性處理成本。目前我們vivo也有團(tuán)隊在使用和實踐。

技術(shù)不斷更迭，沒有最好的方案，只有最適合的方案。開發(fā)過程中不僅滿足當(dāng)前實現(xiàn)，更多的是考慮到后續(xù)擴(kuò)展性和可維護(hù)性。開發(fā)不能一味追求高端技術(shù)，技術(shù)最終服務(wù)于業(yè)務(wù)，堅持長期主義，效率至上。

五、參考資料

1、The Costs of Versioning an API

2、敏捷開發(fā)，火車發(fā)布模式