蠶繭表示法是一個接口描述的規范。我用它的一個典型的場景就是寫內部接口文檔。蠶繭法體現了兩個思想：

使用簡潔的語法來描述對象、數組、字典等復雜結構。

通過命名規范，讓一個名字自發地體現出它的類型。如名詞復數用于對象數組，以Id結尾默認是整型等等。

考慮一個移動互聯網的產品，要做一個手機APP，前端通過某種RESTFul風格的接口規范來調用服務端接口，請求時通過urlencoded方式來傳參數，返回內容采用JSON格式。假設現在需要一個查看訂單的接口，返回訂單詳情，可以這樣描述你的設計：

根據id獲取訂單： getOrder(id) -> {id, userId, dscr, total, %address, @lines}address: {country, city, street, name, phone} lines: [{itemId, qty, price}]

其中，返回對象使用了蠶繭法進行簡要的描述，將復雜數據類型層層剝開直到基本類型，而基于命名約定，參數或屬性的名稱隱含了它的基本類型，無需再多解釋。在內部團隊，如果每個人（架構師，開發，測試人員）已經對產品中的基本術語如order-訂單, item-用戶購買的物品這些了解之后，上面的設計幾乎不需要任何多余的描述文字，因為它已經清楚的展現了每個對象的數據類型和含義：

• 接口返回一個對象，包含id, userId等等屬性。
• 其中address屬性是一個對象，它又包含country, city等屬性。
• lines屬性是一個數組對象，數組的每一項是一個Line對象，它包含itemId, qty等屬性。
• id是對象的主鍵，其它以id結尾的字段如itemId是指向其它對象的外鍵。它們都是整型類型。像total, qty, price這些是貨幣類型（Currency/Money/Decimal），分別表示總金額，數量和價格。其它屬性未明確標示的都是字符串類型。

可以以這樣簡潔的描述讓所有參與的人都能看的很明白，主要得益于大量的約定，比如利用蠶繭法描述對象，數組，字典等，再如良好的命名規范，不僅從名稱中可以了解它的含義，也暗示出它的類型。

一個產品的內部接口會有很多，少則十幾二十個，多則有上百個。怎樣才能維護好它們？要不要有文檔？應該怎樣寫文檔？

筆者對內部文檔的觀點是：

• 接口需要有文檔來記錄。

  我見過很多小團隊的產品根本沒有文檔，遇到接口不明確時都是直接找代碼，看似省確很多事，實則為之后的維護埋下了雷。

• 文檔也應納入版本控制。

  原始文檔應該使用文本類型。某個改動是誰做的，因為什么原因做的，只有應用了版本控制才能方便的做到問題追源。使用文本類型的文檔（比如markdown, wiki等格式），一則方便比較版本間改動，二則可以生成html, word, pdf等多種美觀格式。我見過有好多團隊是使用word來寫文檔的，由于是二進制格式，不利于版本比較，也不專業。還有好多在文檔在頂部還標有版本歷史，以及是誰編輯的做了哪些修改這些內容，真的沒必要（除非是特別重大的變化希望讀者知曉），隨便用svn, git等版本工具就可以做的更專業。

• 文檔要在沒有歧義的基礎上足夠簡潔。

  很多文檔描述很多，而真正有價值的內容并不會增加很多。比如參數或字段的描述，如果從名字就能很清楚的知曉它的含義，又何必再寫一遍（或翻譯一遍）呢，白白增加了很多開銷，維護也麻煩了很多。文檔不應浮于形式，而是力求只寫最有價值的內容。做好這一點的關鍵是作者與讀者要有足夠的約定，比如蠶繭法就能很好的幫助簡化類型定義的描述。

• 應有機制保證接口文檔與代碼的一致。

  一些團隊在文檔上應付差事浮于形式，在代碼寫完后，補一個word文檔應付。在更新代碼時，文檔沒有及時更新，導致文檔都是錯誤沒法看。好的做法都應先有設計再寫代碼，比如架構師或主程先設計好接口，然后再開始編程實現，在實現中發現問題再修正接口，更新設計文檔，而不應是寫完代碼再補個設計。而在文檔更新的具體做法上，也流行一種做法即文檔以注釋的方式內嵌于代碼中，我稱之為“格式化注釋”，這樣做到設計與代碼在一起，更新也就更自然的同步了。之后再通過工具將注釋抽出來美化給讀者看。

總結

以上是生活随笔為你收集整理的用蚕茧表示法写简洁实用的接口文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。