Spring Boot自定义Filter未被调用：是否需要注册？

核心问题分析与修复步骤 #

1. 包导入冲突（关键原因） #

Spring Boot 3.x（基于Spring 6）完全迁移到Jakarta EE规范，所有Servlet相关API都从javax.servlet.*改为jakarta.servlet.*。你的代码中混合了两种包导入：

• 正确导入：jakarta.servlet.http.HttpServletRequest
• 错误导入：javax.servlet.*（Filter、FilterChain等）

这种包冲突会导致容器无法正确识别Filter实现，直接造成Filter不生效。

修复：
将所有javax.servlet.*替换为jakarta.servlet.*，修正后的代码：

package com.example.demo.filter;

import jakarta.servlet.*;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;

import java.io.IOException;

@Component
public class CustomRequestFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest req = (HttpServletRequest) request;
        HttpServletResponse res = (HttpServletResponse) response;

        System.out.println("Hello Filter");

        // 修正类型强转错误：request是请求对象，不能转为HttpServletResponse
        res.setHeader("X-TEST-RESPONSE", "FOOBAR-RESPONSE");
        // 若需给请求添加标识，用setAttribute而非setHeader
        req.setAttribute("X-TEST-REQUEST", "FOOBAR-REQUEST");

        chain.doFilter(request, response);
    }
}

2. 代码中的类型强转错误 #

原代码中((HttpServletResponse) request).setHeader(...)是严重错误：request是HttpServletRequest实例，强行转成HttpServletResponse会抛出ClassCastException，一旦抛出异常，Filter链会中断，且容器可能不会输出明显日志，导致你误以为Filter没被调用。

3. 补充：Filter注册的额外检查点 #

如果修正包导入后仍不生效，检查以下内容：

• 包扫描范围：确保com.example.demo.filter包被Spring Boot组件扫描覆盖（默认主启动类所在包及其子包会被自动扫描，若Filter在主启动类包外，需手动添加@ComponentScan指定包路径）。
• 显式注册Filter（可选）：除了@Component，也可以通过配置类显式注册，更灵活控制拦截路径和执行顺序：

import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class FilterConfig {
    @Bean
    public FilterRegistrationBean<CustomRequestFilter> customRequestFilter() {
        FilterRegistrationBean<CustomRequestFilter> registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(new CustomRequestFilter());
        // 指定拦截路径，默认值为/*
        registrationBean.addUrlPatterns("/*");
        // 设置Filter执行顺序，数值越小优先级越高
        registrationBean.setOrder(1);
        return registrationBean;
    }
}

验证方法 #

1. 打开System.out.println("Hello Filter");的注释，启动项目后发起请求，查看控制台是否输出该内容。
2. 用Postman或浏览器发起请求，检查响应头中是否包含X-TEST-RESPONSE。

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