从 Zuul 迁移到 Spring Cloud Gateway：一步步实现服务网关的升级

帅帅梁2024-12-11 6:05

从 Zuul 迁移到 Spring Cloud Gateway：一步步实现服务网关的升级

公司的项目之前使用的是Zuul，然后使用的是以前传下来的jar包，JDK1.8,spring1.*，都是比较老了，然后因为这些原因，要把Zuul替换成Gateway。

本文将详细介绍如何从 Zuul 迁移到 Gateway。

迁移前的准备工作

在开始迁移之前，需要做好以下准备：

  1. 确认现有的 Zuul 配置

    收集 Zuul 的路由配置、过滤器逻辑和插件依赖。

  2. 学习 Gateway 的基本概念

    熟悉 Gateway 的核心概念，例如：

    • Route（路由）
    • Predicate（断言）
    • Filter（过滤器）

  3. 确保系统支持响应式编程模型

    检查项目中的依赖库和代码是否与 Spring WebFlux 的非阻塞模型兼容。

  4. 升级到支持 Gateway 的 Spring Boot 版本

    确保 Spring Boot 版本 >= 2.1。

迁移步骤详解

第一步：查看源码

由于项目使用的是预先打包好的 Jar 文件，源码不可直接查看，因此需要通过反编译工具提取代码。我使用的是 jd-gui 工具，界面如图所示：

从反编译的结果可以看到，代码量相对简单，主要包含两个部分：启动类和核心过滤器。相对比较容易。

第二步：启动类迁移

原 Zuul 启动类：

java 复制代码 
@EnableZuulProxy
@SpringBootApplication
public class ZuulServerApplication {
    public static void main(String[] args) {
        (new SpringApplicationBuilder(ZuulServerApplication.class))
                .web(true)
                .run(args);
    }

    @Bean
    public PathRewriteHeaderFilter customAddHeaderFilter(RouteLocator routeLocator) {
        return new PathRewriteHeaderFilter(routeLocator);
    }
}

迁移后的 Gateway 启动类：

java 复制代码 
@SpringBootApplication
@EnableDiscoveryClient
@ComponentScan(basePackages = {"com.aspire.gateway.gatewayservice"})
public class GatewayServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(GatewayServiceApplication.class, args);
    }
}
  • Spring Boot 2.x 后，@EnableZuulProxy 不再需要，Gateway 默认支持路由功能。
  • 由于项目的特殊需求，需要添加 @ComponentScan 手动指定 Bean 扫描路径，确保组件能够被正确加载。
  • 因为spring2之后的版本不需要再显示指定Gateway了，其实理论上只需要一个SpringBootApplication就够了，其他其实都不用。但是我这里不知道为啥，扫描不到我的bean，所以我就写了扫描当前启动类。@ComponentScan(basePackages = {"com.aspire.gateway.gatewayservice"})这里你可以换成自己的扫描包路径。

第三步：引入 Gateway 依赖

在 pom.xml 中移除 Zuul 相关依赖，替换为 Gateway 依赖：

以下是我使用的版本控制，就是这些版本之间是兼容的，我使用的也是这些版本。

xml 复制代码 
<properties>
        <java.version>17</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <spring-cloud.version>2024.0.0</spring-cloud.version> <!-- Spring Cloud 2024.x -->
        <spring-cloud-alibaba.version>2022.0.0.0-RC2</spring-cloud-alibaba.version> <!-- Spring Cloud Alibaba 对应版本 -->
        <keycloak.version>22.0.4</keycloak.version>   <!-- 非必须，我的项目需要，你不用就删掉 -->
    </properties>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

这一步主要就是导入你的依赖嘛。

第四步 编写bootstrap.yaml

这一块里面其实主要就是你的nacos的配置文件，反正我用的是nacos，因为Zuul是网关嘛，Gateway也是网关，然后你实际的服务和网关都是要在同一个服务发现下面的，我之前是eureka，现在是nacos，所以要在这里说明的。

yaml 复制代码 
spring:
  main:
    allow-circular-references: true
    allow-bean-definition-overriding: true
  application:
    name: rbac-gateway
  cloud:
    nacos:
      username: ${ENV_CONFIG_USERNAME:nacos}
      password: ${ENV_CONFIG_PASSWORD:}
      server-addr: ${ENV_CONFIG_IP:10.*.*.*}:${ENV_CONFIG_PORT:*}

      # Nacos 服务发现配置
      discovery:
        enabled: true  # 启用服务发现
        service: ${spring.application.name}  # 使用应用名作为服务名
        server-addr: ${ENV_CONFIG_IP:*}:${ENV_CONFIG_PORT:*}
        namespace: ${NAMESPACE:*}
        #group: ${spring.cloud.nacos.discovery.group:*}
        group: *
        metadata:
          version: v1
          env: prod

    # Nacos 配置中心配置
      config:
        enabled: true
        server-addr: ${ENV_CONFIG_IP:*}:${ENV_CONFIG_PORT:*}
#        group: ${spring.cloud.nacos.discovery.group:*}
        group: *
        namespace: ${NAMESPACE:*}
        file-extension: yml
        shared-configs:
          - data-id: ${CONFIG_DATA_ID:ms-gateway.yml}
            group: *
            refresh: true
      timeout: 600000
      config-long-poll-timeout: 5000
      config-retry-time: 2000
      max-retry: 3
      refresh-enabled: true

第五步：替换路由配置

将 Zuul 的 application.yml 配置迁移为 Gateway 的路由配置。这一块实际上就比较复杂了，因为他们之间的切换还是很麻烦的，所以我这里是直接使用AI帮我替换的，你也可以这样。

反正差不多样子就是如下吧。直接让AI帮你替换，然后你看一眼就行了。我反正是这么搞的，然后也没啥问题。

Zuul 配置：

yaml 复制代码 
zuul:
  #
  semaphore:
    max-semaphores: 1000
  servlet-path: /
  host:
    connect-timeout-millis: 60000
    socket-timeout-millis: 60000
  #
  routes:
    smartdata-check:
      path: /smartCheck
      service-id: rbac
      strip-prefix: false
    smartdata-token-init:
      path: /v1/smartdata/token
      service-id: rbac
      strip-prefix: false
    composite-roles:
      path: /v1/roles/**
      service-id: rbac
      strip-prefix: false

Gateway 配置：

yaml 复制代码 
spring:
  cloud:
    gateway:
      routes:
        - id: sso
          uri: lb://rbac
          predicates:
            - Path=/v1/alerts/sso/**
        - id: smartdata-check
          uri: lb://rbac
          predicates:
            - Path=/smartCheck
        - id: smartdata-token-init
          uri: lb://rbac
          predicates:
            - Path=/v1/smartdata/token
        - id: composite-roles
          uri: lb://rbac
          predicates:
            - Path=/v1/roles/**

其实没有全局过滤器，已经可以用了，就是网关服务已经是可以用了。到这里其实就已经结束了。服务能用。不看后面也行，我为什么要替换呢，因为我想完美迁移。

第六步：迁移过滤器逻辑

Zuul 使用过滤器机制来处理请求，而 Gateway 则使用过滤器工厂。这一块就比较复杂了，也是我花的最多时间的一步了。

原本的Zuul 过滤器：

java 复制代码 
import com.netflix.zuul.ZuulFilter;
import com.netflix.zuul.context.RequestContext;
import java.util.Map;
import javax.servlet.http.HttpServletRequest;
import org.keycloak.KeycloakSecurityContext;
import org.keycloak.representations.AccessToken;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.cloud.netflix.zuul.filters.Route;
import org.springframework.cloud.netflix.zuul.filters.RouteLocator;
import org.springframework.web.util.UrlPathHelper;

public class PathRewriteHeaderFilter extends ZuulFilter {
  private static final Logger log = LoggerFactory.getLogger(com.migu.tsg.microservice.zuul.PathRewriteHeaderFilter.class);
  
  private RouteLocator routeLocator;
  
  private final UrlPathHelper urlPathHelper = new UrlPathHelper();
  
  private static final String EMPLOYEE_TYPE = "employeeType";
  
  private static final String ORG_ACCOUNT = "head_orgAccount";
  
  private static final String IS_ADMIN = "head_isAdmin";
  
  private static final String IS_SUPERUSER = "head_isSuperUser";
  
  private static final String USER_NAME = "head_userName";
  
  private static final String FALSE = "false";
  
  private static final String TRUE = "true";
  
  private static final String ADMIN = "admin";
  
  private static final String ROOT = "root";
  
  private static final Integer SIX = Integer.valueOf(6);
  
  private static final String COLON = ":";
  
  public PathRewriteHeaderFilter() {}
  
  public PathRewriteHeaderFilter(RouteLocator routeLocator) {
    this.routeLocator = routeLocator;
  }
  
  public int filterOrder() {
    return SIX.intValue();
  }
  
  public String filterType() {
    return "pre";
  }
  
  public boolean shouldFilter() {
    return true;
  }
  
  public Object run() {
    RequestContext requestContext = RequestContext.getCurrentContext();
    String requestURI = this.urlPathHelper.getPathWithinApplication(requestContext.getRequest());
    Route route = this.routeLocator.getMatchingRoute(requestURI);
    try {
      if (route != null) {
        String location = route.getLocation();
        log.info("location: {}", location);
        if (location != null) {
          HttpServletRequest request = requestContext.getRequest();
          KeycloakSecurityContext securityContext = (KeycloakSecurityContext)request.getAttribute(KeycloakSecurityContext.class.getName());
          handleRewriteHeader(securityContext, requestContext);
          if (location.startsWith("http:") || location.startsWith("https:"))
            log.info("forward url is : " + location); 
        } 
      } 
    } catch (Exception e) {
      requestContext.set("error.status_code", Integer.valueOf(500));
      requestContext.set("error.message", e.getCause());
      requestContext.set("error.exception", e);
    } 
    return null;
  }
  
  private void handleRewriteHeader(KeycloakSecurityContext securityContext, RequestContext requestContext) {
    log.info("keycloak securityContext = {}", securityContext);
    if (securityContext == null)
      return; 
    AccessToken token = securityContext.getToken();
    Map<String, Object> otherClaims = token.getOtherClaims();
    log.info("keycloak token = {}, otherClaims = {}", token, otherClaims);
    String employeeType = (String)otherClaims.get("employeeType");
    String userName = (String)otherClaims.get("userName");
    String orgAccount = "";
    String isSupperUser = "false";
    String isAdmin = "false";
    if (employeeType.equals("root")) {
      isSupperUser = "true";
      orgAccount = userName;
    } 
    if (employeeType.equals("admin")) {
      isAdmin = "true";
      orgAccount = userName;
    } 
    if (!employeeType.equals("root") && !employeeType.equals("admin")) {
      int index = employeeType.indexOf(".") + 1;
      orgAccount = employeeType.substring(index, employeeType.length());
    } 
    log.info("employeeType: {}, head_userName: {}, head_isSuperUser: {}, head_orgAccount: {}, head_isAdmin: {}", new Object[] { employeeType, userName, isSupperUser, orgAccount, isAdmin });
    requestContext.addZuulRequestHeader("head_userName", userName);
    requestContext.addZuulRequestHeader("head_isSuperUser", isSupperUser);
    requestContext.addZuulRequestHeader("head_orgAccount", orgAccount);
    requestContext.addZuulRequestHeader("head_isAdmin", isAdmin);
  }
}

但是我是想完美的等量替换，所以这里就把原本的过滤器也给拿过来了。可以看到是少了一些东西了，因为原本的方法有很多东西是用不到的，我就把那些东西给删掉了。只保留了用到的东西

反正我测下来，是没啥问题，反正就是实现起来差别真的很大，首先是extends ZuulFilter不用了，改成了GlobalFilter ，然后里面的实现也从public Object run() 变成了public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) ，然后具体的实现逻辑也变了，这一块呢，就是自己琢磨着改吧。每一个过滤器都不一样，反正大体逻辑就是实现的方法不一样了，然后重写的方法不一样了。这两个是最主要的。

  1. 实现的接口不一样
  2. 重写的方法不一样

其实主要把握这两个就行，里面就是具体的代码逻辑了。

替换后的Gateway 全局过滤器：

java 复制代码 
@Component
@Order(6)  // 这里使用 @Order 注解来设置过滤器顺序
public class PathRewriteHeaderFilter implements GlobalFilter {

    private static final Logger log = LoggerFactory.getLogger(PathRewriteHeaderFilter.class);

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        try {
            String requestURI = exchange.getRequest().getURI().getPath();
            log.info("Request URI: {}", requestURI);

            // 在此处你可以获取并处理 Keycloak 的 securityContext 和 token
            KeycloakSecurityContext securityContext = exchange.getAttribute(KeycloakSecurityContext.class.getName());
            if (securityContext != null) {
                AccessToken token = securityContext.getToken();
                Map<String, Object> otherClaims = token.getOtherClaims();
                log.info("keycloak token = {}, otherClaims = {}", token, otherClaims);

                String employeeType = (String) otherClaims.get("employeeType");
                String userName = (String) otherClaims.get("userName");
                String orgAccount = "";
                String isSuperUser = "false";
                String isAdmin = "false";

                if ("root".equals(employeeType)) {
                    isSuperUser = "true";
                    orgAccount = userName;
                } else if ("admin".equals(employeeType)) {
                    isAdmin = "true";
                    orgAccount = userName;
                } else {
                    int index = employeeType.indexOf(".") + 1;
                    orgAccount = employeeType.substring(index);
                }

                log.info("employeeType: {}, head_userName: {}, head_isSuperUser: {}, head_orgAccount: {}, head_isAdmin: {}",
                        employeeType, userName, isSuperUser, orgAccount, isAdmin);

                exchange.getRequest().mutate()
                        .header("head_userName", userName)
                        .header("head_isSuperUser", isSuperUser)
                        .header("head_orgAccount", orgAccount)
                        .header("head_isAdmin", isAdmin)
                        .build();
            }

        } catch (Exception e) {
            log.error("Error processing request", e);
        }

        return chain.filter(exchange);
    }
}

第七步：测试与调优

  1. 功能测试

    验证迁移后的路由和过滤器逻辑是否正常工作。

    我这里是正常的，没有问题的。

  2. 性能测试

    测试 Gateway 的吞吐量和延迟，确保性能满足要求。

  3. 监控与日志

    配置 Gateway 的监控和日志，及时捕获异常和瓶颈。

迁移过程中常见问题及解决方案

  1. 问题：某些依赖库与 WebFlux 不兼容
    解决方案： 更新相关依赖或寻找替代方案，确保与 WebFlux 模型兼容。

  2. 问题：路由配置规则变更导致服务无法访问
    解决方案： 仔细对比 Zuul 和 Gateway 的配置方式，确保路径匹配规则正确。

  3. 问题：过滤器执行顺序混乱
    解决方案： 合理设置过滤器的 Order 值，并明确其执行逻辑。

真实问题：

注意事项：Nginx 转发配置的调整

在迁移过程中，有一个细节需要特别注意，那就是 Nginx 的转发规则。以下是我遇到的问题和解决方法，希望能对你有所帮助。

问题背景

在原有的 Zuul 部署环境中，我使用的是 IP+端口 的形式进行服务转发。由于迁移初期 IP 和端口并未发生改变，所以 Nginx 的配置无需修改，服务能够正常使用。然而，当将 Gateway 部署到云原生环境（如 Kubernetes）后，问题随之出现。

云原生环境中，服务之间的通信通常使用 服务名:端口 的形式，而不是 IP 地址。因此，原本在 Nginx 中配置的 qams-zuul-server 服务名需要进行修改，否则转发规则无法正确匹配，导致请求失败。

解决方法
  1. 检查原有的 Nginx 配置
    原有配置通常类似以下形式：
r 复制代码 
        location ^~/v1/ {
            proxy_pass   http://zuulServer;
        }
         location ^~/v2/ {
            #proxy_pass   http://10.24.88.160:5566;
            proxy_pass   http://10.12.7.115:5566;
        }
         location ^~/zuul/ {
            #proxy_pass   http://10.24.88.160:5566;
            proxy_pass   http://10.12.7.115:5566;
        }
          location ^~/download/ {
            proxy_pass   http://10.24.88.160:2222;
        }

这种配置基于固定的 IP 和端口，在云原生环境下无法适用。

  1. 修改为基于服务名的配置
    在云原生环境中，需要将 10.12.7.115 的地址替换为服务名，示例如下：
cobol 复制代码 
  location ^~/v1/ {                                                                                         
        proxy_pass   http://qams-gateway-server:5566;
    }
    
    location ^~/v2/ {                                                                                       
        proxy_pass   http://qams-gateway-server:5566;                                                                 
    } 
    
    location ^~/gateway/ {                                                                                       
        proxy_pass   http://qams-gateway-server:5566;                                                                 
    }
    
    location ^~/download/ {                                                                                       
        proxy_pass   http://qams-gateway-server:2222;                                                                 
    }

注意：

  • 服务名 qams-gateway-service 必须与云原生环境中定义的服务名称一致。
  • 确保 Nginx 能够解析服务名。通常情况下，Nginx 部署在同一 Kubernetes 集群内，DNS 解析应当是自动支持的。
  1. 重启 Nginx 并测试
    完成修改后，重启 Nginx 并通过实际访问测试转发是否正常。

迁移的时候注意nginx的转发，我之前呢，是因为我使用的是IP+端口的形式，然后我的IP和端口实际上并没有发生改变，所以我的Nginx没改然后服务依旧能正常使用。

但是当我把Gateway迁移到云原生环境下的时候，就不太行了，因为云原生环境使用的是服务名：端口的格式，所以他原本的服务名称为：qams-zuul-server，要换成下面的格式，就是nginx也要需要，这个不要忘记了。

总结

从 Zuul 迁移到 Spring Cloud Gateway 是一次提升系统性能和功能的好机会。通过合理规划和逐步迁移，可以平稳完成网关的升级，并充分利用 Gateway 的新特性来优化系统架构。

希望这篇文章能为你的迁移过程提供有价值的参考！如果你在迁移过程中遇到问题，欢迎留言讨论。

相关推荐
weixin_472339462 小时前
高效处理大体积Excel文件的Java技术方案解析
java·开发语言·excel
枯萎穿心攻击3 小时前
响应式编程入门教程第二节：构建 ObservableProperty＜T＞ — 封装 ReactiveProperty 的高级用法
开发语言·unity·c#·游戏引擎
Eiceblue4 小时前
【免费.NET方案】CSV到PDF与DataTable的快速转换
开发语言·pdf·c#·.net
m0_555762905 小时前
Matlab 频谱分析 (Spectral Analysis)
开发语言·matlab
浪裡遊5 小时前
React Hooks全面解析：从基础到高级的实用指南
开发语言·前端·javascript·react.js·node.js·ecmascript·php
烛阴6 小时前
简单入门Python装饰器
前端·python
lzb_kkk6 小时前
【C++】C++四种类型转换操作符详解
开发语言·c++·windows·1024程序员节
好开心啊没烦恼6 小时前
Python 数据分析：numpy，说人话，说说数组维度。听故事学知识点怎么这么容易？
开发语言·人工智能·python·数据挖掘·数据分析·numpy
面朝大海，春不暖，花不开7 小时前
使用 Python 实现 ETL 流程：从文本文件提取到数据处理的全面指南
python·etl·原型模式
简佐义的博客7 小时前
破解非模式物种GO/KEGG注释难题
开发语言·数据库·后端·oracle·golang
热门推荐
01Java学习第十五部分——MyBatis02集群聊天服务器---MySQL数据库的建立03Coze扣子平台完整体验和实践（附国内和国际版对比）04基于odoo17的设计模式详解---装饰模式05使用Ruby接入实时行情API教程06扣子（coze）实战|我用扣子搭建了一个自动分析小红薯笔记内容的AI应用|详细步骤拆解07Everything文件检索工具 几秒检索几百G的文件08基于odoo17的设计模式详解---单例模式09DeepSeek各版本说明与优缺点分析10【无标题】