Spring Boot 中Servlet、Filter、Listener 四种注册方式全解析

在Spring Boot项目里，Servlet、Filter、Listener是Java Web的核心组件，和传统Java Web项目比起来，它们的注册方式简单了不少～ Spring Boot提供了四种便捷注册方式，各自适配不同场景，下面给大家详细说说每种方式的实现、特点和注意点。

方式一：通过Spring Bean自动注册（简单也简陋）

这是Spring Boot里最省事的注册方式：Spring Boot启动时，会自动扫描容器里所有属于Servlet、Filter、Listener的Spring Bean，直接把它们注册到嵌入式Servlet容器（比如Tomcat、Jetty）里。

实现示例：

// 1. 注册Servlet（作为Spring Bean）@ComponentpublicclassMyServletextendsHttpServlet{@OverrideprotectedvoiddoGet(HttpServletRequestreq,HttpServletResponseresp)throwsServletException,IOException{resp.getWriter().write("MyServlet Auto Registered");}}// 2. 注册Filter（作为Spring Bean）@ComponentpublicclassMyFilterimplementsFilter{@OverridepublicvoiddoFilter(ServletRequestrequest,ServletResponseresponse,FilterChainchain)throwsIOException,ServletException{System.out.println("MyFilter Auto Filtering");chain.doFilter(request,response);}}// 3. 注册Listener（作为Spring Bean）@ComponentpublicclassMyListenerimplementsServletContextListener{@OverridepublicvoidcontextInitialized(ServletContextEventsce){System.out.println("ServletContext Initialized (Auto Registered)");}}

小问题：默认路径的局限及优化办法

• Servlet：如果只有一个servlet，默认映射路径是/，否则为/bean名称（就是类名首字母小写，比如上面的MyServlet，对应路径就是/myServlet）；
• Filter：默认映射路径是/*，意思是会拦截所有请求；
• Listener：不用手动配路径，它会自动监听Servlet上下文的相关事件（比如启动、销毁）。

优化小技巧：如果想改默认路径，要么结合方式二的RegistrationBean补充配置，要么直接用方式二、三、四，轻松实现自定义路径～

方式二：通过RegistrationBean手动注册（自定义首选）

如果想对Servlet、Filter、Listener做更细致的控制——比如自定义映射路径、设置初始化参数、指定加载顺序，甚至排除某些不需要拦截的路径，方式一就无能为力了。好在Spring Boot提供的RegistrationBean系列类，能让我们实现完全自定义配置，想怎么配就怎么配。

先说下核心类：

• ServletRegistrationBean：专门注册Servlet，映射路径、初始化参数、加载顺序都能配；
• FilterRegistrationBean：注册Filter专用，除了路径，还能配拦截规则、关联指定Servlet等；
• ServletListenerRegistrationBean：注册Listener，能设置Listener实例和启动顺序。

拿Filter举个例子（其他两种组件用法类似）：

@ConfigurationpublicclassWebConfig{// 注册Filter，自定义路径和初始化参数@BeanpublicFilterRegistrationBean<MyFilter>myFilterRegistrationBean(){FilterRegistrationBean<MyFilter>registrationBean=newFilterRegistrationBean<>();registrationBean.setFilter(newMyFilter());// 设置Filter实例registrationBean.addUrlPatterns("/api/*");// 自定义映射路径（仅拦截/api下的请求）registrationBean.setInitParameter("filterName","myFilter");// 初始化参数registrationBean.setOrder(1);// 设置加载顺序（值越小，加载越早）returnregistrationBean;}// 注册Servlet，自定义路径和初始化参数@BeanpublicServletRegistrationBean<MyServlet>myServletRegistrationBean(){ServletRegistrationBean<MyServlet>registrationBean=newServletRegistrationBean<>();registrationBean.setServlet(newMyServlet());registrationBean.addUrlMappings("/myServlet/custom");// 自定义映射路径registrationBean.setInitParameter("servletName","myServlet");registrationBean.setLoadOnStartup(1);// 启动时加载returnregistrationBean;}// 注册Listener@BeanpublicServletListenerRegistrationBean<MyListener>myListenerRegistrationBean(){ServletListenerRegistrationBean<MyListener>registrationBean=newServletListenerRegistrationBean<>();registrationBean.setListener(newMyListener());returnregistrationBean;}}

方式三：使用@ServletRegistration和@FilterRegistration注解注册

这是方式二（RegistrationBean手动注册）的注解替代方案，直接用Spring Boot提供的@ServletRegistration和@FilterRegistration两个注解，标注在Servlet和Filter类上，就能完成路径、初始化参数等自定义配置，适配喜欢注解式开发的场景。

核心说明：

• @ServletRegistration：专门用于注册Servlet，可配置映射路径、启动加载顺序、初始化参数等，功能与ServletRegistrationBean一致；
• @FilterRegistration：专门用于注册Filter，可配置映射路径、拦截规则、初始化参数等，功能与FilterRegistrationBean一致；
• 局限性：仅支持Servlet和Filter，Listener无法用这两个注解注册，需要spring-boot 3.5.x 及以上版本。

实现示例：

// 用@ServletRegistration注册Servlet，替代ServletRegistrationBean@ServletRegistration(urlPatterns="/myServlet/annotation",loadOnStartup=1)@ComponentpublicclassMyServletextendsHttpServlet{// 实现逻辑...}// 用@FilterRegistration注册Filter，替代FilterRegistrationBean@FilterRegistration(urlPatterns="/api/*",initParams={@InitParam(name="filterName",value="myFilter")})@ComponentpublicclassMyFilterimplementsFilter{// 实现逻辑...}

方式四：使用Servlet3.0注解配合@ServletComponentScan

Servlet3.0规范本身就提供了三个注解——@WebServlet、@WebFilter、@WebListener，直接标注在组件类上，就能指定路径、名称这些配置。不过在Spring Boot项目里，得在启动类上加个@ServletComponentScan注解，开启对这三个注解的扫描，组件才能被自动注册上。

示例如下：

// 1. 启动类添加@ServletComponentScan，指定扫描包（可选，默认扫描当前包及子包）@SpringBootApplication@ServletComponentScan(basePackages="com.example.web.component")publicclassApplication{publicstaticvoidmain(String[]args){SpringApplication.run(Application.class,args);}}// 2. 用@WebServlet注册Servlet@WebServlet(urlPatterns="/webServlet",name="WebServletDemo",loadOnStartup=1)publicclassWebServletDemoextendsHttpServlet{@OverrideprotectedvoiddoGet(HttpServletRequestreq,HttpServletResponseresp)throwsServletException,IOException{resp.getWriter().write("WebServlet Annotated Registered");}}// 3. 用@WebFilter注册Filter@WebFilter(urlPatterns="/web/*",filterName="WebFilterDemo")publicclassWebFilterDemoimplementsFilter{@OverridepublicvoiddoFilter(ServletRequestrequest,ServletResponseresponse,FilterChainchain)throwsIOException,ServletException{System.out.println("WebFilter Annotated Filtering");chain.doFilter(request,response);}}// 4. 用@WebListener注册Listener@WebListenerpublicclassWebListenerDemoimplementsServletContextListener{@OverridepublicvoidcontextInitialized(ServletContextEventsce){System.out.println("ServletContext Initialized (WebListener Annotated)");}}

注意事项

• @ServletComponentScan一定要加在Spring Boot启动类上，不然扫描不到这三个注解标注的组件；
• 这种方式和方式一不冲突，如果一个组件既加了@Component，又加了@WebServlet（等）注解，Spring Boot会优先用@WebServlet里的配置（比如路径）；
• 需要Servlet3.0及以上版本的嵌入式容器，不过Spring Boot默认集成的Tomcat等容器都支持。

四种方式对比及适用场景