Spring Boot多模块应用中避免重复注册同名请求响应过滤器的正确实践

在spring boot多模块项目中，若多个模块均定义了同名且标注@component的filter实现，spring会将所有实例自动注册进全局过滤链，导致请求被随机拦截——这是由spring容器统一管理bean生命周期所致，而非负载均衡或线程调度引起。

在多模块Spring Boot应用中，过滤器（Filter）的注册行为由Spring容器的Bean扫描机制决定，而非模块边界。当你在三个模块中分别定义了相同类名、且均使用@Component（或@WebFilter + @ServletComponentScan）声明的自定义Filter时，Spring Boot启动过程中会：

1. 扫描所有已启用的模块（取决于@SpringBootApplication所在模块的scanBasePackages或默认扫描路径）；
2. 将每个匹配的@Component类实例化为Spring Bean；
3. 自动将所有实现了javax.servlet.Filter接口的Bean注册到Servlet容器的过滤链中（通过FilterRegistrationBean或自动配置机制）。

⚠️ 关键问题在于：Spring不校验Filter类名是否重复，也不按模块隔离——它只认Bean类型与实例数量。 因此，三个同名Filter会被视为三个独立Bean，全部加入同一过滤链。由于Filter执行顺序默认由Bean注册顺序决定（受类路径加载顺序、编译顺序等影响），每次启动甚至每次请求都可能触发不同Filter，造成响应不一致、日志混乱、Header篡改冲突等非预期行为。

✅ 正确解决方案：

• 唯一声明原则：仅在主模块（启动模块） 中定义并注册核心过滤器，其他业务模块不声明任何@Component Filter；
• 模块解耦设计：将通用过滤逻辑封装为可复用的工具类（如RequestResponseLogger），由主模块的Filter调用，而非跨模块复制Filter类；
• 显式控制注册：若必须在某子模块提供Filter，应禁用其自动注册，并在主模块中手动注入与配置：

// 在主模块中（如Application.java同包或配置类）
@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean loggingFilterRegistration() {
        FilterRegistrationBean registration = new FilterRegistrationBean<>();
        registration.setFilter(new LoggingFilter()); // 显式构造，避免@Component扫描
        registration.setOrder(Ordered.HIGHEST_PRECEDENCE); // 控制顺序
        registration.addUrlPatterns("/api/*");
        return registration;
    }
}

• 避免@WebFilter陷阱：@WebFilter需配合@ServletComponentScan生效，而该注解默认扫描启动类所在包——若多个模块的Filter类被意外包含在扫描路径中，仍将被重复加载。建议完全弃用@WebFilter，统一使用FilterRegistrationBean方式。

? 额外建议：

• 使用IDEA或Maven命令（如mvn dependency:tree）检查各模块是否因依赖传递引入了重复Filter类；
• 在application.yml中开启调试日志：logging.level.org.springframework.boot.web.servlet=DEBUG，观察Filter注册过程；
• 对Filter添加唯一标识（如@Order或日志前缀），便于定位实际生效的实例。

总之，Spring Boot的“约

定优于配置”在多模块场景下要求开发者更主动地管理横切关注点的归属。过滤器不是模块内私有组件，而是全局HTTP处理链的一环——它的定义权必须集中，注册行为必须明确。