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


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

按Wikipedia的解释:微服务是一种以业务功能为主的服务设计概念,每一个服务都具有自主运行的业务功能,对外开放不受语言限制的 API (最常用的是 HTTP),应用程序则是由一个或多个微服务组成。

跨语言的确是实现了,但这仅是从编程语言的维度来定义。人与人之间的跨越可就没这么方便喽,你华山派门下有独门的Restful调用,我武当派一向Thrift一招走天下。 纳尼!隔壁少林派表示自家金刚Protobuf技压群雄,在座各位都是……

别闹了,如果大家都把自己的武林秘籍写得通俗易懂,岂不是人人皆可练百家武学?

一切从README开始

>推荐技能:Markdown
难度系数:★☆☆☆☆

当Boss让你构建一个新项目时,我相信你是幸运的,因为迎接你的是崭新的开始,而不是某位已经离职的前辈留下的天书般的旧项目。

如果你的直觉认同我上述观点,那么我相信你肯定珍惜这一次编码机会,于是你开始使用你熟悉的脚手架工具在GitLab上构建你的空白工程。

什么?!这就完了?不不不,在这之后,先别猴急着开始写代码,放松下,让我们touch一个README,想象一下你的项目架构应该是怎样的,大致提供些什么功能,供别人调用的入口代码应该设计成什么样,你的项目所需的技术栈有哪些,甚至能想到的Todo列表等等。

这些都可以先填补到你的README上,有余力的话甚至可以用一些原型工具(如:ProcessOnPencilCacoo)设计一些架构草图、时序图那就更好了,如果你手头的确没合适的工具,那么尝试用原始的纸笔画一下拍张照片也行。
01.png

图:良好的README样例

一个落落大方的README,方便了团队的其他成员迅速理解你的项目核心功能,让人看着就赏心悦目!

用心写好了一个README,才会感觉自己好像在写一个伟大的项目不是么?有时候你需要给自己定一个小目标,给自己一些成就感,带着愉快的心情去继续你的代码。

优雅的代码风格和注释

> 推荐技能:Google Java Formatter,maven-javadoc-plugin
难度系数:★★★★★

代码风格

保持良好的代码风格永远是一件很有意义的事情,特别是对于一个协作团队,无法想象彼此混乱的代码风格会导致多大的阅读障碍。

现代化的集成开发环境极大地方便了我们保持整洁的代码。如果你懒得自己去配置,那么这里有个很好的选择Google Java Formatter。装上它,这样你的代码永远都是浓浓的Google风了。

当然永远记得和你的团队保持一致的步调。

如果你的团队有重度强迫症,那么像CheckStyle之类的工具会比较适合。

除了代码风格,如果你使用Restful,那么设计良好的Restful API也是一门必修课。这里推荐阮一峰老师的RESTful API 设计指南

关于注释

写注释是痛苦的,但也是很有帮助的。你不一定需要完美地覆盖大部分代码,这样成本太高,也没有太大意义。
02.gif

图:关于代码注释
PS:这个漫画系列真的蛮搞笑的。 传送门

  1. 自文档

    让你的代码无需注释就能让人一眼看出作用。这需要你在编码时注意良好的命名和设计。

    比如你需要一个定时器时间参数的方法,如果参数名为time,那么调用者会疑惑应该传毫秒还是秒?这时候不妨设计成timeInSeconds或者干脆拆成time + timeUnit

    比如你的实现类需要带额外的配置项,想想一下如果其结构是个Map,那会是多糟糕的决定,它会让使用者感到迷茫。这时候你可以动手定义一个专有的配置对象,或者初始化过程改造为Builder等等。

    总之时刻想着以后会维护你代码的那些兄弟,还有,未来的你。

  2. 对外暴露的代码

    比如对外暴露的接口,工具类等等。因为经常会被别人调用。在这些地方写明详细的用法,让你的小伙伴们愉快地调用吧。

  3. 核心或者晦涩的部分

    你可以无视大部分代码注释,因为80%的代码都是可以在几分钟内被人读懂的。只有剩下的少数重要的或者太过复杂晦涩难懂的部分,一定要描述一下。

  4. 有助于文档生成

    如果你的注释会被构建工具识别,并且可以做一些自动化文档生成的事,那请一定注意在这些地方适当加上注释。配置这些小工具很简单,如配置下maven-javadoc-plugin即可生成大量的Javadoc。甚至你还可以帮你自动fix一些注释,何乐而不为呢?


共享你的成果

> 推荐技能:Postman
难度系数:★☆☆☆☆

当你终于初步写完了你的代码,你的微服务终于可以运行起来了。但你没有富余的时间认真写API手册,你该如何让团队的同事对你的API接口有个大致的了解呢?

如果你使用的是二进制的协议,像Thrift和Protobuf这种,那么没有什么特别好的办法,建议在DSL描述文件里带上大量注释,因为一切都是基于这些定义文件。

如果你使用了主流的REST,那么恭喜你,繁荣的生态拥有大量的工具来帮你完成这些工作。

比较入门级的,你有Postman或者Paw(收费)之类的工具可以帮你调试,这些工具同时也具备分享功能,你可以共享给前端,测试组的同事们。
03.png

图:Postman一览

如果团队比较庞大,你可能需要在Confluence上专门开辟个页面了。或者使用一个专门的API工具,像笔者所在的团队使用的RAP,除了基本的共享,还可以额外做一些高级的事情。
04.png

图:RAP一览

认真撰写你的API

> 推荐技能:Swagger
难度系数:★★☆☆☆

终于历经测试摧残,各种bugfix,你的微服务终于可以公开部署发布了。在欣喜之余,聪明的你肯定想到需要某种方法来优雅地表达你的API。

Bingo! 挑选一个合适的工具动起手来! 比如鼎鼎大名的Swagger,只要会一些基本的yaml,很快就能通过它来描绘你的API。
05.png

图:Swagger编辑器

于是你很快有了一个Swagger文件,通过它来生成一些UI,或者干一些其他的事情都是极好的。

纳尼?!你觉得写yaml太繁琐了你不喜欢???

我们还有RAML或者API Blueprint等等一大堆工具呢。

纳尼?!没有GUI你还是觉得无法接受???

好吧,那么笔者推荐类似APIMATIC这类更友好的工具,你可以导入导出其他格式,也可以使用其GUI来撰写。这下舒心了吧?
06.png

图:APIMATIC编辑器一览

通过这些工具,自动生成文档HTML供大家使用的时候查询,一切都是这么惬意。

笔者目前的习惯是:
  1. 使用APIMATIC撰写API
  2. 导出为API Blueprint
  3. 使用aglio生成文档HTML


07.png

图:最终效果

最后,祝各位看官能把自己手下的微服务文档写得精彩绝伦!笔者能力有限,如果大家有窝藏的好工具、好方法,也希望分享出来哦

作者信息

本文系力谱宿云LeapCloud旗下MaxLeap团队_数据分析组成员:蔡伟伟 ,本科毕业于同济大学,从事Java开发多年,后端码农一枚。先后从事ETL、AdHoc报表、垂直爬虫、App制作云服务、动态用户分群等产品的设计研发工作。在互联网领域混迹多年,各方面均有所涉猎。现任MaxLeap数据分析组开发人员,负责Hadoop、Spark相关的分析系统架构设计与开发。

原文链接

1 个评论

好东西~

要回复文章请先登录注册