Quarkus服务过滤器实现的可选替代依赖包咨询

AI 小北

2026-8-27

Quarkus 过滤器实现方案参考

Quarkus 生态内除了javax.ws.rs.client包下的JAX-RS标准客户端过滤器外，还有多类官方原生支持、适配GraalVM原生编译的过滤器实现，不需要额外引入非官方第三方依赖，按你的业务场景选即可：

RESTEasy Reactive 内置过滤器（默认REST栈）
Quarkus默认的REST实现完全兼容JAX-RS标准，你之前熟悉的JAX-RS过滤器写法可以直接用，同时做了性能优化，没有额外反射开销，原生镜像下无需额外配置。
- 服务端过滤：实现ContainerRequestFilter/ContainerResponseFilter接口加@Provider注解即可自动注册，支持@PreMatching（请求匹配路由前执行）、@NameBinding（自定义注解标记指定接口生效）、@Priority控制执行顺序。
- 客户端过滤：除标准JAX-RS客户端过滤器外，还提供了@ClientHeaderParam这类注解式能力，不用写实现类就能完成自动加请求头、参数签名这类通用逻辑。

Vert.x 层全局HTTP过滤器
如果你需要拦截所有HTTP请求（包括静态资源、非REST路由的请求），可以直接实现Quarkus内置的RouteFilter接口，优先级高于REST层过滤器，适合做全局鉴权、跨域处理、统一访问日志这类跨业务的逻辑。只要项目引入了quarkus-vertx-web（绝大多数Web相关依赖都会间接传递引入）就可以直接用，示例代码：

import io.quarkus.vertx.web.RouteFilter;
import io.vertx.ext.web.RoutingContext;

public class GlobalAccessLogFilter {
    @RouteFilter(100) // 数值越小，过滤器执行优先级越高
    void process(RoutingContext ctx) {
        long startAt = System.currentTimeMillis();
        ctx.addEndHandler(end -> {
            // 响应返回后执行的逻辑
            System.out.printf("path:%s status:%d cost:%dms%n",
                    ctx.request().path(),
                    ctx.response().getStatusCode(),
                    System.currentTimeMillis() - startAt);
        });
        ctx.next(); // 放行请求
    }
}

横切场景专用内置拦截器
如果你的过滤器是做链路追踪、指标采集、限流、重试这类通用横切逻辑，不需要手写过滤器，直接引入对应官方扩展即可自动完成拦截：
- 链路追踪/指标：引入quarkus-micrometer或quarkus-opentelemetry扩展，会自动注册全局过滤器采集请求指标、打链路标记
- 容错能力：引入quarkus-smallrye-fault-tolerance扩展，用@Retry、@RateLimit、@Timeout等注解标记接口即可实现对应拦截逻辑，不需要自己写拦截代码
Spring 兼容层过滤器
如果你是从Spring Boot体系迁移到Quarkus，希望复用原有Spring生态的过滤器代码，可以直接引入quarkus-spring-web扩展，原有实现javax.servlet.Filter/OncePerRequestFilter接口的过滤器代码可以直接运行，几乎不需要改造成本。

版本适配提示：Quarkus 2.x 及更早版本使用javax包名，3.x及之后版本全部迁移到jakarta包名，引入依赖和写代码时注意和你当前使用的Quarkus版本匹配，不要混引不同包名的类，避免出现过滤器不生效的问题。生产环境优先选上述官方维护的扩展，不要随意引入未做Quarkus适配的第三方JAX-RS组件，避免原生镜像编译、运行时出现兼容性问题。

内容的提问来源于stack exchange，提问作者Lucas Mattera