swagger可能是目前开发resful API时最流行的工具集,可能很多童鞋在遇到API开发需求时,直接反应会是:“用swagger不就好了?”。
protoapi
与swagger
会有一些理念上根本性差异,为详细阐述这些差异,我们先来看看swagger
是如何发展起来的。
文档先行 vs 实现先行
swagger
最早是在2011年开源,它处理提供的是:
-
机器可读的
API JSON定义
- 它后续又发展成为OpenAPI Specification
- 基于API实现代码来生成
API JSON定义
- 基于
API JSON定义
提供web界面,以:- 方便查看API文档
- 快速测试API调用
- 基于
API JSON定义
生成客户端SDK
它核心的思路是API实现先行,即,先有服务器端的API的实现代码,然后通过静态分析这些实现代码,去生成机器可读的API JSON定义
,以及文档等等。
说白了,我们可以理解为这是服务器端开发人员,习惯于直接实现API,然后又懒得写API文档,在写实现代码的时候,顺手写一下注释,然后使用swagger
结合代码 + 注释生成出来文档。
而protoapi
强调的则是文档先行
,想要实现API的话,必须 先用protobuf
作为IDL,把API先给定义好了,IDL即文档,而且是人类可读。
protobuf
有严格的语法以及成熟的编译器,当然也是机器可读的。
swagger code-gen
文档先行
与实现先行
孰优孰劣,这几乎不需要讨论,因为swagger
后续也推出了swagger-codegen项目,提倡文档先行
,即开发API的时候,先写API JSON定义
(我们也可以认为这样的API JSON定义是IDL),然后再使用swagger-codegen
去分别生成服务器端已经客户端的SDK。
这样的做法,其实跟protoapi
的文档/IDL先行
非常类似,区别在于,swagger
使用的是类似下面的机器可读JSON格式:
人类去读机器可读的JSON格式,是很容易脑壳疼(前同事的评论)的,因此swagger
又提供了Swagger Editor这样的web编辑器。
而protoapi
选择的protobuf
则是人类可读的格式,各式文本编辑器、IDE均有其插件,可以方便的阅读、编辑:
协作的差异
IDL是否方便阅读、编辑其实还是小问题,重要的其实是对于团队协作的影响。
swagger
更多是使用在提供给第三方调用的场景,比方说github。
在这样的场景下,API提供些什么,完全是由服务器端实现者决定,他们在提供API的时候,其实也不会针对特定的业务场景,调用者会如何使用API,只有当调用者开发具体业务的时候才会知晓。
并且,是API开发完毕、发布之后,API调用者的角色才会出现。
问题是,这样的场景往往则跟公司内部项目,特别是走前后端分离
架构的项目不符。
但我们日常开发公司内部项目的时候,现实情况很可能是这样:
- web前端、客户端、后端API可能需要同时开发
- 实现的是新业务,业务从项目开始就确定
- 后端提供的是特定业务的API,而不是通用、业务中立的API
- 调用方(web前端、客户端)很可能更了解具体什么API更合适
在这样的场景下,如果我们还是走swagger
默认所提倡的实现先行
的开发模式,是非常不合适的:
- 调用方需要等待后端API开发完毕之后,才可以了解API
- 两端无法并行开发会严重拖慢项目进度
- 后端闭门造车提供的API未必最适合具体业务的需要
- 调用方难以推动API变更
- 服务器后端,顾名思义是要有服务意识的
而如果采用protoapi
这样文档/IDL先行
方案,流程很可能是:
- 调用方定义特定业务需要的API,proto文件保存在独立的代码仓库
- 后端、调用同时进行开发
- API需要变更的时候,各方均可以对保存proto文件的代码仓库发起合并请求
这里,重点是将API定义
,与API实现
、API调用
三者解耦剥离开来:
-
API定义
先行,定义者可以是API实现方,也可以是调用方,更可以是第三方 - 有各方中立的具体形式方便各方协作推动API的修改
这样的开发方式更加符合敏捷流程。
总结一下
protoapi | swagger | swagger-codegen | |
---|---|---|---|
开发流程 | 文档先行 | 实现先行 | 文档先行 |
开发模式 | 敏捷开发 | 瀑布流 | 偏瀑布流 |
API定义者 | 前后端均可 | 后端 | 后端 |
变更流程友好 | 是 | 否 | 否 |
IDL | 人类+机器可读 | 偏机器可读 | 偏机器可读 |
前端代码生成 | 有 | 有 | 有 |
后端代码生成 | 有 | 无 | 有 |
我很久之前就使用过IDL去做各式代码生成,并使用在之前公司几乎所有的项目当中,protoapi
与我而言,并不是什么新颖的概念/实现;而是成熟、经历过百项目长期考验的技术思路;相关的技术也都并不高深,属于直接了当,明显没有bug的实现。
我一直没有全面阐述过相关技术背后的理念。这次我重新整理写这系列API的文章,反响最强烈的其实是客户端、前端的多位前同事。
protoapi
所提倡的是,是敏捷、流畅互动的团队协作,而不是“我定义、你接受”这样偏单向的流程。
后面我会整理一下protoapi
的实战案例,并将项目开源,暂时只是先在github上占个坑,欢迎star:github.com/yoozoo/protoapi