转载

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

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

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

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

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

一切从README开始

推荐技能: 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: 这个漫画系列真的蛮搞笑的。 传送门

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 (收费)之类的工具可以帮你调试, 这些工具同时也具备分享功能, 你可以共享给前端, 测试组的同事们。

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

(图: Postman一览)

如果团队比较庞大, 你可能需要在 confluence 上专门开辟个页面了。

或者使用一个专门的API工具, 像笔者所在的团队使用的 RAP , 除了基本的共享, 还可以额外做一些高级的事情。

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

(图: RAP一览)

认真撰写你的API

推荐技能: Swagger

难度系数: ★★☆☆☆

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

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

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

(图: Swagger编辑器)

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

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

我们还有 RAML 或者 api blueprint 等等一大堆工具呢。

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

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

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

(图: apimatic编辑器一览)

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

笔者目前的习惯是

  1. 使用apimatic撰写API
  2. 导出为apiblueprint
  3. 使用 aglio 生成文档HTML

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

(图: 最终效果)

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

作者信息

本文系力谱宿云LeapCloud旗下MaxLeap团队_数据分析组成员:蔡伟伟 【原创】

– 力谱宿云LeapCloud 首发 –

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

相关文章

微服务实战:从架构到发布(一)

微服务实战:从架构到发布(二)

移动云平台的基础架构之旅(一):云应用

从应用到平台 – 云服务架构的演进过程

作者往期佳作

一个JAVA码农的Node之旅

飞驰在Mesos的涡轮引擎上

欢迎扫以下二维码,关注微信公众号:MaxLeap_yidongyanfa

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

原文  https://blog.maxleap.cn/archives/1241
正文到此结束
Loading...