HTTP API可演進性最佳實踐

2022-02-12 02:59:36 字數 2453 閱讀 5951

正如標題所示,benjamin carlyle試圖在《best practices for http api evolvability》一文中為圍繞http api構建的系統的設計定義原則和實踐,這些系統是可擴充套件的,並且能一直進化下去。他先指出了rest(一種架構風格)和http api(通過http暴露的程式設計介面)之間的區別。

http api是針對乙個特定服務的面向開發者的介面,也被稱為restful服務契約、面向資源架構或uri space。

我說rest和http api緊密相關是因為大多數http api並不嚴格遵守統一介面約束,嚴格說來統一介面約束要求介面是「標準的」[…]

文章開頭他標識出了api設計中的不同元素,這些元素決定了api後續的進化。通常來說,api進化涉及到了設計客戶端與伺服器的相容性;特別是api的向後和向前相容變更。 變更頻率按增序排列依次是:

api中用到的方法的通用語義,包含異常條件和其他元資料

api中用到的**型別的通用語義,包含全部schema資訊

構成api的uri集合,包含api中用到的每個通用方法和**型別的特定語義

api進化中改變最少的就是方法的語義。文中描述的最佳實踐是識別出向前和向後相容的變化,運用postel法則讓服務與客戶端以一種更能容忍的方式進行進化。他建議盡可能地使用http錯誤碼來傳達相容性問題。

最佳實踐3:新方法名應該選擇那些不會和任何已有方法發生向前相容的名字。例如,如果要處理的方法必須正確理解(必須理解語義)方法的新特性,那麼應該選擇乙個新的方法名。

最佳實踐4:服務應該忽略它們不理解的標頭或元件。**應該不加修改地傳遞這些標頭,或者是無法理解的元件。

[…]最佳實踐7:在某個數字範圍內為新狀態分配乙個狀態碼,這個範圍可以粗粒度地標識已存在的條件。

[…]最佳實踐9:如果新狀態是乙個已知狀態(除了400 bad request或500 internal server error)的子集,可以向響應頭新增資訊來細化已知狀態的含義,而不是分配乙個新的狀態碼。

他指出了乙個重要的區別,即客戶端與伺服器互動中**型別的對稱本質。

[…]與客戶端和伺服器之間非對稱的方法和狀態不同,**型別通常能用作請求或響應的負載,即適用於兩個方向。為此本節中我們不討論客戶端與伺服器,而是講傳送端與接收端。

...這構成了與**型別相關的最佳實踐的基礎

[…]

最佳實踐11:只有當驗證邏輯是為與文件傳送方相同版本或後續版本的api編寫的情況下,才可能出現不符合最佳實踐10的文件驗證。

最佳實踐12:在不違反**型別設計目標的前提下,如果能向現有**型別的schema中新增新資訊,那麼就新增吧。

他提倡使用content-types和accept標頭來管理傳送端與接收端之間的相容性。

http api習慣於做出向後不相容的**型別schema變更。新客戶端請求或者提供了schema中帶有向後不相容變更的新**型別。老的客戶端繼續請求或提 供舊的**型別。直到所有重要的相關實現都公升級到最新的**型別集之前,客戶端與伺服器端都應該要支援舊的**型別。

他認為對資源的修改,尤其是uri的修改都是伺服器應該關心的事;如果客戶端是設計成由超**約束驅動的話,一般這些修改都不應該引入相容性問題。他提倡使用cookies將客戶端請求路由到合適的服務例項/伺服器。

在使用多種通用方法時,我們不再處理通用的方法或**型別,而是和帶有特定語義的特定url打交道。[…]在考慮如下服務契約時,我傾向於採用以伺服器為中心的視角:

get /invoice//paid,返回**型別text/plain(xsd:bool語法),內容是invoice-id指定的發貨單的支付狀態

put /invoice//paid,接受**型別text/plain(xsd:bool語法),設定invoice-id指定的發貨單的支付狀態

此外,他還提出了一些客戶端的最佳實踐,以便客戶端能應對伺服器uri的轉變(transition)和進化。

最佳實踐19:在公升級時,服務應該通過cookies追蹤哪些客戶端應該連線到舊的伺服器,哪些應該連線到新的伺服器,或者也可以使用類似的機制。

最佳實踐20:即使不是在響應head或get請求,客戶端也應該遵從伺服器發回的重定向狀態響應[說明:rfc2616]。

最佳實踐21:重新設計url時,確保新的url擁有和舊url一樣的語義,並將舊url重定向到新的url上。

本文中提供了一些基本原理,讓http api系統能隨著時間不斷進化。請務必閱讀benjamin carlyle的完整原文以便對這一主題能有更深入的理解。

檢視英文原文:best practices for http api evolvability

《京東物流系統架構演進中的最佳實踐》閱讀筆記

青龍系統架構演進過程中,從高可用,高效能,資料一致性,使用者體驗四個方面,積累了豐富的經驗,確保了青龍系統在發展過程贏得了公司內外的口碑。每年 雙十一 都是網購狂歡節,假設當天哪個電商系統出現系統不可用,那幾乎是災難性的,不僅會導致使用者快速流失,而且,公司將承受重大損失,甚至在未來競爭中失敗。即使...

13種提高系統伸縮性的最佳實踐

1,盡可能地使用非同步通訊.2,為提供不同服務的硬體引入故障隔離.3,在多層系統中,使用cache.4,從使用者角度監控你的系統效能.5,使用資料庫複製,降低單點讀壓力.6,根據使用者和業務的不同,將應用或資料庫分片.7,減少使用關係型資料庫的複雜特性.盡可能把它當做是乙個持久儲存裝置.8,以循序漸...

13種提高系統伸縮性的最佳實踐

1,盡可能地使用非同步通訊.2,為提供不同服務的硬體引入故障隔離.3,在多層系統中,使用cache.4,從使用者角度監控你的系統效能.5,使用資料庫複製,降低單點讀壓力.6,根據使用者和業務的不同,將應用或資料庫分片.7,減少使用關係型資料庫的複雜特性.盡可能把它當做是乙個持久儲存裝置.8,以循序漸...