微服务横行的今天, 你的文档跟上节奏了么?

摘要：纳尼隔壁少林派表示自家金刚技压群雄在座各位都是。。。纳尼你觉得写太繁琐了你不喜欢我们还有或者等等一大堆工具呢。纳尼没有你还是觉得无法接受好吧那么笔者推荐类似这类更友好的工具你可以导入导出其他格式也可以使用其来撰写。

说起微服务, 想必现在的技术圈内人士个个都能谈笑风云, 娓娓道来。的确, 技术变革日新月异, 各种工具框架雨后春笋般涌现, 现在我们可以轻巧便捷地根据自己的业务需求, 构建一个个微服务。

按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