操作指南

API 文档

微服务网关 SDK 使用指南

最近更新时间:2021-04-30 16:03:12

准备工作

开始实践微服务网关功能前,请确保您已完成 SDK 下载

说明:

  • 从1.22.0版本开始,TSF 微服务网关 SDK(TSF-MSGW)提供基于 Zuul 和 SCG (Spring Cloud Gateway) 两种类型的实现。
  • 从1.22.0以前版本进行升级的用户,需要注意 POM 依赖发生了调整。

Zuul

快速上手

使用微服务网关功能前,您需要在pom.xml中添加网关依赖项,同时在代码中使用网关开关注解。或参考官方 TSF Demomsgw-demo 模块来编写。

1.22.0-Series-RELEASE 以及之后版本

  1. 向工程中添加依赖。在 pom.xml 中添加以下代码:
<dependency>
<groupId>com.tencent.tsf</groupId>
<artifactId>spring-cloud-tsf-msgw-zuul</artifactId>
<version><!-- 调整为 SDK 最新版本号 --></version> 
</dependency>
  1. 向 Application 类中添加注解 @EnableZuulProxySpringBootApplication
// 下面省略了无关的代码
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.zuul.EnableZuulProxy;
@EnableZuulProxy
@SpringBootApplication
public class Application {
      public static void main(String[] args) {
              SpringApplication.run(Application.class, args);
      }
}
  1. 创建分组,导入 API。具体请参考 微服务网关分组管理

1.22.0-Edgware-RELEASE/1.22.0-Finchley-RELEASE 之前的版本

  1. 向工程中添加依赖。在 pom.xml 中添加以下代码:
<dependency>
    <groupId>com.tencent.tsf</groupId>
    <artifactId>spring-cloud-tsf-gateway</artifactId>
    <version><!-- 1.22.0 之前版本 --></version> 
</dependency>
  1. 向 Application 类中添加注解 @EnableTsfGateway
// 下面省略了无关的代码
import com.tencent.tsf.gateway.core.annotation.EnableTsfGateway;
@EnableTsfGateway
public class Application {
      public static void main(String[] args) {
              SpringApplication.run(Application.class, args);
      }
}
  1. 创建分组,导入 API。具体请参考 微服务网关分组管理

集成 TSF 其它功能

您在使用微服务网关功能的同时,还可以集成 TSF 其它功能,包括分布式配置、监控、服务治理等,您需要在 pom.xml 中添加其对应依赖项,同时在代码中启用注解,具体参考其功能接入文档。以下示例为集成所有功能:

  1. 向工程中增加依赖。在 pom.xml按顺序添加以下代码:
<dependency>
  <groupId>com.tencent.tsf</groupId>
  <artifactId>spring-cloud-tsf-msgw-zuul</artifactId>
  <version><!-- 调整为 SDK 最新版本号 --></version> 
</dependency>
<!--TSF 其它 SDK 依赖,添加到 msgw-zuul 依赖的后面-->
<dependency>
<groupId>com.tencent.tsf</groupId>
<artifactId>spring-cloud-tsf-starter</artifactId>
 <version><!-- 调整为 SDK 最新版本号 --></version> 
</dependency>
  1. 向 Application 类中增加注解 @EnableTsf
// 下面省略了无关的代码
import com.tencent.tsf.gateway.core.annotation.EnableTsfGateway;
import org.springframework.tsf.annotation.EnableTsf;
@EnableZuulProxy
@SpringBootApplication
@EnableTsf
public class Application {
      public static void main(String[] args) {
              SpringApplication.run(Application.class, args);
      }
}

自定义网关过滤器

msgw-zuul SDK 提供通过继承TsfGatewayZuulFilter(或原生ZuulFilter)的方式自定义 Filter,同时需要在类上添加@TsfGatewayFilter注解(或其它生成Bean方式)。目前 msgw-zuul 基于 zuul1 实现,其 Filter 功能和原生 ZuulFilter 保持一致。

import static org.springframework.cloud.netflix.zuul.filters.support.FilterConstants.PRE_TYPE;
import com.netflix.zuul.exception.ZuulException;
import com.tencent.tsf.gateway.core.annotation.TsfGatewayFilter;
import com.tencent.tsf.gateway.zuul1.filter.TsfGatewayZuulFilter;
@TsfGatewayFilter
public class TestFilter extends TsfGatewayZuulFilter {
   @Override
  public String filterType() {
      return PRE_TYPE;
  }
   @Override
  public int filterOrder() {
      return 100;
  }
   @Override
  public boolean shouldFilter() {
      return true;
  }
   @Override
  public Object run() throws ZuulException {
      System.out.println("hello world");
      return null;
  }
}

Dubbo 接口协议转换

从1.29.0版本开始,TSF 微服务网关 SDK 支持 Alibaba Dubbo 的泛化调用。参考 API 上报 将 Dubbo API 上报后。在微服务网关-API管理页面将其导入网关。对应网关分组发布后,即可通过网关的 HTTP 接口进行访问。

请求示例:

curl -H 'Content-Type: application/json' -X POST --data "{\"name\":\"xiaoming\"}" <ip>:<port>/<gateway-context>/<namespace-name>/personservice/findNameByPersion

其中 为网关分组的访问 Context, 是后端服务的命名空间名称, personservice 为 dubbo 服务名示例,/findNameByPersion 是 dubbo 方法的 API 路径示例。

SCG(Spring Cloud Gateway)

快速上手

使用微服务网关功能前,您需要在pom.xml中添加网关依赖项,同时在代码中使用网关开关注解。或参考官方 TSF Demo 中 msgw-demo 模块来编写。

  1. 向工程中添加依赖。在 pom.xml 中添加以下代码:
<dependency>
  <groupId>com.tencent.tsf</groupId>
  <artifactId>spring-cloud-tsf-msgw-scg</artifactId>
  <version><!-- 调整为 SDK 最新版本号 --></version> 
</dependency>
  1. 向 Application 类中添加注解 @SpringBootApplication
// 下面省略了无关的代码
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class Application {
      public static void main(String[] args) {
              SpringApplication.run(Application.class, args);
      }
}
  1. 创建分组,导入 API。具体请参考 微服务网关分组管理

集成 TSF 其它功能

您在使用微服务网关功能的同时,还可以集成 TSF 其它功能,包括分布式配置、监控、服务治理等,您需要在pom.xml中添加其对应依赖项,同时在代码中启用注解,具体参考其功能接入文档。以下示例为集成所有功能:

  1. 向工程中增加依赖。在 pom.xml按顺序添加以下代码:
<dependency>
<groupId>com.tencent.tsf</groupId>
<artifactId>spring-cloud-tsf-msgw-scg</artifactId>
<version><!-- 调整为 SDK 最新版本号 --></version>
</dependency>
<!--TSF 其它 SDK 依赖,添加到 msgw-scg 依赖的后面-->
<dependency>
<groupId>com.tencent.tsf</groupId>
<artifactId>spring-cloud-tsf-starter</artifactId>
<exclusions>
  <exclusion>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-tomcat</artifactId>
  </exclusion>
  <exclusion>
    <groupId>com.tencent.tsf</groupId>
    <artifactId>spring-cloud-tsf-swagger</artifactId>
  </exclusion>
</exclusions>
</dependency>
  1. 向 Application 类中增加注解 @EnableTsf
// 下面省略了无关的代码
import org.springframework.tsf.annotation.EnableTsf;
@SpringBootApplication
@EnableTsf
public class Application {
      public static void main(String[] args) {
              SpringApplication.run(Application.class, args);
      }
}

自定义网关过滤器

msgw-scg SDK 提供通过继承AbstractTsfGlobalFilter的方式,或通过实现原生GlobalFilter 接口的方式自定义 Filter。同时需要在类上添加@TsfGatewayFilter注解(或其它生成 Bean 方式)。AbstractTsfGlobalFilter 提供了和编写 ZuulFilter 类似的体验:

// 下面省略了无关的代码
@TsfGatewayFilter
public class TestFilter extends AbstractTsfGlobalFilter {
  @Override
  public int getOrder() {
      return 100;
  }
   @Override
  public boolean shouldFilter(ServerWebExchange exchange, GatewayFilterChain chain) {
      return true;
  }
   @Override
  public Mono<Void> doFilter(ServerWebExchange exchange, GatewayFilterChain chain) {
      System.out.println("hello world");
      return null;
  }
}

Dubbo 接口协议转换

从1.29.0版本开始,TSF 微服务网关 SDK 支持 Alibaba Dubbo 的泛化调用。参考 API 上报 将 Dubbo API 上报后。在微服务网关-API管理页面将其导入网关。对应网关分组发布后,即可通过网关的 HTTP 接口进行访问。

请求示例:

curl -H 'Content-Type: application/json' -X POST --data "{\"name\":\"xiaoming\"}" <ip>:<port>/<gateway-context>/<namespace-name>/personservice/findNameByPersion

其中 为网关分组的访问 Context, 是后端服务的命名空间名称, personservice 为 dubbo 服务名示例,/findNameByPersion 是 dubbo 方法的 API 路径示例。

目录