XSS过滤器实战：从零到一构建SpringBoot安全防护网（含常见坑点解析）

XSS过滤器实战：从零到一构建SpringBoot安全防护网（含常见坑点解析）

最近在帮一个朋友排查他们项目的安全漏洞，发现一个挺典型的问题：用户在前端编辑器里上传了一张图片，结果图片里居然嵌入了恶意脚本。更麻烦的是，这个脚本是通过multipart/form-data方式提交的，他们之前写的那个XSS过滤器居然没生效。最后排查下来，发现是过滤器在处理文件上传请求时，直接把MultipartHttpServletRequest给漏掉了。这个经历让我意识到，很多开发者虽然知道XSS攻击的危害，也尝试过自己写过滤器来防护，但往往会在一些细节上栽跟头，特别是当项目里混用了普通表单提交和文件上传时。

这篇文章就是为你准备的，无论你是刚开始接触SpringBoot安全防护的新手，还是已经写过几个过滤器但总觉得不够完善的中级开发者。我会带你从零开始，搭建一个真正能覆盖各种场景的XSS过滤器。我们不止要实现基础功能，更要深入那些容易踩坑的地方——比如文件上传请求的处理、过滤器的执行顺序、以及如何确保过滤策略既安全又不影响正常业务。你会发现，构建一个健壮的防护网，远不止是写几行替换特殊字符的代码那么简单。

1. 理解XSS攻击与过滤器的核心原理

在动手写代码之前，我们得先搞清楚两件事：XSS攻击到底是怎么发生的，以及Servlet过滤器为什么能拦截它。很多人一提到XSS，就想到<script>alert('xss')</script>这种经典弹窗，但实际上攻击者的手段要狡猾得多。

跨站脚本攻击的本质，是攻击者将恶意脚本注入到原本可信的网页中，当其他用户浏览该页面时，嵌入的脚本就会被执行。根据脚本注入和执行的时机不同，XSS主要分为三类：

• 反射型XSS：恶意脚本作为请求的一部分发送给服务器，服务器未经处理就直接返回给浏览器执行。常见于搜索框、错误提示页等场景。
• 存储型XSS：恶意脚本被持久化存储到服务器数据库或文件中，当其他用户访问包含该数据的页面时触发。论坛发帖、用户评论是重灾区。
• DOM型XSS：攻击发生在客户端的DOM解析阶段，不经过服务器。前端JavaScript直接操作URL参数或本地存储时处理不当，就可能中招。

我们的过滤器主要防范前两种，因为它们的数据流经后端服务器。而Servlet过滤器就像一个安检门，所有进入控制器的HTTP请求和离开的响应都要经过它。我们可以在这里对请求参数、头信息进行“清洗”，把危险的字符替换掉。

注意：过滤是一种重要的缓解手段，但绝非银弹。最根本的防护应该遵循“输入验证，输出编码”的原则。过滤器属于输入验证环节的补充，尤其是在遗留系统或快速开发中，它能提供一层有效的安全垫。

那么，一个基本的XSS过滤策略是什么样子的呢？通常是把那些可能被用来构造脚本的HTML特殊字符，转换成它们的HTML实体编码。这样，即使用户输入了<script>，存入数据库和返回给前端的也会是安全的<script>，浏览器会将其显示为普通文本，而不会解析为标签。

下面这个表格对比了常见危险字符及其对应的实体编码，这是我们过滤器逻辑的基础：

理解了这些，我们就可以开始构思过滤器的骨架了。它需要做两件事：第一，拦截所有请求；第二，对请求中的参数值进行遍历和清洗。在SpringBoot中，我们通过实现javax.servlet.Filter接口并注册它来完成。

2. 构建核心：可扩展的XSS过滤处理器

直接上手写一个把所有逻辑都塞进doFilter方法的类，很快你就会遇到维护的噩梦。更好的做法是职责分离，我们将过滤器的调度逻辑和具体的清洗逻辑拆开。这里我设计了一个XssRequestWrapper和一个独立的XssFilter。

首先，创建XssRequestWrapper类，它继承自HttpServletRequestWrapper。它的核心作用是包装原始的HttpServletRequest对象，并重写其获取参数的方法，在我们重写的方法里执行过滤操作。这样，后续的控制器从request对象里取到的参数，就已经是“干净”的了。

import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletRequestWrapper; import java.util.*; public class XssRequestWrapper extends HttpServletRequestWrapper { public XssRequestWrapper(HttpServletRequest request) { super(request); } @Override public String getParameter(String name) { String value = super.getParameter(name); return cleanXss(value); } @Override public String[] getParameterValues(String name) { String[] values = super.getParameterValues(name); if (values == null) { return null; } int count = values.length; String[] encodedValues = new String[count]; for (int i = 0; i < count; i++) { encodedValues[i] = cleanXss(values[i]); } return encodedValues; } @Override public Map<String, String[]> getParameterMap() { Map<String, String[]> parameterMap = super.getParameterMap(); Map<String, String[]> cleanedMap = new HashMap<>(parameterMap.size()); for (Map.Entry<String, String[]> entry : parameterMap.entrySet()) { String[] originalValues = entry.getValue(); if (originalValues != null) { String[] cleanedValues = new String[originalValues.length]; for (int i = 0; i < originalValues.length; i++) { cleanedValues[i] = cleanXss(originalValues[i]); } cleanedMap.put(entry.getKey(), cleanedValues); } else { cleanedMap.put(entry.getKey(), null); } } return Collections.unmodifiableMap(cleanedMap); } @Override public String getHeader(String name) { String value = super.getHeader(name); return cleanXss(value); } private String cleanXss(String value) { if (value == null || value.isEmpty()) { return value; } // 使用更高效且避免正则表达式递归问题的StringBuilder StringBuilder sb = new StringBuilder(value.length()); for (int i = 0; i < value.length(); i++) { char c = value.charAt(i); switch (c) { case '<': sb.append("&lt;"); break; case '>': sb.append("&gt;"); break; case '&': sb.append("&amp;"); break; case '"': sb.append("&quot;"); break; case '\'': sb.append("&#39;"); break; case '/': sb.append("&#47;"); break; case '(': sb.append("&#40;"); break; case ')': sb.append("&#41;"); break; // 可根据需要扩展更多字符 default: sb.append(c); } } return sb.toString(); } }

我为什么用StringBuilder和switch，而不是一堆replaceAll？因为replaceAll内部使用正则表达式，在频繁调用或处理长文本时性能开销较大，且某些极端嵌套的字符串可能导致栈溢出。上面的写法是O(n)复杂度，更稳定高效。

提示：cleanXss方法中的替换规则需要根据你的实际业务来调整。过于严格可能会破坏正常输入（比如一篇讲解HTML的技术文章），过于宽松则可能留下漏洞。一个常见的做法是提供配置项，允许针对不同的接口或参数名采用不同的过滤策略。

有了包装器，过滤器的doFilter方法就非常简洁了：

import javax.servlet.*; import javax.servlet.http.HttpServletRequest; import java.io.IOException; @Component public class XssFilter implements Filter { @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest = (HttpServletRequest) request; // 使用我们自定义的包装器包装原始请求 XssRequestWrapper wrappedRequest = new XssRequestWrapper(httpRequest); // 将包装后的请求传递给后续过滤器或控制器 chain.doFilter(wrappedRequest, response); } @Override public void init(FilterConfig filterConfig) throws ServletException { // 初始化逻辑，如果需要的话 } @Override public void destroy() { // 清理逻辑，如果需要的话 } }

看起来很简单，对吧？但如果你现在就把它部署到有文件上传功能的应用里，马上就会遇到第一个大坑。

3. 攻克难点：处理multipart/form-data文件上传请求

当你通过表单上传文件时，Content-Type通常是multipart/form-data。这种请求的body结构复杂，包含了二进制文件流和文本字段。Spring MVC通过一个叫MultipartResolver的组件来解析这种请求，将其转化为一个MultipartHttpServletRequest对象，这样我们才能方便地通过getParameter或getFile方法获取内容。

问题来了：如果你直接用上面的XssRequestWrapper去包装一个MultipartHttpServletRequest，会发生什么？在过滤器链中，MultipartResolver的解析通常发生在我们的XssFilter之后。这意味着，当请求到达我们的过滤器时，它还是一个原始的、未解析的HttpServletRequest，你调用getParameter什么也拿不到。而等它被后续的MultipartResolver解析后，包装器已经不起作用了，因为解析过程会读取原始的输入流并生成新的request对象。

解决方案是：在我们的过滤器里，先判断如果是文件上传请求，就主动调用MultipartResolver进行解析，然后对我们的包装器进行“增强”，让它能处理解析后的参数。同时，要确保MultipartResolver这个Bean能在过滤器中被正确获取。

首先，我们需要一个工具类来在非Spring管理Bean（如Filter）中获取Spring容器里的Bean。

import org.springframework.beans.BeansException; import org.springframework.context.ApplicationContext; import org.springframework.context.ApplicationContextAware; import org.springframework.stereotype.Component; @Component public class SpringContextHolder implements ApplicationContextAware { private static ApplicationContext applicationContext; @Override public void setApplicationContext(ApplicationContext applicationContext) throws BeansException { SpringContextHolder.applicationContext = applicationContext; } public static <T> T getBean(Class<T> clazz) { return applicationContext.getBean(clazz); } public static Object getBean(String name) { return applicationContext.getBean(name); } }

然后，改造我们的XssFilter：

import org.springframework.web.multipart.MultipartHttpServletRequest; import org.springframework.web.multipart.MultipartResolver; import javax.servlet.*; import javax.servlet.http.HttpServletRequest; import java.io.IOException; @Component public class XssFilter implements Filter { private MultipartResolver multipartResolver; @Override public void init(FilterConfig filterConfig) { // 在初始化时从Spring容器获取MultipartResolver this.multipartResolver = SpringContextHolder.getBean(MultipartResolver.class); if (this.multipartResolver == null) { throw new IllegalStateException("MultipartResolver not found in Spring ApplicationContext. Please check your configuration."); } } @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest = (HttpServletRequest) request; String contentType = httpRequest.getContentType(); XssRequestWrapper wrappedRequest; if (contentType != null && contentType.toLowerCase().startsWith("multipart/form-data")) { // 1. 解析multipart请求 MultipartHttpServletRequest multipartRequest = multipartResolver.resolveMultipart(httpRequest); // 2. 创建包装器，包装解析后的请求 wrappedRequest = new XssRequestWrapper(multipartRequest); // 3. 重要：清理multipart资源，防止内存泄漏 // 注意：清理工作通常在请求处理完成后进行，这里需要确保在后续流程结束后清理 // 一种做法是使用try-finally，或者使用一个一次性包装器，在finally中清理 try { chain.doFilter(wrappedRequest, response); } finally { multipartResolver.cleanupMultipart(multipartRequest); } } else { // 普通请求，直接包装 wrappedRequest = new XssRequestWrapper(httpRequest); chain.doFilter(wrappedRequest, response); } } }

这里有几个关键点：

1. 时机：我们在过滤器里提前解析了multipart请求，使得包装器能对解析后的参数进行过滤。
2. 资源清理：MultipartResolver.resolveMultipart()可能会创建临时文件或占用内存，必须在请求处理完毕后调用cleanupMultipart()进行清理，否则会导致资源泄漏。我们将chain.doFilter()放在try块中，并在finally里确保清理。
3. Bean获取：Filter本身不是由Spring容器通过依赖注入管理的（尽管加了@Component，但它的实例化可能早于Spring上下文完成），所以不能在字段上用@Autowired。我们在init方法中通过工具类获取。

注意：这种在过滤器中处理multipart请求的方式，要求你的MultipartResolver配置（如最大文件大小）必须正确，并且要确保没有其他过滤器或组件在你之前尝试读取请求体，否则可能导致输入流被消费而解析失败。

4. 精准注册与配置：让过滤器在正确的位置生效

写好过滤器只是成功了一半，如何把它“安装”到SpringBoot应用中，并确保它在正确的时间、以正确的顺序处理正确的请求，是另一半挑战。我们使用FilterRegistrationBean进行注册，它提供了细粒度的控制。

创建一个配置类XssFilterConfig：

import org.springframework.boot.web.servlet.FilterRegistrationBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import javax.servlet.DispatcherType; import java.util.EnumSet; @Configuration public class XssFilterConfig { @Bean public FilterRegistrationBean<XssFilter> xssFilterRegistration(XssFilter xssFilter) { FilterRegistrationBean<XssFilter> registration = new FilterRegistrationBean<>(); registration.setFilter(xssFilter); registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 10); // 设置一个较高的优先级 registration.addUrlPatterns("/*"); // 拦截所有请求 registration.setDispatcherTypes(EnumSet.of(DispatcherType.REQUEST, DispatcherType.FORWARD)); registration.setName("xssFilter"); // 可选：添加初始化参数 // registration.addInitParameter("excludeUrls", "/api/public/*,/health"); return registration; } }

我们来详细拆解每个配置项的意义：

• setOrder(int order)：这是最容易出问题的地方。过滤器的执行顺序至关重要。如果你的应用还有字符编码过滤器、日志过滤器、认证过滤器等，XSS过滤应该在字符编码转换之后，业务逻辑（如认证、授权）之前。因为过滤需要处理正确的字符串，且应在执行业务逻辑前确保输入安全。Ordered.HIGHEST_PRECEDENCE是最高优先级（值最小），我们加10是为了给编码过滤器（通常优先级很高）留出空间。
• addUrlPatterns(String... urlPatterns)：定义过滤器作用的URL模式。/*表示根路径下的所有请求。你也可以排除一些不需要过滤的静态资源或公开API，比如registration.addUrlPatterns("/api/*", "/admin/*");。
• setDispatcherTypes(EnumSet<DispatcherType> dispatcherTypes)：指定过滤器拦截的请求分发类型。
  • REQUEST：标准的客户端请求。
  • FORWARD：服务器端转发（RequestDispatcher.forward）。如果你的应用有内部转发，且转发后的请求也需要过滤，就要包含它。
  • INCLUDE：服务器端包含。
  • ERROR：错误页面处理。
  • ASYNC：异步请求（Servlet 3.0+）。通常建议包含，以覆盖异步处理场景。
• setName(String name)：给过滤器一个名字，便于日志记录和调试。
• 初始化参数：你可以通过addInitParameter传递配置，然后在过滤器的init方法中读取。例如，可以配置一个排除URL列表，让某些接口跳过XSS过滤。

一个常见的需求是“排除某些接口不过滤”，比如接收富文本内容的接口，过滤会破坏其格式。我们可以这样增强过滤器：

// 在XssFilter中 private List<String> excludeUrls = new ArrayList<>(); @Override public void init(FilterConfig filterConfig) { // ... 获取multipartResolver ... String excludePattern = filterConfig.getInitParameter("excludeUrls"); if (excludePattern != null) { excludeUrls = Arrays.asList(excludePattern.split(",")); } } @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest = (HttpServletRequest) request; String requestURI = httpRequest.getRequestURI(); // 检查当前请求URI是否在排除列表中 for (String excludeUrl : excludeUrls) { // 这里可以使用AntPathMatcher进行更复杂的模式匹配 if (requestURI.startsWith(excludeUrl.trim())) { // 直接放行，不过滤 chain.doFilter(request, response); return; } } // ... 原有的过滤逻辑 ... }

然后在配置中设置：

registration.addInitParameter("excludeUrls", "/api/richtext/save, /upload/image");

5. 避坑指南与高级策略

即使按照上面的步骤完成了过滤器的搭建，在实际项目中你可能还会遇到一些意想不到的问题。这里我总结几个常见的“坑”及其解决方案。

坑点一：过滤导致数据“双重编码”或前端显示异常这是最频繁的反馈。现象是：用户输入<test>，存入数据库变成了<test>，这没问题。但前端显示时，却显示了<test>这个字符串本身，而不是<test>。

• 原因：前端在渲染时，可能使用了错误的输出方法。例如，在Thymeleaf中，使用th:text会自动进行HTML转义，显示为<test>。但如果你用了th:utext（不转义），或者直接用JavaScript的innerHTML属性，那么<就会被直接当成字符串显示。
• 解决：确保前端在显示从后端获取的、已经过过滤的数据时，使用安全的输出方式。对于需要渲染HTML的场景（如富文本编辑器内容），应该不过滤，而是在输出时使用专门的HTML净化库（如Jsoup）进行白名单过滤。

坑点二：对JSON请求体无效我们的过滤器重写了getParameter等方法，但对于application/json类型的POST/PUT请求，参数是在请求体（Body）中，通过@RequestBody注解绑定，不会走getParameter。因此，这类请求的XSS防护是无效的。

• 解决：
  1. 方案A（全局）：使用Spring的@ControllerAdvice和RequestBodyAdvice接口，在请求体被反序列化成对象之前，对JSON字符串进行扫描和清洗。这种方式更彻底，但实现复杂，且要小心不要破坏JSON结构。
  2. 方案B（局部）：在DTO对象的字段上使用JSR-303验证注解配合自定义校验器，或者使用像@SafeHtml这样的注解（需要Hibernate Validator额外库）。这种方式更灵活，但需要在每个字段上标注。
  3. 方案C（推荐组合）：对于内部可信的API，可以依赖前端框架（如React/Vue）的自动转义特性。对于暴露给第三方或不可信客户端的API，采用方案A或B。

坑点三：性能开销每个请求、每个参数都要进行字符串遍历和替换，在高并发场景下可能成为瓶颈。

• 优化：
  • 缓存：对于频繁出现的、固定的恶意模式，可以预编译正则表达式（如果使用正则的话）或使用Trie树等数据结构进行模式匹配。
  • 采样或异步：对于性能极其敏感的核心链路，可以考虑只对可疑请求（如包含特定关键词）进行深度过滤，或者将过滤日志记录改为异步操作。
  • 使用成熟库：考虑使用经过优化的开源库，如OWASP Java Encoder Project，它提供了上下文敏感的编码方法，比简单的全局替换更安全、更高效。

坑点四：绕过过滤的奇技淫巧攻击者会尝试使用各种编码、大小写混淆、HTML实体嵌套等方式绕过简单的字符串替换。

• 加固：
  • 不要只过滤<script>，要关注所有可能触发脚本执行的上下文，如HTML标签、属性、CSS、JavaScript URL等。
  • 使用白名单而非黑名单。定义一个允许的字符集（如字母、数字、常用标点），将不在白名单中的字符过滤或编码。这比试图列出所有危险字符更安全。
  • 参考OWASP的Cheat Sheet，使用上下文相关的输出编码。在HTML正文、HTML属性、JavaScript、CSS、URL等不同位置，需要转义的字符是不同的。

最后，记住一点：XSS过滤器是防御纵深中的一层，而不是全部。它应该与以下措施结合使用：

• 在HTTP响应头中设置Content-Security-Policy (CSP)，严格限制页面可以加载和执行哪些资源。
• 为Cookie设置HttpOnly和Secure属性。
• 对用户输入进行严格的、符合业务逻辑的验证（长度、类型、格式）。
• 在输出到不同上下文（HTML、JS、URL）时，使用对应的编码函数。

我在最近的一个项目中，就遇到了一个通过SVG文件上传绕过过滤的案例。攻击者将脚本藏在SVG文件的<script>标签里。普通的文件内容检查很难发现，而如果浏览器直接渲染这个SVG，脚本就会执行。最终，我们除了在过滤器中加强了对文件内容类型的检查，还在服务端存储时重命名了文件，并配置了CSP策略禁止内联脚本，才算是堵住了这个漏洞。安全这件事，永远需要多想一想“如果…会怎样”。