Spring Cloud Zuul 过滤器（Filter）深度解析

覆写这四个方法是标准动作。其中 filterType 决定了过滤器在请求生命周期中的位置，Zuul 定义了四种类型：

• pre：路由之前调用，适合做参数校验、权限控制。
• route：路由请求时调用，通常用于修改请求头或转发逻辑。
• post：在 route 和 error 之后调用，适合记录日志或修改响应头。
• error：处理请求发生错误时的逻辑。

filterOrder 决定同类型过滤器的执行顺序，数字越小优先级越高。shouldFilter 则是一个开关，返回 false 时该过滤器直接跳过。而 run 方法里才是具体的业务逻辑，比如通过 ctx.setSendZuulResponse(false) 来阻断请求路由。

2. 过滤器间的状态传递

过滤器之间没有直接的引用关系，但可以通过 RequestContext 共享状态。这是一个类似 Map 的结构，底层使用 ThreadLocal 实现，非常适合在同一个请求线程内传递数据。

接下来我们写一个密码校验过滤器，它会检查上一个过滤器是否已经成功。

public class AccessPasswordFilter extends ZuulFilter {
    @Override
    public Object run() {
        RequestContext ctx = RequestContext.getCurrentContext();
        HttpServletRequest request = ctx.getRequest();

        System.out.println(String.format("%s AccessPasswordFilter request to %s", 
            request.getMethod(), request.getRequestURL().toString()));

        String password = request.getParameter("password");
        if (null != password && password.equals("123456")) {
            ctx.setSendZuulResponse(true);
            ctx.setResponseStatusCode(200);
            ctx.set("isSuccess", true);
            return null;
        } else {
            ctx.setSendZuulResponse(false);
            ctx.setResponseStatusCode(401);
            ctx.setResponseBody("{\"result\":\"password is not correct!\"}");
            ctx.set("isSuccess", false);
            return null;
        }
    }

    @Override
    public boolean shouldFilter() {
        RequestContext ctx = RequestContext.getCurrentContext();
        // 如果前一个过滤器失败，当前过滤器直接跳过
        return (boolean) ctx.get("isSuccess");
    }

    @Override
    public int filterOrder() {
        return 1; // 优先级设为 1，晚于用户名过滤器
    }

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

注意 shouldFilter 里的逻辑：如果前一步校验失败（isSuccess 为 false），这里直接返回 false，后续的过滤器都不会再执行，直接返回错误结果。这种链式依赖在实际开发中非常常见。

最后，我们还需要一个后置过滤器来处理最终响应。

public class AccessTokenFilter extends ZuulFilter {
    @Override
    public Object run() {
        RequestContext ctx = RequestContext.getCurrentContext();
        // 这里可以做一些统一的后置处理，比如添加 Token 到响应头
        ctx.setSendZuulResponse(true);
        ctx.setResponseStatusCode(200);
        ctx.setResponseBody("{\"name\":\"user\"}");
        return null;
    }

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

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

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

3. 测试与执行顺序验证

注册好这些 Bean 后，我们来看看实际请求的效果。

场景一：缺少密码 请求 URL：http://localhost:8768/h2service/user/1?username=admin 控制台会打印两个 Filter 都收到了请求，但最终返回 password is not correct!。这说明请求通过了用户名校验，但在密码校验阶段被拦截了，后端服务并未真正被调用。

场景二：缺少用户名 请求 URL：http://localhost:8768/h2service/user/1?password=123456 此时只有 AccessUserNameFilter 被触发，因为它的优先级更高且先执行。一旦它判定失败，整个流程终止，不会进入后续的密码校验。

场景三：信息完整 请求 URL：http://localhost:8768/h2service/user/1?username=admin&password=123456 此时所有前置过滤器均通过，请求被正常路由到后端服务，数据库 SQL 语句正常输出。这验证了 order 值越小优先级越高的规则。

关于 Zuul 的 Filter 生命周期，整体流程是：Pre -> Route -> Post。对于每个请求，具有这些类型的过滤器都会依次运行。需要注意的是，虽然 AccessTokenFilter 的 order 是 0，但因为它是 post 类型，所以会在所有 pre 类型完成后才执行，这一点在实际调试时容易混淆。

4. 拓展阅读

除了自定义过滤器，Zuul 还提供了一些特殊用途的过滤器，例如 StaticResponseFilter 允许直接从网关生成响应而不转发请求，或者 SurgicalDebugFilter 用于将特定请求路由到独立的调试集群。理解这些内置能力，能帮助我们更灵活地设计网关架构。

掌握 Filter 的生命周期和上下文传递机制，是玩转 Zuul 网关的关键。在实际项目中，结合这些特性可以实现复杂的鉴权、限流和灰度发布策略。