微服务横行的今天, 你的文档跟上节奏了么?
说起微服务, 想必现在的技术圈内人士个个都能谈笑风云, 娓娓道来。的确, 技术变革日新月异, 各种工具框架雨后春笋般涌现, 现在我们可以轻巧便捷地根据自己的业务需求, 构建一个个微服务。
按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供大家使用的时候查询, 一切都是这么惬意。
笔者目前的习惯是
- 使用apimatic撰写API
- 导出为apiblueprint
- 使用 aglio 生成文档HTML
(图: 最终效果)
最后, 祝各位看官能把自己手下的微服务文档写得精彩绝伦! 笔者能力有限, 如果大家有窝藏的好工具、好方法, 也希望分享出来哦 :grinning:
作者信息
本文系力谱宿云LeapCloud旗下MaxLeap团队_数据分析组成员：蔡伟伟 【原创】
– 力谱宿云LeapCloud 首发 –
蔡伟伟，本科毕业于同济大学，从事Java开发多年，后端码农一枚。先后从事ETL、AdHoc报表、垂直爬虫、App制作云服务、动态用户分群等产品的设计研发工作。在互联网领域混迹多年，各方面均有所涉猎。现任MaxLeap数据分析组开发人员，负责Hadoop、Spark相关的分析系统架构设计与开发。
相关文章
微服务实战：从架构到发布（一）
微服务实战：从架构到发布（二）
移动云平台的基础架构之旅（一）：云应用
从应用到平台 – 云服务架构的演进过程
作者往期佳作
一个JAVA码农的Node之旅
飞驰在Mesos的涡轮引擎上
欢迎扫以下二维码，关注微信公众号：MaxLeap_yidongyanfa
正文到此结束
热门推荐
相关文章
近期评论
-
文章和留言都翻到11页了 没有OOM
-
-
朋友，翻页到11页，及以后，会出现OOM，无法访问
-
-
搞个gitee的项目
-
-
版本号是多少，你可以下载哪个代码仓库，jdk选1.8 直接跑就行
-
-
-
Loading...
![[HBLOG]公众号](https://www.liuhaihua.cn/img/qrcode_gzh.jpg)
