1. 项目概述：为什么你的SpringBoot应用需要一个XSS过滤器？

做Web开发这些年，我见过太多因为XSS（跨站脚本攻击）漏洞导致的“惨案”。从用户留言板里突然弹出的恶作剧弹窗，到被悄无声息盗走的用户Cookie，再到页面被恶意跳转到钓鱼网站，这些问题的根源往往不是业务逻辑有多复杂，而是开发者在处理用户输入时，少了一层“净化”的工序。尤其是在SpringBoot这种快速开发框架下，我们往往专注于实现业务功能，却容易忽略Web安全这个基础防线。

XSS攻击的原理其实不复杂，简单说就是攻击者把恶意脚本代码“混”在正常的用户输入里（比如评论、昵称、搜索关键词），提交给服务器。如果服务器没有对这些输入进行过滤或转义，就直接存储并展示给其他用户，那么其他用户的浏览器就会把这些恶意脚本当作正常的页面代码来执行。这就好比你把一个陌生人递过来的、没经过安检的包裹直接放进了自己家，风险可想而知。

SpringBoot项目实战中，集成一个全局的XSS防御机制，是每个项目上线前必须完成的“规定动作”。今天要聊的，就是一个能在5分钟内为你的SpringBoot应用“穿上防弹衣”的实战方案。它不依赖任何重量级的安全框架，核心就是一个自定义的过滤器（Filter），配合一个精心编写的HTML过滤器，实现对请求参数的全局清洗。我会把完整的、可运行的代码示例拆开揉碎了讲给你听，从原理到避坑，保证你拿过去就能用。

2. XSS攻击的本质与SpringBoot的防御盲区

在动手写代码之前，我们必须先搞清楚敌人是谁，以及我们现有的防御体系哪里最薄弱。很多开发者以为用了SpringBoot，安全就高枕无忧了，其实不然。

2.1 XSS攻击的三种常见“姿势”

XSS攻击主要分为三类：反射型、存储型和DOM型。我们的防御方案需要能覆盖前两种最常见的情况。

反射型XSS：这种攻击像是“一次性钓鱼”。恶意脚本作为请求参数（比如在URL里）发送给服务器，服务器未经处理就直接把参数内容嵌入了响应页面中。典型的场景是搜索框，攻击者构造一个包含恶意脚本的搜索链接发给受害者，受害者一点击，脚本就在其浏览器中执行了。它的数据不存储在服务器端。

存储型XSS：这才是“心腹大患”。攻击者将恶意脚本提交到服务器（比如写入数据库的论坛帖子、用户昵称），当其他用户浏览到这些被“污染”的数据时，脚本就会执行。它的危害是持久性的，影响所有访问相关页面的用户。

DOM型XSS：这种攻击发生在客户端，恶意脚本通过修改页面的DOM结构来实施，不经过服务器端处理。防御它主要靠前端对innerHTML、document.write等危险操作的谨慎使用，以及实施严格的CSP（内容安全策略）。我们今天的服务器端过滤器对它的直接防御有限，但良好的编码习惯可以避免。

2.2 SpringBoot的默认安全配置与我们的需求

Spring Boot Security 确实提供了一套强大的安全框架，但它更侧重于身份认证（Authentication）和授权（Authorization），比如防止未登录访问、控制页面权限。对于XSS这种“输入净化”层面的问题，它并没有开箱即用的、针对请求体内容进行字符串级别过滤的全局解决方案。

我们常见的做法是在每个Controller的方法参数里，用@RequestParam或@RequestBody接收数据后，手动调用工具类进行转义。这种方法有两大弊端：一是容易遗漏，哪个开发人员敢保证自己每次都能记得？二是代码侵入性强，业务代码里混杂着安全逻辑，不优雅。

因此，我们需要一个全局的、非侵入的、对业务透明的解决方案。过滤器（Filter）正是Servlet规范中用于在请求到达Servlet之前和响应发出之后进行处理的组件，它是实现这个需求的绝佳位置。我们的目标就是创建一个XSS过滤器，在HTTP请求刚进入应用时，就对所有参数进行“消毒”处理。

3. 核心防御方案设计：全局过滤器的实现思路

整个防御体系的核心是一个自定义的XssFilter和一个包装了HttpServletRequest的XssHttpServletRequestWrapper。思路是“偷梁换柱”：当请求经过我们的过滤器时，我们不把原始的HttpServletRequest对象传递给后面的Controller，而是传递一个被我们包装过的、重写了关键方法（如getParameter，getInputStream）的对象。这样，Controller从请求对象中获取的任何参数，都已经是经过我们清洗过的“安全数据”。

3.1 方案选型：为什么是过滤器而不是拦截器或AOP？

这里可能有人会问，Spring里不是还有拦截器（Interceptor）和面向切面编程（AOP）吗？为什么偏偏选过滤器？

1. 执行时机最早：Filter是Servlet层面的组件，它的执行在Spring MVC的DispatcherServlet之前。这意味着在请求进入Spring框架之前，我们就能完成过滤，范围最广，能处理静态资源请求等。
2. 对请求体（Request Body）处理更友好：拦截器和AOP通常作用于Controller方法被调用时，此时请求参数可能已经被Spring MVC的HttpMessageConverter（如处理JSON的MappingJackson2HttpMessageConverter）解析成了Java对象。要修改这些对象里的数据比较麻烦。而过滤器可以在流级别直接对原始的请求体数据进行处理。
3. 更通用：Filter是Java EE标准，不依赖于Spring，理论上更通用。虽然我们在Spring Boot里用，但这个思想可以迁移。

当然，这个方案也有一个需要特别注意的点：请求体（InputStream）在Servlet规范中默认只能读取一次。我们的包装器需要读取流并进行清洗，那么后续的Controller（或框架）再读取时就会遇到流已关闭的问题。因此，我们必须在包装器里把清洗后的数据缓存起来，并提供一个可以重复读取的InputStream。这是实现过程中的一个关键细节。

3.2 整体架构与流程

整个方案的代码结构清晰，主要包含以下几个部分：

1. XssFilter：入口过滤器，负责判断当前请求是否需要过滤（比如排除一些特定的URL），并将原请求对象替换为我们的包装器。
2. XssHttpServletRequestWrapper：HttpServletRequestWrapper的子类。这是核心，我们通过重写getParameter、getParameterValues、getHeader、getInputStream等方法，在这些方法返回数据前，插入我们的清洗逻辑。
3. EscapeUtil / HTMLFilter：实际的清洗工具类。EscapeUtil提供简单的转义（Escape）和清理（Clean）方法。HTMLFilter则是一个更复杂的、可配置的HTML标签过滤器，它可以根据白名单决定保留哪些安全的HTML标签和属性。
4. FilterConfig：Spring Boot配置类，用于将我们自定义的XssFilter注册到Spring容器中，并可以通过application.yml配置文件来灵活控制过滤器的开关、排除的URL等。

流程图可以简单理解为：HTTP Request->XssFilter-> (如果需要过滤) 将Request对象替换为XssHttpServletRequestWrapper->Spring MVC DispatcherServlet->Controller。Controller感知不到包装过程，它拿到的一切参数都是干净的。

4. 代码逐行精讲与避坑指南

接下来，我们深入到代码内部。我会把核心代码拆解出来，并附上我实际项目中踩过的坑和总结的经验。

4.1 基石：HTML过滤工具类（HTMLFilter）

这个类是整个清洗逻辑的发动机。它来自开源项目OWASP Java HTML Sanitizer的思想，是一个功能相对完善的白名单过滤器。代码较长，但核心逻辑是使用正则表达式匹配HTML标签和属性，然后根据预定义的白名单决定是保留、移除还是转义。

关键配置点（在无参构造函数中）：

public HTMLFilter() { vAllowed = new HashMap<>(); final ArrayList<String> a_atts = new ArrayList<>(); a_atts.add("href"); a_atts.add("target"); // 允许<a>标签有href和target属性 vAllowed.put("a", a_atts); final ArrayList<String> img_atts = new ArrayList<>(); img_atts.add("src"); img_atts.add("width"); img_atts.add("height"); img_atts.add("alt"); // 允许<img>标签有这些属性 vAllowed.put("img", img_atts); // 允许<b>, <strong>, <i>, <em>标签，但不允许它们有任何属性（空列表） final ArrayList<String> no_atts = new ArrayList<>(); vAllowed.put("b", no_atts); vAllowed.put("strong", no_atts); vAllowed.put("i", no_atts); vAllowed.put("em", no_atts); vSelfClosingTags = new String[] { "img" }; // 自闭合标签 vNeedClosingTags = new String[] { "a", "b", "strong", "i", "em" }; // 需要闭合的标签 vAllowedProtocols = new String[] { "http", "mailto", "https" }; // 链接允许的协议 // ... 其他配置 }

实操心得1：白名单策略比黑名单更可靠千万不要试图列一个“所有危险标签”的黑名单去过滤，因为HTML和JavaScript的变形组合方式太多了（比如大小写混合、嵌套无效标签、利用HTML实体编码等），防不胜防。最安全的做法是采用白名单，只允许已知安全的标签和属性通过。上面的配置就是一个非常保守的白名单，只允许一些基本的、用于排版的标签。对于富文本编辑器（如博客内容）的场景，你需要根据业务需求谨慎地扩充这个白名单，比如增加p,span,ul,li等，但一定要避免加入script,style,iframe,onclick这类高危标签或事件属性。

实操心得2：注意JSON数据中的双引号在HTMLFilter的encodeQuotes方法中，有一段注释：“不替换双引号为"，防止json格式无效”。这是因为JSON格式严格依赖双引号"来包裹属性名和字符串值。如果我们将双引号转义，会导致后续的Jackson等JSON解析器报错。因此，在过滤JSON请求体时，这个细节至关重要。我们的清洗策略是移除或转义整个脚本标签，而不是破坏JSON的结构。

4.2 核心包装器：XssHttpServletRequestWrapper

这个类是拦截和清洗数据的关键。它继承了HttpServletRequestWrapper，可以重写父类的方法。

public class XssHttpServletRequestWrapper extends HttpServletRequestWrapper { public XssHttpServletRequestWrapper(HttpServletRequest request) { super(request); } @Override public String[] getParameterValues(String name) { String[] values = super.getParameterValues(name); if (values != null) { String[] escapesValues = new String[values.length]; for (int i = 0; i < values.length; i++) { // 关键清洗操作：清理XSS并去除前后空格 escapesValues[i] = EscapeUtil.clean(values[i]).trim(); } return escapesValues; } return super.getParameterValues(name); } @Override public ServletInputStream getInputStream() throws IOException { // 1. 判断是否为JSON请求 if (!isJsonRequest()) { return super.getInputStream(); // 非JSON，按普通请求处理（如果需要过滤普通表单，可在此扩展） } // 2. 读取原始请求体 String json = IOUtils.toString(super.getInputStream(), StandardCharsets.UTF_8); if (StringUtils.isEmpty(json)) { return super.getInputStream(); } // 3. 对JSON字符串进行XSS清洗 json = EscapeUtil.clean(json).trim(); // 4. 将清洗后的字符串重新封装为InputStream byte[] jsonBytes = json.getBytes(StandardCharsets.UTF_8); final ByteArrayInputStream bis = new ByteArrayInputStream(jsonBytes); return new ServletInputStream() { // ... 实现InputStream的抽象方法，基于bis操作 @Override public int read() throws IOException { return bis.read(); } // ... isFinished, isReady, setReadListener 等方法 }; } // ... 同样需要重写 getParameter, getHeader 等方法 }

避坑指南1：请求体只能读一次这是实现中最容易出错的地方。HttpServletRequest的getInputStream()方法返回的流，默认只能读取一次。在我们的getInputStream()方法里，我们通过IOUtils.toString把流读完了，那么后续Spring MVC框架来解析@RequestBody时就会拿到一个空流。所以，我们必须把清洗后的JSON字符串（jsonBytes）缓存到一个新的ByteArrayInputStream中，并返回这个新流的包装。这样，无论后面读多少次，数据都还在。

避坑指南2：区分请求类型我们重写的getInputStream()中，首先判断!isJsonRequest()。这里假设只有Content-Type为application/json的请求体需要特殊处理（因为要保护JSON结构）。对于传统的application/x-www-form-urlencoded表单提交，其参数是通过getParameter()方法获取的，已经在上面重写的方法里处理了。如果你的应用还有multipart/form-data（文件上传），需要额外注意，文件内容本身通常不需要进行HTML清洗，但文件名（Filename）可能需要。这部分可以根据业务情况在过滤器中排除或单独处理。

4.3 入口与调度：XssFilter 与 FilterConfig

XssFilter是过滤器的实现，它决定哪些请求需要被处理。

public class XssFilter implements Filter { private List<String> excludes = new ArrayList<>(); // 排除的URL模式 @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest req = (HttpServletRequest) request; if (handleExcludeURL(req)) { chain.doFilter(request, response); // 直接放行 return; } // 使用包装器 XssHttpServletRequestWrapper xssRequest = new XssHttpServletRequestWrapper(req); chain.doFilter(xssRequest, response); } private boolean handleExcludeURL(HttpServletRequest request) { String url = request.getServletPath(); String method = request.getMethod(); // 示例：GET和DELETE请求不过滤（根据场景决定，通常GET也可能有XSS风险） if (method == null || HttpMethod.GET.matches(method) || HttpMethod.DELETE.matches(method)) { return true; } // 检查是否在排除列表里 return StringUtils.matches(url, excludes); } }

FilterConfig是Spring Boot的配置类，用于将过滤器注入到Servlet容器。

@Configuration public class FilterConfig { @Value("${xss.enabled:true}") private String enabled; @Value("${xss.excludes:/system/notice,/api/upload}") private String excludes; @Value("${xss.urlPatterns:/*}") private String urlPatterns; @Bean @ConditionalOnProperty(value = "xss.enabled", havingValue = "true") public FilterRegistrationBean<XssFilter> xssFilterRegistration() { FilterRegistrationBean<XssFilter> registration = new FilterRegistrationBean<>(); registration.setFilter(new XssFilter()); registration.addUrlPatterns(StringUtils.split(urlPatterns, ",")); registration.setName("xssFilter"); registration.setOrder(Ordered.HIGHEST_PRECEDENCE); // 设置最高优先级，确保最先执行 Map<String, String> initParameters = new HashMap<>(); initParameters.put("excludes", excludes); registration.setInitParameters(initParameters); return registration; } }

配置经验：

1. @ConditionalOnProperty：这个注解非常好用，它允许我们通过application.yml中的xss.enabled开关来动态启用或禁用整个过滤器。在测试环境或排查问题时，可以临时关闭。
2. Ordered.HIGHEST_PRECEDENCE：将过滤器的执行顺序设为最高。这很重要，要确保我们的清洗操作在其他可能修改请求的过滤器（比如字符编码过滤器）之后执行，但在Spring Security等安全框架之前执行。顺序不对可能导致清洗失效或引发其他问题。
3. 排除列表（excludes）：一定要留出排除接口。例如，某些接受富文本HTML内容（如文章发布）的接口，或者文件上传接口，我们可能不希望进行严格的标签过滤，而是交由更专门的内容审核或前端渲染库处理。

对应的application.yml配置：

xss: enabled: true excludes: /system/notice,/api/rich-text/save # 多个路径用逗号分隔 urlPatterns: /* # 默认过滤所有请求

5. 完整集成、测试与效果验证

现在，我们把所有零件组装起来，并在一个Spring Boot项目中测试。

5.1 项目结构与依赖

创建一个标准的Spring Boot项目，确保pom.xml中包含Web依赖。

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- 可选，用于测试 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency>

将前面提到的HTMLFilter、EscapeUtil、XssHttpServletRequestWrapper、XssFilter、FilterConfig等类放入你的项目源码目录中。通常，过滤器相关类放在com.yourproject.filter包下，工具类放在com.yourproject.utils包下。

5.2 编写测试Controller

我们创建一个简单的Controller来验证过滤效果。

@RestController @Slf4j public class TestController { // 测试1：普通表单POST，参数会被过滤 @PostMapping("/test/form") public String testForm(@RequestParam String content) { log.info("接收到的内容: {}", content); // 观察日志，这里的content应该是被清洗过的，例如<script>alert(1)</script>会被过滤掉标签 return "处理后的内容: " + content; } // 测试2：JSON格式POST，请求体会被过滤 @PostMapping("/test/json") public User testJson(@RequestBody User user) { log.info("接收到的用户: {}", user); // 观察日志，user对象的所有字符串字段都应该被清洗过 return user; } // 测试3：被排除的接口，内容原样返回 @PostMapping("/system/notice") public String notice(@RequestParam String htmlContent) { log.info("公告接口接收HTML: {}", htmlContent); // 这个接口在excludes列表里，不会触发XSS过滤 return htmlContent; } @Data // 使用Lombok注解 public static class User { private String username; private String email; private String bio; // 个人简介，可能包含HTML } }

5.3 使用Postman或CURL进行测试

测试用例1：反射型XSS攻击模拟向/test/form发送一个POST请求，表单数据为content=<script>alert('xss')</script>。

• 预期结果：在Controller里打印的日志和返回的响应中，<script>和</script>标签应该被移除，只剩下alert('xss')这段文本。你的浏览器不会弹出警告框。

测试用例2：存储型XSS攻击模拟（JSON）向/test/json发送一个POST请求，JSON体为：

{ "username": "hacker<script>alert(1)</script>", "email": "test@example.com", "bio": "<img src='x' onerror='alert(\"gotcha\")' />" }

• 预期结果：username字段中的<script>标签被移除。bio字段中的<img>标签，如果不在白名单内或者onerror属性不被允许，整个标签会被移除或净化。返回的JSON对象中，这些危险内容已不存在。

测试用例3：验证排除功能向/system/notice发送一个POST请求，内容为<p>这是一个<b>加粗</b>的公告</p>。

• 预期结果：因为该接口在排除列表里，所以内容不会被HTMLFilter处理，原样到达Controller。这对于需要保存原始HTML的富文本编辑器接口是必要的。

5.4 效果验证与日志分析

启动你的Spring Boot应用，运行上述测试。通过查看Controller中打印的日志，你可以清晰地看到过滤前后的区别。

例如，对于测试用例1，你的日志输出可能类似于：

接收到的内容: alert('xss')

而不是：

接收到的内容: <script>alert('xss')</script>

这就证明我们的过滤器生效了，恶意脚本标签已被成功剥离。

6. 进阶考量与生产环境部署建议

把代码跑起来只是第一步，要真正用到生产环境，还需要考虑更多细节。

6.1 性能影响与优化

字符串过滤，尤其是复杂的正则表达式匹配，肯定会有性能开销。我们需要将其降到最低。

• 优化HTMLFilter：原版的HTMLFilter使用了大量的正则表达式编译（Pattern.compile）。这些Pattern对象应该声明为static final常量，在类加载时就初始化好，避免每次过滤都重新编译。上面给出的代码示例已经做到了这一点。
• 缩小过滤范围：通过urlPatterns和excludes精确控制需要过滤的接口。对于只返回静态数据、无需用户输入的API，可以排除。
• 考虑缓存：对于频繁出现的、相同的恶意模式，可以考虑使用简单的缓存，但要注意缓存污染和内存消耗。

6.2 与其他安全机制的协同

XSS防御不是孤立的，它应该是一个纵深防御体系的一部分。

1. 输出编码：我们的过滤器主要做输入过滤。但更安全的做法是输入验证+输出编码。在某些场景下，我们可能需要存储原始数据（比如富文本），那么在输出到HTML页面时，必须使用正确的编码函数（如Thymeleaf的th:text会自动转义，th:utext则不会，要慎用）。对于非HTML的输出（如JSON API），要设置正确的Content-Type，防止浏览器误解析为HTML。
2. CSP（内容安全策略）：在HTTP响应头中加入CSP策略，是防御XSS的终极利器之一。它可以告诉浏览器只允许加载指定来源的脚本、样式等资源，即使有恶意脚本被注入，浏览器也不会执行。例如：Content-Security-Policy: default-src 'self'。这可以作为我们过滤器方案的有力补充。
3. HttpOnly Cookie：对于会话Cookie，务必设置HttpOnly属性。这样即使网站存在XSS漏洞导致脚本被执行，该脚本也无法通过document.cookie读取到Cookie信息，从而防止会话劫持。

6.3 常见问题排查（FAQ）

在实际部署中，你可能会遇到下面这些问题：

Q1：过滤器导致我的JSON请求报错“HttpMessageNotReadableException”。A1：这很可能是因为XssHttpServletRequestWrapper中的getInputStream()方法没有处理好非JSON请求，或者清洗时破坏了JSON格式（比如错误地转义了双引号）。检查isJsonRequest()方法逻辑，并确保EscapeUtil.clean()方法不会破坏JSON的结构（重点就是双引号问题）。

Q2：文件上传（Multipart）接口出错了。A2：对于multipart/form-data请求，参数是通过getPart()或getParameter()获取的，文件流是单独的。我们的包装器重写了getParameter，所以表单字段会被过滤。但文件内容本身是二进制流，不应该被当作字符串过滤。如果文件上传接口需要排除，将其路径加入excludes列表。如果需要对文件名进行过滤，可能需要更精细的处理，例如在过滤器中判断Content-Type，对multipart请求进行特殊解析（可以使用commons-fileupload等库），但这会显著增加复杂度，通常建议直接排除上传接口。

Q3：有些合法的HTML内容（比如富文本编辑器提交的）被过滤掉了。A3：这是白名单策略的必然结果。你需要根据业务需求，扩展HTMLFilter中的白名单（vAllowed）。例如，允许p,div,span,ul,ol,li,table,tr,td等标签，以及style,class等安全的属性。务必谨慎，每增加一个标签或属性，都要评估其可能带来的风险（比如style属性可能包含expression等危险内容）。对于复杂的富文本场景，可以考虑使用专业的富文本编辑器（如UEditor、WangEditor）配合其自带的XSS过滤规则，或者使用更强大的第三方过滤库如Jsoup。

Q4：过滤器的顺序似乎有问题，没生效。A4：确保在FilterConfig中，XssFilter的注册顺序（setOrder）被设置为较高的值（数字越小优先级越高）。它应该在编码过滤器（如CharacterEncodingFilter）之后运行，因为我们需要先拿到正确编码的字符串。通常设置为Ordered.HIGHEST_PRECEDENCE + 1或类似的值，并通过实际调试来确定最佳顺序。

7. 方案对比与总结

最后，我们来横向对比一下几种常见的Spring Boot防XSS方案，看看我们这个“5分钟过滤器”方案的定位。

总结一下：这个基于过滤器的XSS防御方案，最大的优势在于全局性和对业务代码的零侵入。你只需要引入几个类，做简单配置，整个应用就获得了基础的XSS免疫能力。它可能不是功能最强大的，但绝对是性价比最高、最“省心”的方案之一，特别适合快速发展的业务项目。

当然，没有银弹。这个方案主要解决了存储型和反射型XSS的输入过滤问题。要构建真正坚固的防线，必须结合输出编码、CSP、安全的Cookie策略以及持续的安全代码审计。安全是一个过程，而不是一个特性。希望这个“5分钟”的实战方案，能成为你SpringBoot应用安全之旅的一个可靠起点。