基于 Kotlin 和 Vert.x 的后端快速开发框架

我在 GitHub 上有一个开源项目: https://github.com/LoveInShenZhen/sz-vertx-kotlin

这个项目是采用 Kotlin 语言, 在 Vert.x 基础上, 专注于后端 api 接口的快速开发框架.

框架介绍: http://loveinshenzhen.github.io/#/sz_framework/introduction

希望对使用 kotlin 进行后端开发的同学, 有兴趣可以看看文档介绍, 运行一下 sample 体验一下.

有想进行技术交流的同学, 可以加我的微信, 验证申请时请填入: kotlin

微信号: dragonsunmoon

miao666

2020-04-06 02:07:19 +08:00

世界真奇妙

sagaxu

2020-04-06 02:37:29 +08:00

解决了什么问题？比直接用 vertx 更麻烦

dragonsunmoon

2020-04-06 11:21:20 +08:00

@sagaxu vert.x 只是一套底层的工具库, 如果你直接使用 vert.x 来实现一组后端的 api 接口给前端调用, 并且提供完好的接口文档和测试页面给前端工程师, 那你还需要做很多的工作.

需要注意的是, 在前后端分离的开发模式下, 前端与后端的开发人员是否能够进行有效的分工与合作, 能否提供完备的 api 接口文档和测试页面至关重要.

人都是有惰性的, 程序员大多数都不喜欢写文档. 尤其是, 当代码发生变化的时候, 还要回头修改文档, 真是痛苦的. 而懒于实时修改接口文档, 必然导致 api 接口文档与实现的不一致, 那么前端与后端就会因此引起沟通不畅.

而这套框架, 通过引入了 @Comment 这一个注解. 该注解可用于标注在类, 字段, 方法, 方法参数上, 框架会自动生成 api 接口文档和测试页面. 代码实现与文档保证一致性.

另外, 在离职的时候, 一般公司都有个工作的交接过程, 有的公司会要求开发人员提供开发文档. 有了这套框架, 直接使用现场的文档即可, 都不需要你自己写.

sagaxu

2020-04-06 14:16:36 +08:00

@dragonsunmoon 从注释生成文档的工具已经有很多了，只侵入注释，不侵入代码和框架使用习惯。根据字段类型生成的 mockup 数据，看上去很美好，但是不带业务逻辑在里面，往往没法用，不比前端自己 mockup 的好。

工作交接的时候，使用主流框架比小众的成本要低的多，我觉得最需要文档不是接口和字段说明，那个在代码里就有，迫切需要的是自上而下的架构和设计文档。

netty 算底层库，vertx 可不是底层工具库，vertx-web 已经是全功能的 web 框架了，开发效率跟 springmvc 没有太大差别。

dragonsunmoon

2020-04-06 15:02:11 +08:00

@sagaxu api 接口, 通常需要返回一个 json 结构, 而这个 json 结构可能很复杂. 这个 json 结构,json 里每个字段也是需要在 api 接口文档里体现出来的. 如果仅仅是通过"侵入注释"的方式, 是很难实现的. 如果你知道有哪些注释文档工具, 可以根据代码, 把接口返回的 json 结构和字段说明都生成出来的, 可以告诉我. 我也可以学习和借鉴一下.

sagaxu

2020-04-06 15:14:39 +08:00

@dragonsunmoon Kotlin 官网的 API 文档就是根据注释自动生成的，Vertx 的 API 文档也是这样生成的。

阿里的 rap2 了解一下 https://github.com/thx/rap2-delos

dragonsunmoon

2020-04-06 15:43:20 +08:00

@sagaxu kotlin 官网的 api 文档只是 class/function 的接口文档. 但是, 前后端分离的开发模式, 后端需要提供给前端的接口文档, 不光包括 api 接口的参数是什么, 还要包括, 返回的 json 结构是一个什么样的树状结构的描述, 每个字段的业务含义的描述.
类似于这张图片描述的样子: http://loveinshenzhen.github.io/img/quick_start_api_doc.png

阿里的 rap2 我没有尝试过, 从它 GitHub 的 wiki 页面里:https://github.com/thx/rap2-delos/wiki/user_manual , 我猜测,他有些类似 Swagger, 需要用 yaml 或者 json 格式的文件, 描述和定义接口. 然后前后端都根据这份接口契约, 来进行开发.

可是, 一旦需要调整接口, 就得先修改接口契约, 然后再回头在后端改代码. 一旦后端代码修改了, 而契约没有修改, 就会造成自动生成的文档与后端实现不一致了.

关于 Swagger, SpringMVC 或者 Spring Boot 也提供 Springfox 这一工具,也是通过注解方式, 生成 swagger json 描述文件. 参考这篇文章里的描述: https://www.jianshu.com/p/349e130e40d5

因为要遵循 swagger 的标准, 所以提供了多个不同的注解. 对使用者来说, 使用麻烦,增加了心智负担.
我的框架只使用一种 @Comment 这一个注解. 并且作为接口返回的 json 结构, 也是通过定义类的结构来实现的.
在字段上通过注解描述其业务含义. 通过类的层次结构, 自动生成 json 的结构和文档描述.

在开发这套框架之前, 我也是有考虑过 swagger 的, 但是我发现 swagger 并不能帮我有效的节省时间(没有解决我的痛点), 所以才决定按照自己的思路做了这么一套专注于后端 http api 接口的快速开发框架.

相比 rap2 这类"开发接口管理工具", 我希望的状态是, 每当后端 api 接口实现的代码修改了, 文档就自动修改了. 保证其一致性. 无须像 rap2 一样, 还需要独立部署一套"开发接口管理工具". 每次接口变更, 还得先在这套"开发接口管理工具"上更新接口契约(配置 /描述), 再回头去修改后端的代码实现. (因为没有使用过 rap2, 我只是根据文档介绍里的了解做的判断, 如果不是这么使用的, 那就无视这段话吧)

sagaxu

2020-04-06 16:41:45 +08:00

@dragonsunmoon git 提交的 hook 通知 CI/CD 工具，CI/CD 工具从 repo 拉取代码生成相应版本的文档，整个过程都没有人工参与。

不考虑业务逻辑的前提下，从接口定义的数据结构，自动根据类型填充 mock 一个 JSON 给前端，写个 helper 就可以了，为这样的小需求改变写代码的方式，我觉得不值得。我个人觉得这类功能应该作为 CI/CD 工具的一个插件，而不是框架提供。

rap2 不但能自动生成前端的 typescript 类型定义，还能自动生成调用接口的前端代码，除了在线文档和 API 测试，也能生成离线 docx 文档。最重要的是，这样一套工具，对项目使用的框架和选型没有侵入。rap2 目前已经应用了超过 10 万个 git repo 了。

你的文档和例子我也看了，不是很明白，如何集成 vertx 的其它组件，也不知道怎么跟 springboot 整合，协程中如何处理阻塞线程的调用，不返回 JSON 返回一个文件下载时怎么处理，有多个数据库的时候如何处理。也许简单 CRUD 用用没问题，需求跟套路稍微有点不同，就很难下手了。

dragonsunmoon

2020-04-06 16:59:34 +08:00

@sagaxu 文档和例子不足,很多细节没有相应的文档进行描述, 这是目前这个开源项目面临的最大困难. 毕竟只有我一个人开发. 只有继续努力去完善他了.

不是每个公司, 都能够建立有效的 CI/CD, 建立好 devops 的流程的. 好多都只是 3 到 5 人的小公司. 我自爆是没有在腾讯,华为,阿里那样的大公司呆过. 所以我对如何做到"后端 api 快速开发"有着不同的理解. 我们就求同存异吧.

就像 rap2 和 Swagger, 有人觉得方便好用, 也有人觉得不方便,难用. 适合自己的, 才是最好的.

而我, 做这个开源项目, 是希望可以按照自己的思想, 用软件项目表达出来. 同时也希望, 让这个世界上, 对那些愿意使用 kotlin 进行后端开发的同学, 可以有多一个选择.