微服务架构下的API接口驱动开发，设计和集成( 四 ) 今天谈下在微服务架构下

其次对于比较复杂的模糊查询，还涉及到排序，多条件过滤的，虽然网上也有Rest API规范来强调用Get方法如何来定义，但是我们仍然推荐还是采用POST方法通过Body传递更合适。
反之，涉及到数据新增修改等操作，再简单也不建议通过Get方法进行。
API接口的版本问题
对于API接口的版本定义，仍然推荐在IP地址或域名后先定义版本，再定义详细的对象集合和ID信息。具体如下：
GET https://{serviceRoot}/{collection}/{id}
GET
当然还有一种方法是在后面添加版本，比如:
这种方式为何不好？
即我们很难通过前面的接口定义和URL信息明确地知道究竟是消费哪个版本，而具体接口的版本信息必须动态在调用的时候参数化传递。
那么我们就很难将显性化的细粒度控制到具体的版本。特别是在接口启用大小版本的情况下，实际上大小版本已经是两个输入输出有明显差异的服务，必须单独控制。
包括用这种动态方式， API接口不同版本要注册接入到API网关本身也相当麻烦难以实现。当然如果你全部用POST方式实现接口，那么版本信息定义在路径末尾也是可以的，比如：
具体更加详细的说明可以参考微软的Rest API接口定义规范。
方法和工具选择主流的Swagger设计工具
文章插图
对于设计工具，这里只谈下Swagger设计工具，这个工具最大的好处就是只需要通过编辑器进行Rest接口设计文件的定义，然后可以自动生成测试框架，自动生成客户端和服务端多种语言下的开发框架，生成API接口设计文档，这个工具本身设计完成内容还可以导出为YAML文件或Json文件，也支撑文件导入。
在采用Swagger工具的时候，我们希望的步骤为：
首先是通过Swagger Editor进行接口文件的定义，对于接口文件本身的定义建议仍然进行分域而不是全部都定义到一个文件里面。
其次基于接口定义，通过Swagger提供的CodeGen功能来生成RestClient ，或者整个SpingBoot项目。这个生成既需要包括客户端消费框架，也需要包括服务提供端框架。类似原来基于WSDL文件，用CXF框架来生成代码框架一样。
注意网上也有Spingcloud框架来集成Swagger的文章，更多的则是对已经定义好的接口来生成API接口文档，这并不是完整的接口驱动开发。
再次，通过接口定义来自动生成Mock数据，可以通过Swagger Json文件定义格式在前端通过JS来产生mock数据，也可以搭建一个完整的Mock Server产生数据，在这个步骤完成后，前端开发人员可以开始并行开发工作。
最后， API接口文档生成， Swagger在完成了接口定义后本身就已经形成了完整的接口定义，这个定义本身可以导出为完整的Html文档，也可以自己写代码进一步自动转化为Word文档。
即基于Swagger这类工具，再加上少量的定制，基本就可以实现一个完整的接口驱动开发中所需要的所有文档，代码开发框架等。