当前位置：首页 > news >正文

从0开始搭建微服务架构特别篇SpringCloud网关聚合knife4j

news 来源：原创 2025/5/30 0:44:30

前言：总所周知项目开发接口测试需要knife4j，但是，微服务架构中微服务很多，模块地址很多，需要统一管理api测试，就需要聚合在网关统一调用，本章，就说明如何通过网关聚合使用knife4j。
1、网关集成knife4j

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

2、网关核心配置
网关的路由配置

  id: order_route #路由的唯一标识,路由到order
          uri: lb://system-order #需要转发的地址 lb：使用nacos本地负载均衡策略
          #断言规则 用于路由规则匹配
          predicates:
            - Path=/order/**
          filters:
            - StripPrefix=1#这里的意思是去掉路径第一个

注意了：StripPrefix=1非常重要，不然链接会多一个order会报404错

以下网关的knife4j配置

 # knife4j的网关聚合配置 文档地址：http://{gateway.host}:{gateway.port}/doc.html
# 聚合swagger文档
knife4j:
  gateway:
    # 是否开启Knife4j网关聚合功能(生产环境不建议开启)
    enabled: true
    # 排序规则(tag/operation排序自4.2.0版本新增)
    # 取值：alpha-默认排序规则，官方swagger-ui默认实现,order-Knife4j提供的增强排序规则，开发者可扩展x-order，根据数值来自定义排序
    tags-sorter: order
    operations-sorter: order
    # 指定聚合的策略(默认手动配置(manual)，服务发现(discover))
    strategy: manual
    # 个性化定制的部分子服务分组情况
    routes:
      - name: order模块
        # 服务名
        service-name: system-order
        # 真实子服务访问url地址-提供OpenAPI的文档
        url:/order/v3/api-docs?group=default
        # 路由前缀，兼容OpenAPI3规范在聚合时丢失contextPath属性的异常情况，由开发者自己配置contextPath,Knife4j的前端Ui做兼容处理,与url属性独立不冲突，仅OpenAPI3规范聚合需要，OpenAPI2规范不需要设置此属性,默认为(apiPathPrefix)
        context-path: /order
        # 排序
        order: 1

注意了：strategy:manual是手动配置的方式。手动配置必须这加**/order**/v3/api-docs?group=default 这里的加order（我的服务路径）的目的是因为路由转发的时候，会自动加服务路径。如果，不加order会访问404错误。因为/v3/api-docs是在根目录的。

以下是自动通过服务发现来配置strategy，自动配置会自动加order

strategy: discover
    # 服务发现
discover:
      # OpenAPI 3.0 规范
      version: openapi3
      # 开启服务发现 默认:true
      enabled: true
      # 默认排序 默认:0
      default-order: 0
      # 排除的服务名 默认:为空(建议排除网关服务)
      excluded-services: ${spring.application.name}

3、微服务依赖添加

  <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.5.0</version>
        </dependency>

4、微服务yml配置

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.x'x'x.xxx.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

微服务里面不用加order
总结：路由转发，就算网关配置path /**，也会自动加order名。