接口設計的五點建議！

時間 2019-11-10

標籤接口設計五點 5點建議简体版

原文原文鏈接

本文首發於我的微信公衆號《andyqian》，關注便可內推 BAT程序員

前言

接口是目前：先後端交互(Rest)，系統交互(RPC)最廣泛的一種方式。一個好的接口，應該清晰易懂，職責明確，易於維護。反之，則會形成不少困擾。特別是Open API，誰作誰知道。基於這樣的前提以及本身以前踩過的坑，就成了這篇文章的由來。後端

編寫文檔

文檔與程序員之間有着一種很是奇妙的關係。一句話歸納就是：」寫之，痛之。用之，悔之」。怎麼解釋呢？就是：寫的時候以爲很痛苦，不肯意寫！用的時候呢，又後悔當初沒有留下文檔！ 可見文檔是多麼重要。以Rest接口爲例，文檔須要詳細的記錄請求參數，返回參數，每一個字段的意思，是否必填，請求方法等。隨着代碼的更新，文檔也應該及時更新。在不少開發者眼裏(包括我本身)，以爲寫文檔是一件浪費時間的事情，寫代碼纔是正經事。隨着工做經驗的積累，愈發以爲文檔的重要性，不但沒浪費時間，反而還在節省時間。設計模式

符合最小原則

這個原則實際上是有點像設計模式中的迪米特法則(也稱爲：最小知識原則)，不過我認爲這其中包含了兩層意思：微信

其一：在接口設計中，請求參數在保證功能的前提下：儘量的減小參數，更不容許添加無用的參數。以Rest接口爲例：一旦添加了無用的參數，在後續迭代過程當中，就會遇到：棄之惋惜，留之無用 的尷尬局面。對於 Client 端也會形成困擾，還會浪費帶寬。框架

其二：接口粒度應該儘可能小且保持單一職責，不要寫大而全的接口。單一職責的好處沒必要多說，是一個老生常談的問題。分佈式

新老兼容

在接口設計中，新老接口的兼容是必需要考慮的，堪稱事故多發地。優化

常見事故以下所示：spa

v1 版本 API 上線發佈後。隨着需求變化，須要在v2 接口版本中新增幾個字段。上線後，發現使用v1 版本的客戶端業務中斷。(v1版本沒有兼容V2版本(新字段)致使)。
v1 版本 API 上線發佈後。隨着需求變化，須要刪除某個接口。系統上線後，形成低版本客戶端業務中斷 (沒有兼容老的Client Version 致使)。

…線程

對於 Rest 接口，在這方面須要特別注意。由於客戶端更新的週期是漫長的，以微信Android客戶端爲例。目前最新版本是：V7.0.6，但事實上：並非每個Android客戶端的版本都是最新的V7.0.6，有多是：V6.7.2，也有可能更低。對於微信這類國民軟件而言，每個版本影響的用戶數都是極大的。若是不兼容，形成影響是巨大的。設計

對於這種狀況，API接口的更新：通常會採用新老版本並行使用進行過渡，並在大版本中進行逐步更新，直至沒有Client Version進行使用時，API接口才能進行下線。

一樣的道理，放在內部的 RPC 接口也適用。前一段時間還犯了一個這樣的錯，事情是這樣的：在更新一個必須強制更新RPC接口時，採用了同步發佈法。當時覺得所有理清楚全部調用端，上線後，依然形成了生產事故，由於還有一個調用端沒有在計劃內。這樣作的弊端包括但不限於如下幾點：

涉及應用多，(若是該接口爲底層服務，那調用的上層應用都須要同步修改，一旦缺乏一個，則會發布失敗)。
發佈時間長

…

事實上：咱們應該儘可能避免這種」同步發佈法」，這也是阿里研究員谷樸老師在《API 設計最佳實踐的思考》中特別提到的一點。

及時移除不要的代碼

這個確實是一個容易忽略的細節。我本身也有過這樣的經歷，特別是一些策略性的代碼及產品代碼中，很是容易出現這樣的現象。例如：某段代碼一開始是有的，後面由於優化也好，由於調整也好，要去掉。但「自認爲「後面仍是會使用，則將其註釋之。時而久之，這段註釋的灰代碼就此紮根，誰也不敢修改。代碼中的壞味道就此慢慢的發酵，直至變臭。所以：不管從擴展方面，仍是可維護方面考慮，都建議及時清除沒必要要的代碼。