如何在 Spring Boot 中整合 Zuul 实现 API 网关？

微服务架构中，网关扮演着所有外部请求统一入口的角色，负责分发流量、聚合响应、实施安全策略。Zuul 作为 Netflix 开源的第一代网关组件，与 Spring Boot 生态结合紧密，能够以极低的配置成本集成到现有项目中。它支持多种路由规则、动态配置以及过滤器扩展，适合中小型项目快速落地网关需求。下面将围绕 Spring Boot 与 Zuul 的整合过程展开，从依赖引入到实际运行，逐步构建一个可用的 API 网关服务。

Zuul 的核心概念与整合准备

Zuul 本质上是一个基于 JVM 的网关服务器，核心能力包括请求路由、过滤、监控和弹性处理。在 Spring Cloud 体系内，它被封装为 spring-cloud-starter-netflix-zuul 启动器，底层依赖 Ribbon 和 Hystrix，因此天然支持客户端负载均衡与服务容错。路由规则可以在 application.yml 中静态配置，也可以结合服务发现组件动态获取服务列表。

在开始编写代码之前，需要明确 Zuul 的几个重要概念：路由（Route）定义了请求路径与实际后端服务地址的映射关系；过滤器（Filter）是 Zuul 实现切面逻辑的载体，按执行阶段分为 pre、route、post、error 四种类型；路由定位器（RouteLocator）用于动态管理路由规则。这些概念与 Spring MVC 的拦截器机制有相似之处，但过滤器的执行范围更广，能够直接修改请求对象和响应对象。

整合环境要求 JDK 8 以上版本，构建工具可以选择 Maven 或 Gradle。这里以 Maven 为例，首先创建一个 Spring Boot 项目，版本选择 2.x 系列。由于 Spring Cloud 的版本需要与 Spring Boot 严格匹配，建议引入 BOM 进行统一管理，避免依赖冲突。下面是核心依赖片段：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>Hoxton.SR12</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-netflix-zuul</artifactId>
    </dependency>
</dependencies>

配置路由规则实现基础转发

路由配置是网关最基本的功能。Zuul 提供了两种配置风格：一种是直接使用 zuul.routes 下的自定义键值对，另一种是基于服务名的简化配置。如果后端服务已经注册到 Eureka 或 Consul 中，Zuul 能够自动根据服务名生成路由，例如服务名为 user-service 时，访问网关的 /user-service/** 路径会自动转发到该服务。不过在没有注册中心的情况下，直接配置 URL 更加直观。

假设我们有一个订单服务运行在 http://localhost:8081，一个库存服务运行在 http://localhost:8082，希望网关将 /api/order/** 的请求转发到订单服务，将 /api/inventory/** 转发到库存服务。配置文件如下：

server:
  port: 9000

zuul:
  routes:
    order-service:
      path: /api/order/**
      url: http://localhost:8081
    inventory-service:
      path: /api/inventory/**
      url: http://localhost:8082

上述配置中，path 定义了网关接收的请求路径，支持 Ant 风格匹配，可以使用 ** 通配多级目录，* 通配单级目录。url 指定了后端服务的完整地址，Zuul 会将匹配到的路径转发过去。默认情况下，网关会保留路径中除了匹配前缀之外的部分，例如请求 /api/order/123 会被转发到 http://localhost:8081/123。如果希望转发时保留完整路径，可以设置 stripPrefix: false。

除了直接写死 URL 之外，还可以使用服务名作为路由目标。当引入服务发现组件后，配置方式变为：

zuul:
  routes:
    order-service:
      path: /api/order/**
      serviceId: order-service

这里的 serviceId 对应注册中心里的服务名称，Zuul 会借助 Ribbon 进行客户端负载均衡，自动选择可用的服务实例。这种方式更符合微服务理念，避免了硬编码地址带来的维护问题。对于不需要对外暴露的服务，还可以通过 zuul.ignored-services 进行排除。

自定义过滤器实现请求拦截与日志记录

过滤器是 Zuul 的灵魂，几乎所有的横切逻辑都可以通过过滤器实现，比如登录校验、权限控制、请求日志、限流和灰度发布。Zuul 的过滤器需要继承 ZuulFilter 抽象类，并实现四个核心方法：filterType() 返回过滤器类型（pre、route、post、error），filterOrder() 返回执行顺序（数值越小优先级越高），shouldFilter() 返回布尔值决定是否执行该过滤器，run() 中编写具体的过滤逻辑。

下面实现一个简单的 pre 类型过滤器，用于记录所有到达网关的请求信息，包括请求方法、请求路径和客户端 IP，并在请求头中添加一个自定义字段。这样可以帮助排查问题，也可以为后续的链路追踪提供数据来源。

import com.netflix.zuul.ZuulFilter;
import com.netflix.zuul.context.RequestContext;
import com.netflix.zuul.exception.ZuulException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import javax.servlet.http.HttpServletRequest;

@Component
public class RequestLogFilter extends ZuulFilter {

    private static final Logger logger = LoggerFactory.getLogger(RequestLogFilter.class);

    @Override
    public String filterType() {
        return "pre";
    }

    @Override
    public int filterOrder() {
        return 1;
    }

    @Override
    public boolean shouldFilter() {
        return true;
    }

    @Override
    public Object run() throws ZuulException {
        RequestContext ctx = RequestContext.getCurrentContext();
        HttpServletRequest request = ctx.getRequest();
        String remoteAddr = request.getRemoteAddr();
        String method = request.getMethod();
        String requestURI = request.getRequestURI();
        logger.info("接收请求：{} {}，来源IP：{}", method, requestURI, remoteAddr);
        ctx.addZuulRequestHeader("X-Gateway-Timestamp", String.valueOf(System.currentTimeMillis()));
        return null;
    }
}

在 run() 方法中，通过 RequestContext 可以获取当前请求上下文，进而操作 HttpServletRequest 和 HttpServletResponse。这里向请求头添加了时间戳字段，后端服务可以从请求头中读取该值，实现简单的链路标记。如果需要阻止请求继续路由，可以调用 ctx.setSendZuulResponse(false)，并设置响应状态码和响应体，例如在认证失败时返回 401。

另外一类常见的过滤器是 post 类型，它在请求被路由到后端服务、响应返回之后执行，适合对响应结果进行加工或记录耗时。下面的示例计算每个请求的总处理时间并输出日志：

import com.netflix.zuul.ZuulFilter;
import com.netflix.zuul.context.RequestContext;
import com.netflix.zuul.exception.ZuulException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import javax.servlet.http.HttpServletRequest;

@Component
public class ResponseTimeFilter extends ZuulFilter {

    private static final Logger logger = LoggerFactory.getLogger(ResponseTimeFilter.class);

    @Override
    public String filterType() {
        return "post";
    }

    @Override
    public int filterOrder() {
        return 2;
    }

    @Override
    public boolean shouldFilter() {
        return true;
    }

    @Override
    public Object run() throws ZuulException {
        RequestContext ctx = RequestContext.getCurrentContext();
        HttpServletRequest request = ctx.getRequest();
        long startTime = (long) request.getAttribute("startTime");
        long duration = System.currentTimeMillis() - startTime;
        logger.info("请求 {} 耗时 {} ms", request.getRequestURI(), duration);
        return null;
    }
}

注意这个过滤器依赖 pre 阶段设置的 startTime 属性，因此需要在 pre 过滤器中先调用 request.setAttribute("startTime", System.currentTimeMillis())。这种跨阶段的配合在 Zuul 过滤器中非常常见，需要合理设计过滤器的执行顺序和数据传递方式。

路由重试、超时与容错配置

网关作为流量的汇聚点，稳定性至关重要。Zuul 底层集成 Ribbon 和 Hystrix，因此可以通过这两者的配置实现超时控制、重试机制和熔断降级。默认情况下，Zuul 的路由超时时间为 2000 毫秒，超过该时间会抛出超时异常并返回 500 错误。实际业务中往往需要根据后端服务的响应速度进行调整。

以下配置演示如何修改 Ribbon 的连接超时和读取超时，以及开启重试机制。需要注意的是，重试次数和超时时间需要配合使用，否则可能导致请求堆积。假设我们的某个服务响应较慢，可以这样设置：

ribbon:
  ConnectTimeout: 3000
  ReadTimeout: 6000
  MaxAutoRetries: 1
  MaxAutoRetriesNextServer: 2
  OkToRetryOnAllOperations: true

上述配置表示连接超时 3 秒，读取超时 6 秒，同一实例最多重试 1 次，最多切换 2 个不同实例，并且所有类型的请求（包括 POST、PUT）都允许重试。对于非幂等操作，开启重试可能会造成数据重复提交，需要谨慎设置。如果项目中引入了 Hystrix，还可以通过 hystrix.command.default.execution.isolation.thread.timeoutInMilliseconds 配置整体超时，建议 Hystrix 超时时间略大于 Ribbon 的超时与重试时间之和。

此外，Zuul 还支持自定义错误过滤器和回退机制，当路由失败或后端服务不可用时，返回友好的 JSON 错误信息而不是默认的 500 页面。通过实现 ZuulErrorFilter 或捕获 ZuulException，可以统一处理错误响应结构，提升用户体验和系统可观测性。网关的容错能力直接关系到整个系统的可用性，在负载较高的场景下，合理的超时与重试配置能够有效避免级联故障。

运行验证与常见问题排查

完成上述配置后，启动网关服务和两个模拟后端服务（可以是简单的 Spring Boot REST 接口），访问网关地址即可验证路由是否生效。例如本地启动网关在 9000 端口，订单服务在 8081 端口，请求 http://localhost:9000/api/order/list 应该能够正常返回订单服务的数据。同时观察控制台日志，可以看到 pre 过滤器打印的请求日志和 post 过滤器输出的耗时信息。

在调试过程中经常遇到路由不生效的情况，首先要检查 zuul.routes 的配置格式是否正确，特别是 path 与 url 是否匹配。其次确认网关服务是否添加了 @EnableZuulProxy 注解，该注解是启动 Zuul 网关的关键，缺少它会导致所有路由配置被忽略。另外，如果使用了服务发现，需要保证注册中心正常运行且服务名拼写一致。

如果出现 404 错误，可以开启 Zuul 的调试日志查看路由匹配过程。在 application.yml 中添加 logging.level.com.netflix.zuul: DEBUG，重启后访问请求，控制台会输出每个路由匹配的详细信息，包括路由 ID、路径匹配结果、最终目标地址等。通过这些日志可以快速定位是路径配置错误还是服务实例缺失。对于生产环境，建议结合 Spring Boot Actuator 暴露路由信息端点，便于运维人员动态查看当前生效的路由列表。

Zuul 作为网关的入门组件，虽然功能不如后来的 Spring Cloud Gateway 丰富，但其轻量、易上手的特点依然适合许多中小型项目。掌握它的路由配置、过滤器扩展和容错调优，能够为后续深入学习微服务架构中的边缘服务设计打下坚实基础。在实际项目中，还需要结合安全认证、限流、灰度发布等高级需求，逐步完善网关层的功能完整性。

Spring BootZuulAPI网关修改时间：2026-09-30 04:15:09