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

說起微服務(wù), 想必現(xiàn)在的技術(shù)圈內(nèi)人士個個都能談笑風(fēng)云, 娓娓道來。的確, 技術(shù)變革日新月異, 各種工具框架雨后春筍般涌現(xiàn), 現(xiàn)在我們可以輕巧便捷地根據(jù)自己的業(yè)務(wù)需求, 構(gòu)建一個個微服務(wù)。

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

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

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

推薦技能: Markdown
難度系數(shù): ★☆☆☆☆

當(dāng)Boss讓你構(gòu)建一個新項目時, 我相信你是幸運(yùn)的, 因為迎接你的是嶄新的開始, 而不是某位已經(jīng)離職的前輩留下的天書般的舊項目。

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

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

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

(圖: 良好的README樣例)

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

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

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

保持良好的代碼風(fēng)格永遠(yuǎn)是一件很有意義的事情, 特別是對于一個協(xié)作團(tuán)隊, 無法想象彼此混亂的代碼風(fēng)格會導(dǎo)致多大的閱讀障礙。

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

當(dāng)然永遠(yuǎn)記得和你的團(tuán)隊保持一致的步調(diào)。

如果你的團(tuán)隊有重度強(qiáng)迫癥, 那么像checkstyle之類的工具會比較適合。

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

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

(圖: 關(guān)于代碼注釋)

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

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

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

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

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

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

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

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

推薦技能: Postman
難度系數(shù): ★☆☆☆☆

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

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

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

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

(圖: Postman一覽)

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

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

(圖: RAP一覽)

推薦技能: Swagger
難度系數(shù): ★★☆☆☆

終于歷經(jīng)測試摧殘, 各種bugfix, 你的微服務(wù)終于可以公開部署發(fā)布了。在欣喜之余, 聰明的你肯定想到需要某種方法來優(yōu)雅地表達(dá)你的API。

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

(圖: Swagger編輯器)

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

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

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

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

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

(圖: apimatic編輯器一覽)

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

筆者目前的習(xí)慣是

使用apimatic撰寫API

導(dǎo)出為apiblueprint

使用aglio生成文檔HTML

(圖: 最終效果)

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

作者信息
本文系力譜宿云LeapCloud旗下MaxLeap團(tuán)隊_數(shù)據(jù)分析組成員：蔡偉偉 【原創(chuàng)】
蔡偉偉，本科畢業(yè)于同濟(jì)大學(xué)，從事Java開發(fā)多年，后端碼農(nóng)一枚。先后從事ETL、AdHoc報表、垂直爬蟲、App制作云服務(wù)、動態(tài)用戶分群等產(chǎn)品的設(shè)計研發(fā)工作。在互聯(lián)網(wǎng)領(lǐng)域混跡多年，各方面均有所涉獵?，F(xiàn)任MaxLeap數(shù)據(jù)分析組開發(fā)人員，負(fù)責(zé)Hadoop、Spark相關(guān)的分析系統(tǒng)架構(gòu)設(shè)計與開發(fā)。

相關(guān)文章
微服務(wù)實戰(zhàn)：從架構(gòu)到發(fā)布（一）
微服務(wù)實戰(zhàn)：從架構(gòu)到發(fā)布（二）
移動云平臺的基礎(chǔ)架構(gòu)之旅（一）：云應(yīng)用
從應(yīng)用到平臺 – 云服務(wù)架構(gòu)的演進(jìn)過程

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

歡迎關(guān)注公眾號：MaxLeap_yidongyanfa