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

使用簡潔的語法來描述對象、數(shù)組、字典等復(fù)雜結(jié)構(gòu)。

通過命名規(guī)范，讓一個名字自發(fā)地體現(xiàn)出它的類型。如名詞復(fù)數(shù)用于對象數(shù)組，以Id結(jié)尾默認(rèn)是整型等等。

考慮一個移動互聯(lián)網(wǎng)的產(chǎn)品，要做一個手機(jī)APP，前端通過某種RESTFul風(fēng)格的接口規(guī)范來調(diào)用服務(wù)端接口，請求時通過urlencoded方式來傳參數(shù)，返回內(nèi)容采用JSON格式。假設(shè)現(xiàn)在需要一個查看訂單的接口，返回訂單詳情，可以這樣描述你的設(shè)計：

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

其中，返回對象使用了蠶繭法進(jìn)行簡要的描述，將復(fù)雜數(shù)據(jù)類型層層剝開直到基本類型，而基于命名約定，參數(shù)或?qū)傩缘拿Q隱含了它的基本類型，無需再多解釋。在內(nèi)部團(tuán)隊，如果每個人（架構(gòu)師，開發(fā)，測試人員）已經(jīng)對產(chǎn)品中的基本術(shù)語如order-訂單, item-用戶購買的物品這些了解之后，上面的設(shè)計幾乎不需要任何多余的描述文字，因為它已經(jīng)清楚的展現(xiàn)了每個對象的數(shù)據(jù)類型和含義：

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

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

一個產(chǎn)品的內(nèi)部接口會有很多，少則十幾二十個，多則有上百個。怎樣才能維護(hù)好它們？要不要有文檔？應(yīng)該怎樣寫文檔？

筆者對內(nèi)部文檔的觀點是：

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

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

• 文檔也應(yīng)納入版本控制。

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

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

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

• 應(yīng)有機(jī)制保證接口文檔與代碼的一致。

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

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。