分布式接口文档聚合,Solon 是怎么做的?

1、分布式接口文档聚合,是什么?

如果你有 "22" 个不同的服务(比如微服务),每个服务都有自己的接口文档。每个服务的文档各自打开,估计你会觉得很麻烦的?

再如果,它们是用 openapi 规范的。现在,可以通过一个服务去聚合它们。就是,在一个地址里,打开 "22" 个服务的接口文档。

2、认识 Solon-Docs

solon-docs,是 solon 的接口文档解决方案。它通过 DocDocket 申明文档摘要。支持 swagger 注解,或者 javadoc 注释,或者别的(可适配)。

从文档网关的角度(此文讲聚合嘛),只需使用 groupName, basicAuth, upstream 三个配置项,就可以接入外部服务的接口文档:

java 复制代码
@Configuration
public class DocConfig {
    @Bean("appApi")
    public DocDocket appApi() {
        return new DocDocket()
                .groupName("app端接口")
                .version("2.0") //可选,默认是 2.0
                .basicAuth("admin", "1234") //可选(添加 basic auth 验证)
                .upstream("http://demo.com.cn", "/demo", "swagger/v2?group=appApi");
    }
}

upstream 配置值,切不要连接自己(否则,可能会死循环),其属性有:

属性 说明
service 目标服务名
contextPath 服务上下文路径(在网关处,方便识别是哪个服务的,进而调用)
uri 接口文档地址

solon-docs 也可以通过 solon.docs 配置,完成 DocDocket 自动构建。

3、了解 solon.docs 配置格式自动构建

使用 solon.docs 配置,可以替代 solon bean 的构建方式。格式如下

yml 复制代码
solon.docs:
  discover:
    uriPattern: "swagger/v2?group={service}"  #目标服务的文档接口路径模式(要么带变量 {service},要么用统一固定值)
    syncStatus: false  #同步目标服务上下线状态(如果下线,则文档不显示)
    basicAuth:           #可选
      admin: 1234      
    excluded:  #排除目标服务名
      - "xx"
    included:  #包括目标服务名
      - "yy"
  routes:
     name1: DocDocket
     name2: DocDocket

discover 配置项是专为聚合便利设计的,方便通过注册与发现服务聚合文档。格式说明:

配置名 说明
discover 用于配置分布式发现服务相关的(即,自动配置文档)
discover.uriPattern 目标服务的文档接口路径模式,支持{service}占位符
discover.syncStatus 同步目标服务上下线状态
discover.basicAuth 添加 basic auth 验证(同时会传递给目标服务的文档摘要)
discover.excluded 排除目标服务名
discover.included 包括目标服务名
routes 是一个 Map<String, DocDocket> 结构,用于配置文档路由(即,手动配置文档)

discover 配置,会自动生成服务相关的 DocDocket 及对应的 upstream,其中服务名会成为 upstream.service 和 upstream.contextPath,uriPattern 会生成 upstream.uri。

  • discover,只会发现有请求到的服务(即,LoadBalance.get(name) 触发到的服务)
  • 没有触发到的服务,可以通过 "included" 进行配置

4、聚合示例

(1)模块服务 app-api (当它是 22 个服务中的某个了)
yaml 复制代码
solon.app:
  namespace: test
  group: demo
  name: app-api
    
solon.cloud.nacos:
  server: "127.0.0.1:8848"   #nacos服务地址

solon.docs: #配置本地文档接口服务
  routes:
     default:  #使用固定文档组名(更方便聚合)
       groupName: "app端接口"
       apis: 
         - basePackage: "com.demo.controller.app"
(2)文档网关服务 doc-gateway (有两种配置方式)

使用发现服务配置(这个简单,可自动和批量)

yml 复制代码
solon.app:
  namespace: test
  group: demo
  name: doc-gateway
    
solon.cloud.nacos:
  server: "127.0.0.1:8848"   #nacos服务地址
  
solon.docs:
  discover:
     uriPattern: "swagger/v2?group=default"
     included: 
       - "app-api" #具体的功能服务名

或者,手动本置(routes, discover 配置,也可以同时使用)

yml 复制代码
solon.app:
  namespace: test
  group: demo
  name: doc-gateway
    
solon.cloud.nacos:
  server: "127.0.0.1:8848"   #nacos服务地址
  
solon.docs:
  routes:
     appApi:                 # doc group-id
       groupName: "app端接口" # doc group-name
       upstream: 
         service: "app-api"  #使用具体地址,或使用服务名
         contextPath: "/app-api" #可选(没有时,根据 service 自动生成)
         uri: "swagger/v2?group=default"

更多内容,可参考 Solon 官网。

相关推荐
圈圈编码11 分钟前
Spring Task 定时任务
java·前端·spring
俏布斯24 分钟前
算法日常记录
java·算法·leetcode
276695829228 分钟前
美团民宿 mtgsig 小程序 mtgsig1.2 分析
java·python·小程序·美团·mtgsig·mtgsig1.2·美团民宿
爱的叹息29 分钟前
Java 连接 Redis 的驱动(Jedis、Lettuce、Redisson、Spring Data Redis)分类及对比
java·redis·spring
程序猿chen39 分钟前
《JVM考古现场(十五):熵火燎原——从量子递归到热寂晶壁的代码涅槃》
java·jvm·git·后端·java-ee·区块链·量子计算
浩浩kids1 小时前
Hadoop•踩过的SHIT
大数据·hadoop·分布式
松韬1 小时前
Spring + Redisson:从 0 到 1 搭建高可用分布式缓存系统
java·redis·分布式·spring·缓存
绝顶少年1 小时前
Spring Boot 注解:深度解析与应用场景
java·spring boot·后端
心灵宝贝1 小时前
Tomcat 部署 Jenkins.war 详细教程(含常见问题解决)
java·tomcat·jenkins
天上掉下来个程小白2 小时前
Redis-14.在Java中操作Redis-Spring Data Redis使用方式-操作列表类型的数据
java·redis·spring·springboot·苍穹外卖