knife4j-gateway网关聚合的场景

[xiaoymin]

网关聚合的集中场景case：

1、网关项目走Nginx代理，配置前缀，聚合时需要考虑避免basePath丢失的问题，这种情况可以在网关提供的Endpoint端口进行出来，接收Request对象，并且获取当前nginx代理过来的地址，代码示例：

@GetMapping("/v3/api-docs/swagger-config")
public Mono<ResponseEntity<SwaggerV3Response>> swaggerConfig(ServerHttpRequest request) {
    String contextPath = request.getPath().contextPath().value();
    if (!StringUtils.hasLength(contextPath)) {
        contextPath = "/";
    }
}

2、网关聚合时，手动聚合的模式，手动聚合不用考虑子服务是那个OpenAPI规范(Swagger2/OAS3),只需要提供URL过来即可，配置如下：

knife4j:
  # 聚合swagger文档
  gateway:
    enable: true
    routes:
      - name: 用户服务
        # OpenAPI数据源，不管是Swagger/OAS3，提供地址即可聚合
        url: /user-service/v2/api-docs?group=default
        context-path: /abc
        service-name: user-service
        order: 2
      - name: 订单服务
        url: /order-service/v2/api-docs?group=default
        service-name: order-service
        order: 3

3、如果是通过注册中心，在Spring Cloud微服务框架下，通过服务发现的方式，自动聚合，那么需要考虑的事情：

• 聚合的服务必须保证健康(否则前端UI会显示异常)
• 排除网关自己(因为网关自己没有OpenAPI数据源URL接口)
• 各个子服务需要统一OpenAPI命名规范，避免分组的情况
• 如果有OpenAPI的分组的情况，那么需要提供解决方案
• 子服务可能出现即包含Swagger2，也包含OAS3的情况，聚合时需要兼容

[xiaoymin]

考虑到第三点的特殊性，如果是走服务发现，那么需要有特殊要求，要求如下：

1、各个子服务必须OpenAPI规范统一，要么全部是Swagger2，要么全是OAS3

2、每一个子服务提供的OpenAPI数据源URL必须固定，不能分组，全部是default默认分组

[xiaoymin]

1、针对子服务可能存在分组的情况，在服务发现中增加Routes手动配置的属性，与服务发现进行Merge操作，保证能够全部聚合所有服务文档

2、另外可能还要加一个 属性，服务业务名称映射的字典配置：

a-service : 用户服务

b-service：订单服务

类似这样，但是我觉得如果子服务太多，写这个字典配置也很麻烦，不过也避免不了了

[xiaoymin]

两种模式：

第一种模式，纯手工配置(manual)

knife4j:
    enable: true
    # 指定手动配置的模式(默认为该模式)
    strategy: manual
    routes: 
        - name: 用户服务
          url: /user/v2/api-docs?group=default
          order: 1
        - name: 订单服务
          url: /order/v2/api-docs?group=default
          order: 1

第二种模式，基于微服务自动发现(discover)，自动聚合:

针对微服务聚合，我们有非常多的case

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

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

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

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

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

knife4j:
    enable: true
    # 指定服务发现的模式聚合微服务文档
    strategy: discover
    discover：
        enable: 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:
    enable: true
    # 指定服务发现的模式聚合微服务文档
    strategy: discover
    discover：
        enable: 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

[cyourai]

您好，上面的例子是否差了一级gateway，再一个有的"：" 是中文的

[xiaoymin]

感谢指正，确实是的，这个是还没开发之前构思的，以官网文档为准

[cyourai]

收到，谢谢

[ZhouYixun]

感觉第三种自动聚合已经能满足我的需求

[xiaoymin]

感觉第三种自动聚合已经能满足我的需求

可以试用一下SNAPSHOT版本哦

[xiaoymin]

在4.1版本发布后，我发现在manual手动模式下，还缺少一个功能，就是基于服务发现，自动剔除已经下线的微服务，避免聚合失败

[xiaoymin]

看来这个只能放下个版本了

[xiaoymin]

现在这个组件其实还有两个问题，我觉得的，你们参考看看：

1、第一类问题是在手动配置的模式下，没有从注册中心拿服务，服务如果下线，目前无感知，聚合如果手动配置是第一个服务下线的话，会导致聚合失败，因为第一个下线了，这个在manual模式中，routes节点的service-name属性，目前没有利用起来

2、第二个问题就是你这种问题，但分两类来看，第一个是子服务过网关的时候，路径的规则不是：服务名称/子服务api这种形式，可能是自定义rewrite的规则，这种情况下也会导致拿不到子服务的真实访问路径前缀basePath属性。另外一类是子服务本身设置context-path，本质上和第一类是同一个问题，就是走网关的时候，每个子服务的访问前缀都是有规则的。而目前knife4j-gateway聚合组件只是单纯的用：服务名称/接口url来聚合。场景覆盖不到

现阶段,knife4j-gateway聚合组件 我觉得就是上面两个问题要解决了。其他的问题应该都没有了，场景都覆盖了

[ZhouYixun]

我这边的话侧重点在能显示文档就行

[slppls]

针对第二点，目前有计划做实现吗，目前也是碰到了这种场景，在gateway做了rewrite规则，使用了统一的网关前缀，目前聚合后，请求json内容接口时是访问不到的，因为单纯依靠网关+服务名去访问是无法通过网关这边的rewrite规则的，或者有什么其它解决方案吗？手动聚合每个服务直接写死url?

[xiaoymin]

针对第二点，目前有计划做实现吗，目前也是碰到了这种场景，在gateway做了rewrite规则，使用了统一的网关前缀，目前聚合后，请求json内容接口时是访问不到的，因为单纯依靠网关+服务名去访问是无法通过网关这边的rewrite规则的，或者有什么其它解决方案吗？手动聚合每个服务直接写死url?

下个版本会解决上面两个场景的问题，服务发现的话，通过读取Route的服务路由前缀做识别