摘要：納尼隔壁少林派表示自家金剛技壓群雄在座各位都是。。。納尼你覺得寫太繁瑣了你不喜歡我們還有或者等等一大堆工具呢。納尼沒有你還是覺得無法接受好吧那么筆者推薦類似這類更友好的工具你可以導入導出其他格式也可以使用其來撰寫。

說起微服務, 想必現在的技術圈內人士個個都能談笑風云, 娓娓道來。的確, 技術變革日新月異, 各種工具框架雨后春筍般涌現, 現在我們可以輕巧便捷地根據自己的業務需求, 構建一個個微服務。

按Wikipedia的解釋: 微服務是一種以業務功能為主的服務設計概念，每一個服務都具有自主運行的業務功能，對外開放不受語言限制的 API (最常用的是 HTTP)，應用程序則是由一個或多個微服務組成。

跨語言的確是實現了, 但這僅是從編程語言的維度來定義。人與人之間的跨越可就沒這么方便嘍, 你華山派門下有獨門的Restful調用, 我武當派一向Thrift一招走天下。 納尼！隔壁少林派表示自家金剛Protobuf技壓群雄, 在座各位都是。。。

別鬧了, 如果大家都把自己的武林秘籍寫得通俗易懂, 豈不是人人皆可練百家武學?

推薦技能: Markdown
難度系數: ★☆☆☆☆

當Boss讓你構建一個新項目時, 我相信你是幸運的, 因為迎接你的是嶄新的開始, 而不是某位已經離職的前輩留下的天書般的舊項目。

如果你的直覺認同我上述觀點, 那么我相信你肯定珍惜這一次編碼機會, 于是你開始使用你熟悉的腳手架工具在Gitlab上構建你的空白工程。

什么?! 這就完了? 不不不, 在這之后, 先別猴急著開始寫代碼, 放松下, 讓我們touch一個README, 想象一下你的項目架構應該是怎樣的, 大致提供些什么功能, 供別人調用的入口代碼應該設計成什么樣, 你的項目所需的技術棧有哪些, 甚至能想到的Todo列表等等。

這些都可以先填補到你的README上, 有余力的話甚至可以用一些原型工具(如: ProcessOn,Pencil,Cacoo)設計一些架構草圖、時序圖那就更好了, 如果你手頭的確沒合適的工具, 那么嘗試用原始的紙筆畫一下拍張照片也行。

(圖: 良好的README樣例)

一個落落大方的README, 方便了團隊的其他成員迅速理解你的項目核心功能, 讓人看著就賞心悅目!

用心寫好了一個README, 才會感覺自己好像在寫一個偉大的項目不是么? 有時候你需要給自己定一個小目標, 給自己一些成就感, 帶著愉快的心情去繼續你的代碼。

推薦技能: Google Java Formatter, maven-javadoc-plugin
難度系數: ★★★★★

保持良好的代碼風格永遠是一件很有意義的事情, 特別是對于一個協作團隊, 無法想象彼此混亂的代碼風格會導致多大的閱讀障礙。

現代化的集成開發環境極大地方便了我們保持整潔的代碼。如果你懶得自己去配置, 那么這里有個很好的選擇Google Java Formatter。裝上它, 這樣你的代碼永遠都是濃濃的google風了。

當然永遠記得和你的團隊保持一致的步調。

如果你的團隊有重度強迫癥, 那么像checkstyle之類的工具會比較適合。

除了代碼風格, 如果你使用Restful, 那么設計良好的Restful API也是一門必修課。這里推薦阮一峰老師的RESTful API 設計指南。

寫注釋是痛苦的, 但也是很有幫助的。你不一定需要完美地覆蓋大部分代碼, 這樣成本太高, 也沒有太大意義。

(圖: 關于代碼注釋)

PS: 這個漫畫系列真的蠻搞笑的。 傳送門

讓你的代碼無需注釋就能讓人一眼看出作用。這需要你在編碼時注意良好的命名和設計。

比如你需要一個定時器時間參數的方法, 如果參數名為time, 那么調用者會疑惑應該傳毫秒還是秒? 這時候不妨設計成timeInSeconds或者干脆拆成time+timeUnit。

比如你的實現類需要帶額外的配置項, 想想一下如果其結構是個Map, 那會是多糟糕的決定, 它會讓使用者感到迷茫。這時候你可以動手定義一個專有的配置對象, 或者初始化過程改造為Builder等等。

總之時刻想著以后會維護你代碼的那些兄弟, 還有, 未來的你。

比如對外暴露的接口, 工具類等等。因為經常會被別人調用。在這些地方寫明詳細的用法, 讓你的小伙伴們愉快地調用吧。

你可以無視大部分代碼注釋, 因為80%的代碼都是可以在幾分鐘內被人讀懂的。只有剩下的少數重要的或者太過復雜晦澀難懂的部分, 一定要描述一下。

如果你的注釋會被構建工具識別, 并且可以做一些自動化文檔生成的事, 那請一定注意在這些地方適當加上注釋。配置這些小工具很簡單, 如配置下maven-javadoc-plugin即可生成大量的javadoc。甚至你還可以幫你自動fix一些注釋, 何樂而不為呢?

推薦技能: Postman
難度系數: ★☆☆☆☆

當你終于初步寫完了你的代碼, 你的微服務終于可以運行起來了。但你沒有富余的時間認真寫API手冊, 你該如何讓團隊的同事對你的API接口有個大致的了解呢?

如果你使用的是二進制的協議, 像thrift和protobuf這種, 那么沒有什么特別好的辦法, 建議在DSL描述文件里帶上大量注釋, 因為一切都是基于這些定義文件。

如果你使用了主流的REST, 那么恭喜你, 繁榮的生態擁有大量的工具來幫你完成這些工作。

比較入門級的, 你有Postman或者Paw(收費)之類的工具可以幫你調試, 這些工具同時也具備分享功能, 你可以共享給前端, 測試組的同事們。

(圖: Postman一覽)

如果團隊比較龐大, 你可能需要在confluence上專門開辟個頁面了。

或者使用一個專門的API工具, 像筆者所在的團隊使用的RAP, 除了基本的共享, 還可以額外做一些高級的事情。

(圖: RAP一覽)

推薦技能: Swagger
難度系數: ★★☆☆☆

終于歷經測試摧殘, 各種bugfix, 你的微服務終于可以公開部署發布了。在欣喜之余, 聰明的你肯定想到需要某種方法來優雅地表達你的API。

Bingo! 挑選一個合適的工具動起手來! 比如鼎鼎大名的Swagger, 只要會一些基本的yaml, 很快就能通過它來描繪你的API。

(圖: Swagger編輯器)

于是你很快有了一個swagger文件, 通過它來生成一些UI, 或者干一些其他的事情都是極好的。

納尼?! 你覺得寫yaml太繁瑣了你不喜歡???

我們還有RAML或者api blueprint等等一大堆工具呢。

納尼?! 沒有GUI你還是覺得無法接受???

好吧, 那么筆者推薦類似apimatic這類更友好的工具, 你可以導入導出其他格式, 也可以使用其GUI來撰寫。這下舒心了吧?

(圖: apimatic編輯器一覽)

通過這些工具, 自動生成文檔HTML供大家使用的時候查詢, 一切都是這么愜意。

筆者目前的習慣是

使用apimatic撰寫API

導出為apiblueprint

使用aglio生成文檔HTML

(圖: 最終效果)

最后, 祝各位看官能把自己手下的微服務文檔寫得精彩絕倫! 筆者能力有限, 如果大家有窩藏的好工具、好方法, 也希望分享出來哦 :-D

作者信息
本文系力譜宿云LeapCloud旗下MaxLeap團隊_數據分析組成員：蔡偉偉 【原創】
蔡偉偉，本科畢業于同濟大學，從事Java開發多年，后端碼農一枚。先后從事ETL、AdHoc報表、垂直爬蟲、App制作云服務、動態用戶分群等產品的設計研發工作。在互聯網領域混跡多年，各方面均有所涉獵。現任MaxLeap數據分析組開發人員，負責Hadoop、Spark相關的分析系統架構設計與開發。

相關文章
微服務實戰：從架構到發布（一）
微服務實戰：從架構到發布（二）
移動云平臺的基礎架構之旅（一）：云應用
從應用到平臺 – 云服務架構的演進過程

作者往期佳作
一個JAVA碼農的Node之旅
飛馳在Mesos的渦輪引擎上

歡迎關注公眾號：MaxLeap_yidongyanfa