程序员经验分享-hwhale

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

2023-05-16

转载自： https://blog.maxleap.cn/archives/1241


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

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

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

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

一切从README开始

推荐技能: Markdown

难度系数: ★☆☆☆☆

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


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

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

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

良好的README样例

(图: 良好的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一览

(图: Postman一览)

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

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

RAP一览

(图: RAP一览)

认真撰写你的API

推荐技能: Swagger

难度系数: ★★☆☆☆

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

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

Swagger编辑器

(图: Swagger编辑器)

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

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

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

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

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

apimatic编辑器一览

(图: apimatic编辑器一览)

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

笔者目前的习惯是

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

(图: 最终效果)

本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)

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

  • 9 个很酷的 CMD 命令

    开发者 xff08 KaiFaX xff09 面向全栈工程师的开发者 专注于前端 Java Python Go PHP的技术社区 大家好 xff0c 我是若飞 今天给大家推荐几个很酷的CMD命令 使用得当 xff0c 可以让你事半功倍 ip

  • MariaDB INSERT INTO SELECT 报错

    文章目录 1 错误描述2 原因3 例子参考文献 1 错误描述 MariaDB 10 5 9 在使用 INSERT INTO SELECT 时会报错 xff0c 错误如下 xff1a ERROR 1064 42000 You have an

  • 科班程序员逆袭为渗透测试工程师的坎坷路（第一篇）

    渗透测试工程师 1 什么是渗透测试 渗透测试 xff08 penetration test xff09 事实上并没有一个标准的定义 xff0c 在国外的大部分安全组织达成的统一说法是 xff1a 渗透测试是通过模拟恶意黑客的攻击方法 xff

  • XD基础操作演示

    基础操作演示 1 启动页面 xff0c 页面上展示了几种画板类型 xff0c 根据项目类型选择相应的画板 xff0c 或者自定义画板大小 在XD中是使用一倍图进行设计 xff0c 由于XD是矢量设计软件 xff0c 所以导出 64 2x 6

  • SQL中的注释语句（三种注释）

    一 单行注释 采用 34 34 双减号 进行单行注释 xff0c 注意 xff1a 34 34 与注释内容要用空格隔开才会生效 二 多行注释 采用 进行多行注释 三 xff0c xff08 单行 xff09 注释 在mysql数据库中就可使

  • Python内置库——http.client源码刨析

    看过了http client的文档 xff0c 趁热打铁 xff0c 今天继续研究一下http client的源码 xff08 一 xff09 你会怎么实现 开始之前先让我们回忆一下一个HTTP调用的完整流程 xff1a 看到这张图 xff

  • 端到端 个人理解

    什么是端到端 端到端是根据客户端提出的需求端 xff0c 到满足客户需求端的一个过程 xff0c 这个过程叫做端到端服务 举个栗子 xff1a 客户可以看做市场 xff0c 客户提出的需求可以看做输入端 xff0c 而我们满足客户需求的结果

  • @PathVariable注解的作用

    1 64 PathVariable注解的作用 在SpringMVC中可以使用占位符进行参数绑定 xff0c 地址 list 1 3可以写成 list page limit xff0c 占位符 page 和 limit 对应的值就是1和3 在

  • ssm配置

    web xml lt context param gt lt param name gt log4jConfigLocation lt param name gt lt param value gt classpath log4j prop

  • Ubuntu16.04安装hexo

    在Ubuntu16 04中安装hexo出现一系列的问题 xff0c 总结一下安装hexo的步骤 首先安装noejs xff0c Ubuntu源中的nodejs时旧版本 xff0c 所以需要在安装后更新nodejs span class hl

  • Power Manager之DisplayPowerState.PhotonicModulator

    Android4 4 DisplayPowerState java PhotonicModulator PhotonicModulator是DisplayPowerState的内部类 xff0c private final class xf

  • AB升级之odex文件首次开机处理

    开启AB升级方案的项目 xff0c 因为很多需要升级的镜像都有两份 xff0c 所以存储空间比较浪费 为缓解此问题 xff0c 有个针对odex的优化方案 编译版本会生成两个system镜像 xff1a system img和system

  • 使用PyQt5/PySide2编写一个极简的音乐播放器

    文章目录 一 创建UI界面二 获取网络歌曲三 创建和链接信号槽 疫情肆虐 xff0c 憋在家实在无聊 xff0c 索性写点东西 xff0c 于是就有了这个极极极极极简的音乐播放器 这个极极极简的音乐播放器类似于 阅后即焚 的软件 xff0c

  • linux中最常用的用户、组和权限

    资源分派 xff1a Authentication xff1a 认证 Authorization xff1a 授权 Accouting Audition xff1a 审计 用户user 令牌token identity Linux用户 xf

  • Ansible的playbook

    playbook还是感觉学的不扎实 xff0c 可能得再来一遍才能写出来 xff0c 先占个位置 xff0c 过几天再补充 xff01

  • DNS相关介绍

    1 名字解析介绍和DNS 1 1 背景 当前TCP IP网络中的设备之间进行通信 xff0c 是利用和依赖于IP地址实现的 但数字形式的IP地址是很难记忆的 当网络设备众多 xff0c 想要记住每个设备的IP地址 xff0c 可以说是 不可

  • 关于ubuntu22.04的安装分区时需要注意的情况

    不同于20 04版本 xff0c 可以按照如下安装 如果是ubuntu 22 04 xff0c 则必须安装efi https blog csdn net janeqi1987 article details 106172976 https

  • 系统日志管理

    1 系统日志管理 1 系统日志介绍 将系统和应用发生的事件记录至日志中 xff0c 以助于排错和分析使用 日志记录的内容包括 xff1a 历史事件 xff1a 时间 xff0c 地点 xff0c 人物 xff0c 事件 日志级别 xff1a

  • python——实现名片管理器

    39 39 39 16 编写程序 xff0c 完成 名片管理器 项目 需要完成的基本功能 xff1a 添加名片 删除名片 修改名片 查询名片 退出系统 程序运行后 xff0c 除非选择退出系统 xff0c 否则重复执行功能 名片 xff1a

  • python——实现五子棋

    39 39 39 五子棋 矩阵做棋盘 16 16 34 43 34 打印棋盘 for for 游戏是否结束 开始下棋 while True 游戏是否结束 xff1a 黑白交替 player 61 0 p 2 61 61 0 61 61 1

随机推荐

  • python面向对象——烤土豆，开枪案例

    烤土豆应用 xff1a 示例属性如下 cookedLevel 这是数字 xff1b 0 3表示还是生的 xff0c 超过3表示半生不熟 xff0c 超过5表示已 经烤好了 xff0c 超过8表示已经烤成木炭了 xff01 我们的地瓜开始时时

  • linux 如何查看端口被哪个进程占用？

    1 lsof i 端口号 2 netstat tunlp grep 端口号 都可以查看指定端口被哪个进程占用的情况 步骤一 lsof i lsof i 用以显示符合条件的进程情况 lsof xff08 list open files 是一个

  • 学习Hadoop——Zookeeper 介绍

    Zookeeper 是一个开源的分布应用程序协调服务 xff0c 来自于Google 一个开源的实现 xff0c 是Hadoop 和HBase 的重要组件 Zookeeper 可以为分布式应用提供一致性服务 xff0c 功能包括 xff1a

  • 数据库中的CAP原理

    去年在参加盒子科技秋招笔试题中遇到过 xff0c 印象深刻 xff0c 一直想要查资料总结下来 这个理论是由美国著名科学家 xff0c 同时也是著名互联网企业Inktomi的创始人Eric Brewer在2000年PODC Symposiu

  • downloadingSpring（Failed to download）下载失败的解决办法

    如下图所示报错 解决办法 点击Set up HTTP proxy settings 点击后 xff0c 在第二项添加华为Maven仓库https mirrors huaweicloud com repository maven 点击Try

  • 如何将本地文件复制到远程服务器

    首先 xff0c 点击windows开始按钮 xff0c 点击运行 xff08 windows 7系统请按windows快捷键 43 R xff09 xff0c 输入mstsc xff0c 点击确定 在弹出来的对话框中 xff0c 输入服务

  • 用xstart远程连接linux图形用户界面

    有时工作中 xff0c 我们需要用到linux图形用户界面环境进行一些操作 xff08 比如装oracle数据库等等 xff09 xff0c 这时就需要用xstart远程连接linux图形用户界面 xff0c 这样我们就不用特意跑到机房操作

  • SpringDataJpa 动态复杂查询NativeQuery

    SpringDataJpa 动态复杂查询NativeQuery emm挺长时间没更新了 xff0c 最近在忙项目 xff0c 外加搬家 后续会继续更新 遇到一个复杂的sql查询 xff0c 在不通过外键关联的情况下 xff0c 只能选择使用

  • 又见一帘幽梦

    又见一帘幽梦 最是魂断伤心处 xff0c 浮生若残梦 冷遇秋 xff0c 夕阳下 xff0c 碧野又清空 xff0c 泪眼朦胧 一帘幽梦红尘路 xff0c 爱深处 xff0c 情留驻 秋菊相思 xff0c 旭日重生 xff0c 无奈生死殊途

  • Openfeign ErrorDecoder caused java.io.IOException: stream is closed

    实现错误解码器 保留 feign 服务异常信息 xff0c 左侧是之前设计的 偶尔下游系统出现异常时 xff0c 拿到返回结果时 xff0c 居然会是stream is closed xff0c 就找了下原因 Don 39 t use an

  • 鞋厂园区--稳食生涯--2017~2018

    2017年初 进入广州的鞋类企业搞数字化新零售中台业务开发 这个地方 应该是我进入电商新零售业务的启蒙和提升之地 不但学习了线上线下的电商与门店业务 也学习了完整的一套新零售中台业务技术架构和整体的微服务演变进程 同时也应该算是收获最多朋友

  • 棉类工业园--奋斗的故事--2018~2020

    nbsp 2018年8月 进入深圳的工业园继续搞数字化新零售中台业务开发 18年初步规划设计 从0到1打造整个电商与新零售中台体系 1 用户中心 用户表 角色表 系统表 菜单表 用户角色表 角色菜单表 角色系统表 数据范围表 用户数据范围

  • 不是我写的原文

    青春的尾声悄然敲响 xff0c 我站在尽头送别剩下为数不多的光阴 婚礼上同学聚会上 xff0c 越来越多的人开始为人妻为人母 xff0c 我们在经受着一场不可逆的转变 转变以前是快乐的 xff0c 转变后也会是另一种快乐 xff0c 但是转

  • 我这是一条什么路

    首先 xff0c 我从未在这里发表博客 xff0c 有些胆战 其次 xff0c 我技术不精 xff0c Java web php Android 再次 xff0c 没有共享过源码 xff0c 倒是从不少开源代码获益 最后 xff0c 这也许

  • 在珠海的一年

    时间倒退到2013年 作为应届生 xff0c 初入职场 xff0c 来到珠海 xff0c 开始了我IT生涯的第一步 以Java初级程序员的身份 xff0c 加入一家港企 xff0c 位于珠海的香洲区唐家湾镇 xff0c 还真的是一个镇啊 一

  • Hadoop的构造模块

    Hadoop集群中运行的守护进程共有5类 xff1a NameNodeDataNodeSecondary NameNodeJobTrackerTaskTracker Hadoop集群中的机器 节点 分为2类 xff1a 主节点和从节点 xf

  • 通过yum来进行mysql的安装

    1 卸载掉原有mysql rpm qa grep mysql 这个命令就会查看该操作系统上是否已经安装了mysql数据库 rpm e mysql 普通删除模式 rpm e nodeps mysql 强力删除模式 xff0c 如果使用上面命令

  • 因为咳嗽

    看了下我曾写过的博客 xff0c 居然发现年初的时候 xff0c 原来也咳嗽的撕心裂肺一次 xff0c 而这次又发作了 xff0c 我预估这是一种很严重的肺炎 xff0c 但还没去医院检测过 xff0c 心情甚是忧伤 回头望了下自己这几年写

  • VC++ 学习笔记------Window 多线程（生产消费者模式 案例）

    理论部分参考 这篇文章讲生产 消费者模式比较详细 http ifeve com producers and consumers mode 使用VC 43 43 模式实现如 xff1a span class hljs comment 创建信号

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

    转载自 xff1a https blog maxleap cn archives 1241 说起微服务 想必现在的技术圈内人士个个都能谈笑风云 娓娓道来 的确 技术变革日新月异 各种工具框架雨后春笋般涌现 现在我们可以轻巧便捷地根据自己的业

热门标签