跳到主要内容

Spring Cloud Gateway网关聚合

简介

提示

1、Knife4j 在v4.0版本提供了基于Spring Cloud Gateway网关聚合文档的中间件

2、在使用该组件时,如果开发者在网关层面做了鉴权等操作,需要把Ui资源以及相关的API接口放开,否则会出现无法访问的情况,放开资源清单可以参考文档

3、实战文章请参考:Spring Cloud Gateway网关下的文档聚合?就用它了

自4.0版本后,Knife4j提供了一个针对在Spring Cloud Gateway网关进行聚合的组件,开发者可以基于此组件轻松的聚合各个子服务的OpenAPI文档

值得注意的事项:

  • 生产环境上线时,配置文件通过配置knife4j.gateway.enabled: false进行关闭,避免接口泄漏,造成安全问题
  • 支持服务发现knife4j.gateway.discover.enabled: true,该属性4.1.0后新增
  • 服务发现中注意排除网关服务

使用

Maven坐标如下:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-gateway-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>

手动配置聚合(manual)

手动配置聚合,顾名思义,开发者只需要在Spring Cloud Gateway网关的yml配置文件中进行配置即可。

application.yml配置文件中配置路由规则(该配置可以配置在Nacos配置中心中,实时生效),配置规则如下:


knife4j:
# 聚合swagger文档
gateway:
enabled: true
# 排序规则(tag/operation排序自4.2.0版本新增)
# 取值:alpha-默认排序规则,官方swagger-ui默认实现,order-Knife4j提供的增强排序规则,开发者可扩展x-order,根据数值来自定义排序
tags-sorter: order
operations-sorter: order
# 指定手动配置的模式(默认为该模式)
strategy: manual
routes:
- name: 用户服务
# 真实子服务访问url地址-提供OpenAPI的文档
url: /user-service/v2/api-docs?group=default
service-name: user-service
# 路由前缀
# 兼容OpenAPI3规范在聚合时丢失contextPath属性的异常情况,由开发者自己配置contextPath,Knife4j的前端Ui做兼容处理,与url属性独立不冲突,仅OpenAPI3规范聚合需要,OpenAPI2规范不需要设置此属性,默认为(apiPathPrefix)
context-path: /
order: 2
- name: 订单服务
url: /order-service/v2/api-docs?group=default
service-name: order-service
# 路由前缀
context-path: /
order: 3

配置属性说明:

配置属性名称类型描述默认值
knife4j.gateway.enabledboolean是否开启使用Gateway网关聚合组件false
knife4j.gateway.strategyenum聚合的策略,主要支持两种,分别是手动配置(manual)、服务发现(discover)manual
knife4j.gateway.routesarray{Router}通过路由注册文档
knife4j.gateway.routes[0].namestring界面显示分组名称null
knife4j.gateway.routes[0].urlstring文档地址子服务的Swagger资源接口地址(Swagger2默认/v2/api-docs,只需要配置group参数即可),因为是从网关层走,开发者配置时别忘记了网关前缀地址。
knife4j.gateway.routes[0].service-namestring访问服务名称null
knife4j.gateway.routes[0].orderint排序0
knife4j.gateway.routes[0].context-pathstring路由前缀,根据实际情况自行配置/

服务发现模式(discover)

如果子服务非常多的情况下,那么手动配置就会显得很累,那么可以通过服务发现的模式,自动从注册中心聚合文档,不过服务发现的模式,有一些注意事项,开发者需要注意:

注意事项
  • 子服务必须统一规范实现,统一使用OpenAPI2或者OpenAPI3的版本
  • 子服务需要提供默认default分组,该分组是服务发现模式下自动聚合的url

配置属性

在服务发现模式下的配置属性如下:

knife4j:
gateway:
# 是否开启
enabled: true
# 排序规则(tag/operation排序自4.2.0版本新增)
# 取值:alpha-默认排序规则,官方swagger-ui默认实现,order-Knife4j提供的增强排序规则,开发者可扩展x-order,根据数值来自定义排序
tags-sorter: order
operations-sorter: order
# 指定服务发现的模式聚合微服务文档,并且是默认`default`分组
strategy: discover
# 子服务存在其他分组情况,聚合其他分组,只能手动配置
routes:
- name: 用户服务-1
# 子服务存在其他分组情况,聚合其他分组
url: /user-service/v2/api-docs?group=用户服务
# 服务名称(Optional)
service-name: user-service
# 路由前缀
context-path: /
# 排序
order: 2
- name: 订单服务-2
url: /order-service/v2/api-docs?group=订单服务
service-name: order-service
# 路由前缀
context-path: /
order: 3
# 服务发现模式的配置
discover:
# 开启
enabled: true
# 指定版本号(swagger2|openapi3)
version : openapi3
# 需要排除的微服务(eg:网关服务)
excluded-services:
- gateway-service
# 如果子服务是OpenAPI3,并且有个性化配置
oas3:
url: /v3/api-docs?group=default
oauth2-redirect-url: ''
validator-url: ''
# 如何子服务是Swagger2,并且个性化配置
swagger2:
url: /v2/api-docs?group=default
# 单个服务的个性化配置,key-服务名称,value-配置信息
service-config:
# 假设order服务(具体真实服务开发者根据自己的情况配置)
order-service:
# 该服务的排序
order: 0
# 分组显示名称
group-name: 订单服务名称
# 兼容OpenAPI3规范在聚合时丢失contextPath属性的异常情况,由开发者自己配置contextPath,Knife4j的前端Ui做兼容处理,与url属性独立不冲突,仅OpenAPI3规范聚合需要,OpenAPI2规范不需要设置此属性,默认为(apiPathPrefix)
context-path: /
# 该属性自4.2.0添加,支持子服务非`default`分组的其他分组聚合
# 参考 https://gitee.com/xiaoym/knife4j/pulls/87
group-names:
- 分组1
- 分组2


排除服务

自4.2.0版本,在Spring Cloud Gateway网关聚合时,开发者可自定义排除服务的规则,实现Knife4j开放的接口即可

主要解决在Dubbo等服务的场景中聚合了不必要的服务。参考Gitee#I6YLMB

@Slf4j
@Component
public class MyExcludeService implements GatewayServiceExcludeService {
@Override
public Set<String> exclude(Environment environment, Knife4jGatewayProperties properties, List<String> services) {
log.info("自定义过滤器.");
if (!CollectionUtils.isEmpty(services)){
// 排除注册中心包含order字眼的服务
return services.stream().filter(s -> s.contains("order")).collect(Collectors.toSet());
}
return new TreeSet<>();
}
}

场景case

2.1 所有子服务全部是OpenAPI3规范

knife4j:
gateway:
enabled: true
# 指定服务发现的模式聚合微服务文档,并且是默认`default`分组
strategy: discover
discover:
enabled: true
# 指定版本号(Swagger2|OpenAPI3)
version : openapi3
# 需要排除的微服务(eg:网关服务)
excluded-services:
- gateway-service

2.2 所有子服务全部是Swagger2规范,并且是默认default分组

knife4j:
gateway:
enabled: true
# 指定服务发现的模式聚合微服务文档
strategy: discover
discover:
enabled: true
# 指定版本号(Swagger2|OpenAPI3)
version : swagger2
# 需要排除的微服务(eg:网关服务)
excluded-services:
- gateway-service

2.3 子服务中除了default分组,还有别的分组,测试,我们需要单独聚合(因为discover模式只聚合默认),此时,则复用routes自定义属性

knife4j:
gateway:
enabled: true
# 指定服务发现的模式聚合微服务文档
strategy: discover
discover:
enabled: true
# 指定版本号(Swagger2|OpenAPI3)
version : swagger2
# 需要排除的微服务(eg:网关服务)
excluded-services:
- gateway-service
# 个性化定制的部分子服务分组情况
routes:
- name: 用户服务
service-name: user-service
url: /user/v2/api-docs?group=组织管理
order: 1
- name: 订单服务
service-name: order-service
url: /order/v2/api-docs?group=订单管理
order: 1

2.4 在discover服务发现模式下,如果我们希望对聚合起来的微服务提供一些个性化配置,例如:排序、分组重命名、context-path配置等等,那么可以通过服务配置对每个服务进行配置,如下:

knife4j:
gateway:
enabled: true
# 指定服务发现的模式聚合微服务文档
strategy: discover
discover:
enabled: true
# 指定版本号(Swagger2|OpenAPI3)
version : openapi3
# 需要排除的微服务(eg:网关服务)
excluded-services:
- gateway-service
# 各个聚合服务的个性化配置,key:注册中心中的服务名称,value:个性化配置
service-config:
user-service:
# 排序
order: 1
# 前端显示名称
group-name : 用户服务
# 重新指定basePath,一般在OpenAPI3规范中需要
context-path: /user
order-service:
# 排序
order: 2
# 前端显示名称
group-name : 订单服务
# 重新指定basePath,一般在OpenAPI3规范中需要
context-path: /order

访问地址

http://{gateway.host}:{gateway.port}/doc.html