本文首發於個人微信公衆號《andyqian》, 期待你的關注！
前言
接口是目前：前後端交互(Rest)，系統交互(RPC)最普遍的一種方式。一個好的接口，應該清晰易懂，職責明確，易於維護。反之，則會造成很多困擾。特別是Open API，誰做誰知道。基於這樣的前提以及自己之前踩過的坑，就成了這篇文章的由來。
編寫文檔
文檔與程序員之間有着一種非常奇妙的關係。一句話概括就是：”寫之，痛之。用之，悔之”。怎麼解釋呢？就是：寫的時候覺得很痛苦，不願意寫！用的時候呢，又後悔當初沒有留下文檔！ 可見文檔是多麼重要。以Rest接口爲例，文檔需要詳細的記錄請求參數，返回參數，每個字段的意思，是否必填，請求方法等。隨着代碼的更新，文檔也應該及時更新。在很多開發者眼裏(包括我自己)，覺得寫文檔是一件浪費時間的事情，寫代碼纔是正經事。隨着工作經驗的積累，愈發覺得文檔的重要性，不但沒浪費時間，反而還在節省時間。
符合最小原則
這個原則其實是有點像設計模式中的迪米特法則(也稱爲：最小知識原則)，不過我認爲這其中包含了兩層意思：
其一：在接口設計中，請求參數在保證功能的前提下：儘可能的減少參數，更不允許添加無用的參數。以Rest接口爲例：一旦添加了無用的參數，在後續迭代過程中，就會遇到：棄之可惜，留之無用 的尷尬局面。對於 Client 端也會造成困擾，還會浪費帶寬。
其二：接口粒度應該儘量小且保持單一職責，不要寫大而全的接口。單一職責的好處不必多說，是一個老生常談的問題。
新老兼容
在接口設計中，新老接口的兼容是必須要考慮的，堪稱事故多發地。
常見事故如下所示：
- 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 設計最佳實踐的思考》中特別提到的一點。
及時移除不要的代碼
這個確實是一個容易忽略的細節。我自己也有過這樣的經歷，特別是一些策略性的代碼及產品代碼中，非常容易出現這樣的現象。例如：某段代碼一開始是有的，後面因爲優化也好，因爲調整也好，要去掉。但 “ 自認爲 “ 後面還是會使用，則將其註釋之。時而久之，這段註釋的灰代碼就此紮根，誰也不敢修改。代碼中的壞味道就此慢慢的發酵，直至變臭。因此：無論從擴展方面，還是可維護方面考慮，都建議及時清除不必要的代碼。
相關閱讀:
