租户端 互联网中间件 微服务框架（TSF） 开发手册

微服务网关开发指南

最近更新时间: 2024-10-17 17:10:00

准备工作

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

注意：

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

Zuul

快速上手

使用微服务网关功能前，您需要在pom.xml中添加网关依赖项，同时在代码中使用网关开关注解。

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 类中添加注解 @EnableZuulProxy 和 SpringBootApplication：
// 下面省略了无关的代码
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管理页面将其导入网关。对应网关分组发布后，即可通过网关的 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 的泛化调用。 将 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 路径示例。