Spring Cloud微服务接口这么多怎么调试
导读
我们知道在微服务架构下,软件系统会被拆分成很多个独立运行的服务,而这些服务间需要交互通信,就需要定义各种各样的服务接口。具体来说,在基于Spring Cloud的微服务模式中,各个微服务会基于Spring MVC的Controller定义多个该微服务需要向外部发布的接口。
根据各个微服务功能边界定义的不同,有些微服务会提供与具体业务相关的接口,如支付接口账户接口等;而有些微服务则会提供一些公共性质的服务接口,如短信接口统一认证接口之类。而这些微服务往往又是由多个不同的团队在开发维护,传统方式下服务接口的定义往往需要服务提供方提供良好的可阅读性比较高的接口文档才可以比较方便地对接和测试,而事实上,随着时间的推移人员的迭代更新,很多情况下这些早期的接口文档往往很快就会因为无人维护而过时,即便不过时,微服务模式下这样的方式也会因为服务接口文档太多而让开发人员显得抓狂!
那么有没有一种更便捷地方式,可以让开发接口的同时,自动就能生成与服务接口高度一致的文档来呢?答案是有的,接下来就和大家一起聊聊到底有什么样方式可以让微服务的接口管理变得更加容易些!
接口管理方式介绍
事实上,市面上已经有多种开源项目提供了这样的支持!如:SwaggerApiDocRAPDOCLeverCrapApi等,这些项目都提供了对于Api在线文档的管理功能,那么在Spring Cloud体系中哪一种方式更加适合呢?下面,我们一起来对比下这些项目的优缺点。
1. Swagger
Swagger是一款基于YAMLJSON语言的文档在线生成和代码自动生成的工具。它的优点如下:
- 它可以直接嵌入在Spring Boot项目中,通过开发时编写注释,从而自动生成接口文档,实现代码与文档的高度一致;
- 可以分析接口的结构,并且还可以通过发起请求来验证接口的正确性;
- 它提供了多种编程语言的前后端分离解决方案,支持根据定义的接口导出各种语言的服务端或客户端代码 ;
- 它还包括了Swagger Editor,这是使用yaml语言的Swagger API的编辑器,支持导出yaml和json格式的接口文件;
- 包含了Swagger UI,它可以将Swagger Editor编辑好的接口文档以html的形式展示出来;
- 免费开源,支持国际化,生态丰富社区活跃;
它的缺点是:
- 对代码有侵入性;
- 不同项目的Swagger接口文档是分离的,需要到不同的地方去找;
- Swagger UI展现出来的接口文档缺乏分类,使用体验比较差;
- 不同项目的接口文档没有权限管理,缺少Mock;
2. ApiDoc
ApiDoc是一款轻量级的类似于Swagger的在线文档生成工具。其缺点也类似于Swagger,接口管理自动测试等功能也比较弱,并且其社区生态国际化方面都还不如Swagger。
3. RAP
RAP是一个可视化接口管理工具,它可以通过分析接口结构,动态生成模拟数据,校验真实接口正确性,围绕接口定义,通过一系列自动化工具提升微服务模式下的协作效率。
它的优点如下:
- 支持项目管理团队管理文档版本管理;
- 支持Mock测试数据;
- 阿里大厂出品,在阿里巴巴内部得到实践;
- 支持接口检索;
- 可以分析接口结构,发起请求校验接口的正确性;
- 免费开源
缺点如下:
- 文档和接口分离,很容易出现不一致的现象;
- 每个接口都需要手工编辑;
- 后端采用nodejs编写,与基于Java的Spring Cloud技术栈不一致;
4. DOCLever
DOCLever也是一个免费开源的接口管理工具,它的优点如下:
- 支持项目管理团队管理文档工具丰富;
- 支持丰富的Mock测试数据;
- 用户案例也比较丰富:滴滴美团58同城同城旅游等;
- 支持接口检索;
- 可以分析接口的结构发起请求校验接口正确性参数也很丰富;
- 支持复杂场景的自动化测试,比如获取验证码登陆,获取订单列表,甚至获取某个特定订单详情等上下文关联的操作;
缺点如下:
- 文档和接口分离,很容易出现不一致的现象;
- 每个接口都需要手工编辑;
- 后端也是采用nodejs编写,与Spring Cloud的Java技术栈不符;
5. CrapApi
优点如下:
- 支持项目管理团队管理文档版本管理;
- 支持Mock测试数据;
- 支持接口检索;
- 可以分析接口结构发起请求校验接口的正确性;
- 支持接口监控设置报警规则,接口不可用时及时通知服务负责人;
- 后端基于Java开发,与Spring Cloud技术栈Java匹配;
- 免费开源;
缺点:
- 文档和接口分离,很容易出现不一致的现象;
- 每个接口都需要手工编辑;
- 使用案例较少,功能不够完善,可能会有很多坑;
6. Spring Cloud集成Swagger
通过对上述开源项目的分析,除Swagger外其余项目采取的都是文档和代码分离的方式,虽然这样会减少对代码的侵入,但是也会造成文档和代码的不一致现象,所以在基于Spring Cloud的微服务项目中,我们选择Swagger作为微服务接口管理工具。
那么基于Spring Boot的Spring Cloud微服务该如何集成Swagger呢?
①. 在Spring Boot微服务项目中引入Maven依赖:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency>
②. 创建Swagger2配置类:
@Configuration @EnableSwagger2 @Profile("!production") public class SwaggerConfiguration { @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .groupName("Api") .select() .apis(withClassAnnotation(RestController.class)) .build() .globalOperationParameters(commonParameters()) .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Api") .version("1.0.0-SNAPSHOT") .build(); } private List<Parameter> commonParameters() { List<Parameter> parameters = Lists.newArrayList(); parameters.add(new ParameterBuilder() .name("war") .description("backdoor 在测试环境绕过鉴权") .modelRef(new ModelRef("string")) .parameterType("query") .required(false) .defaultValue("war123") .build()); parameters.add(new ParameterBuilder() .name("uid") .description("backdoor 设定的用户ID") .modelRef(new ModelRef("string")) .parameterType("query") .required(false) .defaultValue("1000053") .build()); parameters.add(new ParameterBuilder() .name("Authorization") .description("生产环境中,需要传递的用户当前 Token") .modelRef(new ModelRef("string")) .parameterType("header") .required(false) .defaultValue("Bearer XXXXX") .build()); return parameters; } }
以上配置类中,我们可以通过@Profile("!production")注解指定生效的环境,如这里我们设置除在生产环境外,其他环境都生效。
③. 添加文档内容
在完成上述配置后,其实已经可以生产文档内容了,但是这样的文档主要针对请求本身,描述的主要来源是函数的命名,多用户并不友好,为了让文档更加易于阅读和理解,我们可以通过Swagger注解来增加一些说明。这些注解主要有:
- @Api:用在类上,说明该类的作用。
- @ApiOperation:注解来给API增加方法说明。
- @ApiImplicitParams : 用在方法上包含一组参数说明。
- @ApiImplicitParam:用来注解来给方法入参增加说明。
- @ApiResponses:用于表示一组响应。
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息。
- @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)。
接下来,我们通过一个实际的微服务接口定义案例来演示下:

@Api(value = "运维端系统用户层外部接口", description = "用于组装直接面向运维App端相关服务")
以上我们在微服务下定义了一个用户注册接口,此时启动微服务,然后输入微服务的IP+端口+/swagger-ui.html,就可以看到Swagger-UI了,如下:

通过Swagger-UI我们就可以校验的方式测试接口了,同时因为接口字段都在UI有说明和暂时,并且是与实际代码完全一致的,所以在对接时基于这些接口定义进行对接就可以了!
————END————
Spring Cloud微服务接口这么多怎么调试的更多相关文章
- 【多线程】java多线程Completablefuture 详解【在spring cloud微服务之间调用,防止接口超时的应用】【未完成】
参考地址:https://www.jianshu.com/p/6f3ee90ab7d3 示例: public static void main(String[] args) throws Interr ...
- Spring Cloud微服务系列文,服务调用框架Feign
之前博文的案例中,我们是通过RestTemplate来调用服务,而Feign框架则在此基础上做了一层封装,比如,可以通过注解等方式来绑定参数,或者以声明的方式来指定请求返回类型是JSON. 这种 ...
- Spring Cloud 微服务
https://mp.weixin.qq.com/s?__biz=MzU0OTE4MzYzMw==&mid=2247486301&idx=2&sn=f6d45860269b61 ...
- 一张图了解Spring Cloud微服务架构
Spring Cloud作为当下主流的微服务框架,可以让我们更简单快捷地实现微服务架构.Spring Cloud并没有重复制造轮子,它只是将目前各家公司开发的比较成熟.经得起实际考验的服务框架组合起来 ...
- Spring Cloud微服务中网关服务是如何实现的?(Zuul篇)
导读 我们知道在基于Spring Cloud的微服务体系中,各个微服务除了在内部提供服务外,有些服务接口还需要直接提供给客户端,如Andirod.IOS.H5等等. 而一个很尴尬的境地是,如果直接将提 ...
- Dubbo和Spring Cloud微服务架构比较
Dubbo 出生于阿里系,是阿里巴巴服务化治理的核心框架,并被广泛应用于中国各互联网公司:只需要通过 Spring 配置的方式即可完成服务化,对于应用无入侵,设计的目的还是服务于自身的业务为主. 微服 ...
- 在阿里云容器服务上开发基于Docker的Spring Cloud微服务应用
本文为阿里云容器服务Spring Cloud应用开发系列文章的第一篇. 一.在阿里云容器服务上开发Spring Cloud微服务应用(本文) 二.部署Spring Cloud应用示例 三.服务发现 四 ...
- Dubbo 和 Spring Cloud微服务架构 比较及相关差异
你真的了解微服务架构吗?听听八年阿里架构师怎样讲述Dubbo和Spring Cloud微服务架构. 微服务架构是互联网很热门的话题,是互联网技术发展的必然结果.它提倡将单一应用程序划分成一组小的服务, ...
- 全链路实践Spring Cloud 微服务架构
Spring Cloud 微服务架构全链路实践Spring Cloud 微服务架构全链路实践 阅读目录: 网关请求流程 Eureka 服务治理 Config 配置中心 Hystrix 监控 服务调用链 ...
随机推荐
- 工具资源系列之给 windows 虚拟机装个 mac
众说周知,Mac 很好但也很贵,对一般大众而言,漂亮简洁高颜值,对软件开发者而言,方便省心有点贵. 好到什么程度? 内置大量常用的开发工具,省去了初学者安装配置环境的麻烦,版本控制工具 svn 默认已 ...
- XAML与C#与WPF三者到底有什么关系?
XAML是.NET体系开发程序或者网页时前台编程的一种布局方式或者说开发语言,可以比较自由的用标签的方式进行布局,借鉴了HTML和XML等语言的风格,并且加入了一些动画等的实现.C#则是后台逻辑开发用 ...
- ZigBee按键查询实践
按键查询 即硬件上电后,程序开始运行,当检测到按键按下,触发按键语句,执行按键触发的事件: 玩单片机需要清楚两件东西,第一个是单片机的电路图,另一个则是单片机的寄存器: CC2530是51的升级版,我 ...
- 基于缓存或zookeeper的分布式锁实现
缓存锁 我们常常将缓存作为分布式锁的解决方案,但是却不能单纯的判断某个 key 是否存在 来作为锁的获得依据,因为无论是 exists 和 get 命名都不是线程安全的,都无法保证只有一个线程可以获 ...
- 微信小程序 键盘显示短信验证码
1.场景描述: IOS系统 一些APP或者微信小程序在收到短信验证码的时候会在键盘上自动保存验证码信息,当用户点击的时候,会自动赋值到当前所点击的输入框中 2.案例: 2.实现: TIPS:这个功能是 ...
- 聊聊Java String.intern 背后你不知道的知识
Java的 String类有个有意思的public方法: public String intern() 返回标准表示的字符串对象.String类维护私有字符串池. 调用此方法时,如果字符串池已经包含等 ...
- P2344 奶牛抗议 离散化+前缀和+动态规划+树状数组
[题目背景] Generic Cow Protests, 2011 Feb [题目描述] 约翰家的N 头奶牛正在排队游行抗议.一些奶牛情绪激动,约翰测算下来,排在第i 位的奶牛的理智度为Ai,数字可正 ...
- 20131214-HTML基础-第二十一天
[1]表单练习 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www ...
- 爬虫之突破xm-sign校验反爬
喜马拉雅 网页分析 - 打开我们要爬取的音乐专辑https://www.ximalaya.com/ertong/424529/ - F12打开开发者工具 - 点击XHR 随便点击一首歌曲会看到存储所有 ...
- Python教程资源
链接:https://pan.baidu.com/s/1zcCG4KJ8p4GI-x2c6PY2Ng 提取码:n2q2