1. 项目概述：为什么我们需要一个“清洁工”？

在Web应用开发的世界里，数据就像从四面八方涌来的水流，用户输入、第三方接口、甚至爬虫脚本，都可能携带泥沙。XSS（跨站脚本攻击）就是其中最隐蔽、最危险的“泥沙”之一。它不像SQL注入那样直接攻击数据库，而是潜伏在返回给用户的页面中，窃取Cookie、劫持会话、甚至冒充用户执行操作，防不胜防。很多开发者，尤其是刚接触SpringBoot的朋友，可能会觉得框架本身已经足够安全，或者依赖前端进行转义就够了。但现实是，安全防线必须层层设卡，后端作为数据的最终处理者和存储者，对输入进行净化和校验是不可或缺的最后一道闸门。

这个项目的核心，就是为你的SpringBoot应用配置一个高效、灵活的“数据清洁工”——基于Hutool工具包的XSS过滤器。它不只是一个简单的字符替换，而是一套完整的防御策略。通过这个过滤器，所有进入你应用的HTTP请求参数、请求体，都会经过一次“安检”，将潜在的恶意脚本标签、危险属性等剥离或转义，确保存入数据库和返回给前端的数据都是“干净”的。Hutool作为一个国产的Java工具库，其HtmlUtil类提供了非常强大的HTML过滤和转义功能，性能优异且API友好，与SpringBoot的过滤器机制结合，能让我们用极少的代码构建起坚固的防线。

这篇文章，我将从一个有十多年后端开发经验的视角，带你彻底拆解这个“清洁工”的搭建过程。我不会只给你一段代码让你复制粘贴，而是会详细解释每一个配置项背后的安全考量，分享我在实际项目中踩过的坑，以及如何根据不同的业务场景（比如富文本编辑器）调整过滤策略。无论你是正在为安全审计发愁的团队骨干，还是想夯实自己Web安全基础的初学者，这篇全解析都能给你带来可直接落地的解决方案和深度的原理理解。

2. 核心思路与架构设计：不止于转义

在动手写代码之前，我们必须想清楚防御策略。一个健壮的XSS防御方案，绝不是简单地把<script>标签删除就万事大吉。攻击者的手段层出不穷，从最基础的标签注入到利用HTML事件属性、CSS表达式、甚至混淆编码绕过，我们的过滤器需要有相应的应对机制。

2.1 防御策略分层

我的设计思路是分层防御，核心是“输入过滤，输出转义”。本过滤器主要解决“输入过滤”这一层。

1. 全局输入过滤（本过滤器核心）：在请求进入Controller之前，对所有参数进行清洗。这是我们的主战场。
2. 上下文输出转义：在视图层（如Thymeleaf、FreeMarker）或API返回时，根据输出上下文对动态数据进行转义。这通常由模板引擎或JSON序列化库负责。
3. 内容安全策略（CSP）：通过HTTP响应头Content-Security-Policy，告诉浏览器只允许加载指定来源的脚本、样式等资源，即使有恶意脚本被注入，浏览器也不会执行。这是最后一道强有力的防线。

我们的SpringBoot + Hutool过滤器，聚焦于第一层，目标是构建一个可配置、高性能的请求清洗网关。

2.2 技术选型：为什么是Hutool？

市面上能做HTML过滤的库不少，比如Jsoup、OWASP Java Encoder。选择Hutool的HtmlUtil，主要基于以下几点实战考量：

• 功能聚焦且强大：HtmlUtil.filter()方法默认就提供了一套严格的过滤规则，能移除所有HTML标签，只保留文本内容。这对于大多数普通输入框（如用户名、搜索关键词）来说，开箱即用。同时，它也支持白名单过滤模式，这对于需要保留部分格式（如富文本）的场景至关重要。
• 性能与可靠性：Hutool在国内Java开发者中应用广泛，其稳定性和性能经过大量项目验证。它底层采用高效的字符串处理机制，在过滤性能上表现优异，不会对应用响应时间造成明显影响。
• 与SpringBoot生态融合好：配置简单，无需复杂的依赖冲突解决。其API设计符合Java开发者的直觉，易于集成到Spring的Filter接口中。
• 国产开源，文档友好：中文文档和社区支持对于快速解决问题非常有帮助。

2.3 过滤器架构设计

我们将创建一个自定义的Filter，并把它插入到SpringBoot的过滤器链中。关键设计点包括：

• 包装HttpServletRequest：因为原生的HttpServletRequest中的参数（getParameter,getParameterMap）是只读的。我们需要自定义一个XssHttpServletRequestWrapper类来包装它，重写相关方法，在返回值时进行过滤。
• 区分请求类型：对于application/x-www-form-urlencoded（表单提交）和multipart/form-data（文件上传）格式的参数，我们从getParameter*系列方法中过滤。对于application/json格式的请求体，我们需要读取输入流进行过滤。
• 配置排除路径：像文件上传接口、WebSocket连接点、或一些特殊的第三方回调接口，可能不需要或不能进行XSS过滤，我们需要支持配置排除列表。
• 线程安全与性能：过滤器会被所有线程共享，必须确保无状态且高效。避免在过滤方法中创建大量临时对象。

这个架构确保了过滤动作对业务代码透明，Controller接收到的已经是净化后的数据，开发者可以像往常一样编写业务逻辑，无需额外关心XSS风险。

3. 核心组件实现详解

接下来，我们进入实战环节，一步步构建这个过滤器。我会对每一行关键代码进行解释，并说明为什么这么做。

3.1 第一步：引入依赖

首先，在你的pom.xml中添加Hutool的依赖。建议使用最新的稳定版本。

<dependency> <groupId>cn.hutool</groupId> <artifactId>hutool-all</artifactId> <version>5.8.25</version> <!-- 请检查并使用最新版本 --> </dependency>

注意：如果你的项目已经引入了SpringBoot的spring-boot-starter-web，它已经包含了Servlet API，无需额外引入。确保依赖版本兼容，一般不会有问题。

3.2 第二步：创建XSS请求包装器

这是过滤器的核心部件，负责拦截所有获取参数的请求。

import cn.hutool.core.util.StrUtil; import cn.hutool.http.HtmlUtil; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletRequestWrapper; import java.util.*; /** * XSS请求包装器 * 重写 getParameter, getParameterValues, getParameterMap, getHeader 等方法 */ public class XssHttpServletRequestWrapper extends HttpServletRequestWrapper { public XssHttpServletRequestWrapper(HttpServletRequest request) { super(request); } /** * 对单个字符串值进行XSS清理 * @param value 原始值 * @return 清理后的值 */ private String cleanXss(String value) { if (StrUtil.isBlank(value)) { return value; } // 使用Hutool的HtmlUtil进行过滤，移除所有HTML标签，保留纯文本 // 这是最严格的过滤方式，适用于绝大多数场景 return HtmlUtil.filter(value); } /** * 重写getParameter方法 */ @Override public String getParameter(String name) { String value = super.getParameter(name); return cleanXss(value); } /** * 重写getParameterValues方法（处理多选框等场景） */ @Override public String[] getParameterValues(String name) { String[] values = super.getParameterValues(name); if (values == null) { return null; } int length = values.length; String[] cleanValues = new String[length]; for (int i = 0; i < length; i++) { cleanValues[i] = cleanXss(values[i]); } return cleanValues; } /** * 重写getParameterMap方法 * 注意：这里返回的Map中的值数组应该是清理后的副本，避免修改原始Map */ @Override public Map<String, String[]> getParameterMap() { Map<String, String[]> parameterMap = super.getParameterMap(); if (parameterMap == null) { return null; } Map<String, String[]> cleanMap = new LinkedHashMap<>(parameterMap.size()); for (Map.Entry<String, String[]> entry : parameterMap.entrySet()) { String key = entry.getKey(); String[] values = entry.getValue(); if (values != null) { String[] cleanValues = new String[values.length]; for (int i = 0; i < values.length; i++) { cleanValues[i] = cleanXss(values[i]); } cleanMap.put(key, cleanValues); } else { cleanMap.put(key, null); } } return cleanMap; } /** * 重写getHeader方法（某些攻击可能通过Header注入） */ @Override public String getHeader(String name) { String value = super.getHeader(name); return cleanXss(value); } }

关键点解析：

1. cleanXss方法：这里直接使用了HtmlUtil.filter(value)。它会移除字符串中所有的HTML标签。例如，输入<script>alert(1)</script>你好，输出将是你好。
2. 重写getParameterMap：这是最容易被忽略但很重要的一点。我们必须返回一个新的Map，包含清理后的值数组。如果直接修改原Map或返回原Map，可能会引起线程安全问题或意外的副作用。
3. 处理Header：虽然不常见，但XSS攻击有时也会尝试通过User-Agent、Referer等HTTP头进行注入。重写getHeader方法是一个防御纵深考虑。

3.3 第三步：创建并配置XSS过滤器

现在，我们创建过滤器本体，并将其注册到Spring容器。

import org.springframework.boot.web.servlet.FilterRegistrationBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import javax.servlet.*; import javax.servlet.http.HttpServletRequest; import java.io.IOException; import java.util.Arrays; import java.util.HashSet; import java.util.Set; @Configuration public class XssFilterConfig { /** * 配置XSS过滤器 */ @Bean public FilterRegistrationBean<XssFilter> xssFilterRegistrationBean() { FilterRegistrationBean<XssFilter> registrationBean = new FilterRegistrationBean<>(); registrationBean.setFilter(new XssFilter()); registrationBean.setOrder(1); // 设置过滤器执行顺序，数字越小优先级越高 registrationBean.addUrlPatterns("/*"); // 过滤所有请求 registrationBean.setName("xssFilter"); // 设置排除路径（不需要过滤的URL） registrationBean.addInitParameter("exclusions", "/api/file/upload,/ws/*,/callback/thirdParty"); return registrationBean; } /** * 自定义XSS过滤器 */ public class XssFilter implements Filter { // 排除路径集合 private Set<String> excludes = new HashSet<>(); @Override public void init(FilterConfig filterConfig) throws ServletException { String exclusions = filterConfig.getInitParameter("exclusions"); if (StrUtil.isNotBlank(exclusions)) { String[] urls = exclusions.split(","); excludes.addAll(Arrays.asList(urls)); } } @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 requestURI = request.getRequestURI(); if (StrUtil.isEmpty(requestURI)) { return false; } // 简单路径匹配（实际项目中可能需要更复杂的Ant路径匹配） for (String exclude : excludes) { if (exclude.endsWith("/*")) { if (requestURI.startsWith(exclude.substring(0, exclude.length() - 2))) { return true; } } else if (requestURI.equals(exclude)) { return true; } } return false; } @Override public void destroy() { // 清理资源 } } }

配置详解与避坑指南：

1. FilterRegistrationBean：这是SpringBoot注册Servlet Filter的标准方式。它提供了比@WebFilter注解更强大的控制能力，比如设置顺序(setOrder)和初始化参数(addInitParameter)。
2. 执行顺序(setOrder)：将其设置为1（或一个较小的数字），是为了让XSS过滤尽可能早地执行。因为过滤要在参数被读取之前完成。但要小心其他全局过滤器（如字符编码过滤器CharacterEncodingFilter）的顺序，通常编码过滤器应该在更前面（Order值更小）。
3. 排除路径(exclusions)：这个功能至关重要。例如：
   • /api/file/upload：文件上传接口，过滤可能会破坏文件二进制内容。
   • /ws/*：WebSocket端点，通常使用不同的协议，不需要HTTP参数过滤。
   • /callback/thirdParty：第三方回调接口，参数格式可能固定且复杂，盲目过滤可能导致签名校验失败。
   • 避坑提示：排除路径的匹配逻辑这里用了简单的字符串匹配。在生产环境中，如果路径规则复杂，建议引入Spring的AntPathMatcher进行更准确的Ant风格路径匹配（如/admin/**）。
4. JSON请求体的处理：上面的包装器只处理了getParameter和getHeader，对于POST请求中application/json类型的数据（通过request.getInputStream()读取），包装器是无效的。这是一个常见的陷阱。我们需要额外处理。

3.4 第四步：处理JSON请求体

为了处理JSON请求，我们需要进一步改造包装器，重写getInputStream()方法，并缓存流中的数据。

// 在 XssHttpServletRequestWrapper 类中添加以下代码 import javax.servlet.ServletInputStream; import javax.servlet.http.HttpServletRequest; import java.io.*; import java.nio.charset.StandardCharsets; public class XssHttpServletRequestWrapper extends HttpServletRequestWrapper { // ... 之前已有的字段和方法 ... private byte[] body; // 用于缓存请求体数据 public XssHttpServletRequestWrapper(HttpServletRequest request) throws IOException { super(request); // 缓存请求体，以便多次读取 cacheRequestBody(request); } private void cacheRequestBody(HttpServletRequest request) throws IOException { StringBuilder stringBuilder = new StringBuilder(); try (BufferedReader reader = request.getReader()) { String line; while ((line = reader.readLine()) != null) { stringBuilder.append(line); } } String requestBody = stringBuilder.toString(); if (StrUtil.isNotBlank(requestBody)) { // 关键：对JSON字符串进行XSS过滤 // 注意：这里简单过滤整个字符串，可能会破坏JSON结构。更优方案是解析JSON后对字符串值字段单独过滤。 String cleanBody = cleanXssJson(requestBody); this.body = cleanBody.getBytes(StandardCharsets.UTF_8); } else { this.body = new byte[0]; } } /** * 专门处理JSON字符串的XSS清理 * 简单实现：直接调用HtmlUtil.filter，但这会过滤掉JSON中的引号等符号，破坏结构。 * 正确做法：使用JSON库解析，然后递归遍历所有字符串值进行过滤。 * 此处为演示，先使用简单方法。下文会给出优化方案。 */ private String cleanXssJson(String json) { // 【警告】此简单方法会破坏JSON结构，仅作演示。 // return HtmlUtil.filter(json); // 暂时先原样返回，我们在后面优化。 return json; } @Override public ServletInputStream getInputStream() throws IOException { if (body == null) { body = new byte[0]; } final ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(body); return new ServletInputStream() { @Override public int read() throws IOException { return byteArrayInputStream.read(); } @Override public boolean isFinished() { return byteArrayInputStream.available() == 0; } @Override public boolean isReady() { return true; } @Override public void setReadListener(ReadListener listener) { // 不处理异步 } }; } @Override public BufferedReader getReader() throws IOException { return new BufferedReader(new InputStreamReader(getInputStream(), StandardCharsets.UTF_8)); } }

这里暴露了一个严重问题：HtmlUtil.filter会无差别地过滤掉<、>、&、"等字符，这对于JSON字符串来说是灾难性的，因为JSON本身就需要这些字符作为语法符号（如双引号"）。直接过滤会导致JSON解析失败。

解决方案：我们需要解析JSON，只对值部分（value）的字符串类型进行过滤。这需要引入一个JSON处理库，如Jackson。

3.5 第五步：优化JSON请求体的精准过滤

首先，确保你的项目引入了Jackson（SpringBoot默认已包含）。

<!-- SpringBoot web starter 默认包含 jackson --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>

然后，我们优化cleanXssJson方法，使用Jackson遍历JSON节点。

import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.*; // 在 XssHttpServletRequestWrapper 类中修改 cleanXssJson 方法并添加辅助方法 private String cleanXssJson(String json) throws IOException { if (StrUtil.isBlank(json)) { return json; } ObjectMapper objectMapper = new ObjectMapper(); try { JsonNode rootNode = objectMapper.readTree(json); JsonNode cleanedNode = cleanJsonNode(rootNode); return objectMapper.writeValueAsString(cleanedNode); } catch (IOException e) { // 如果JSON解析失败，可能是无效JSON或非JSON内容，直接返回原字符串或进行安全处理 // 出于安全考虑，对于无法解析的JSON，可以选择记录日志并返回空对象或原串（有风险） // 这里记录日志后返回原串，实际项目可根据安全级别调整 // log.warn("XSS过滤：JSON解析失败，内容将被跳过过滤。内容前缀：{}", StrUtil.subPre(json, 100)); return json; // 或返回 "{}" } } private JsonNode cleanJsonNode(JsonNode node) { if (node == null || node.isNull()) { return NullNode.getInstance(); } if (node.isTextual()) { // 只对文本节点进行XSS过滤 String cleanedText = HtmlUtil.filter(node.asText()); return new TextNode(cleanedText); } if (node.isArray()) { ArrayNode newArray = new ArrayNode(JsonNodeFactory.instance); for (JsonNode childNode : node) { newArray.add(cleanJsonNode(childNode)); } return newArray; } if (node.isObject()) { ObjectNode newObject = new ObjectNode(JsonNodeFactory.instance); node.fields().forEachRemaining(entry -> { newObject.set(entry.getKey(), cleanJsonNode(entry.getValue())); }); return newObject; } // 对于数字、布尔值等非字符串节点，直接返回 return node; }

优化点解析：

1. 精准过滤：cleanJsonNode方法递归遍历JSON树，只对TextNode（字符串值）调用HtmlUtil.filter。对象键（key）通常不可控，但理论上也应考虑过滤，不过修改key会破坏数据结构，需谨慎。这里假设key是安全的。
2. 异常处理：如果输入的字符串不是合法JSON，objectMapper.readTree会抛出异常。在catch块中，我们记录了警告（注释掉了，实际项目应开启日志），并选择返回原字符串。这是一个安全权衡：严格模式下，可以拒绝非法请求；宽松模式下，为了兼容性可能放过。我建议在关键业务系统采用严格模式，直接返回错误响应。
3. 性能考虑：每次请求都进行JSON解析和序列化，对性能有一定影响。如果应用JSON请求体非常大或QPS极高，需要评估性能损耗。可以考虑使用更高效的JSON库（如fastjson2，但需注意其历史安全漏洞），或者对于明确内部、可信的接口，通过排除路径跳过过滤。

至此，一个能够处理表单参数、URL参数、HTTP头和JSON请求体的完整XSS过滤器就构建完成了。

4. 高级配置与场景化调优

基础的过滤器搭建好了，但真实业务场景往往更复杂。直接移除所有HTML标签的“一刀切”策略，可能会误伤一些合法需求。

4.1 场景一：富文本编辑器内容处理

用户在使用富文本编辑器（如UEditor、WangEditor、TinyMCE）提交文章、评论时，内容本身包含HTML标签（如<p>,<strong>,<img>）。我们显然不能把这些标签都删掉。

解决方案：使用白名单过滤。

Hutool的HtmlUtil提供了cleanHtml方法，可以指定一个白名单。

import cn.hutool.core.util.StrUtil; import cn.hutool.http.HtmlUtil; // 在 XssHttpServletRequestWrapper 中新增一个方法，或修改 cleanXss 方法使其可配置 private String cleanXss(String value, boolean isRichText) { if (StrUtil.isBlank(value)) { return value; } if (isRichText) { // 使用白名单过滤 // 定义允许的标签及其属性 // 这是一个相对宽松的白名单，可根据实际需求收紧 String clean = HtmlUtil.cleanHtml(value, new HashSet<>(Arrays.asList( // 允许的标签 "p", "br", "b", "strong", "i", "em", "u", "s", "span", "div", "h1", "h2", "h3", "h4", "h5", "h6", "ul", "ol", "li", "a", // 链接 "img", // 图片 "blockquote", "code", "pre", "table", "thead", "tbody", "tr", "th", "td" ))); // 进一步，可以限制标签的属性，例如只允许a标签有href和title属性 // 这里Hutool的cleanHtml默认会移除所有不安全的属性（如onclick, javascript:等） // 对于更精细的控制，可能需要结合Jsoup return clean; } else { // 普通文本，严格过滤，移除所有标签 return HtmlUtil.filter(value); } }

那么，如何判断一个字段是否是富文本内容呢？有两种常见思路：

1. 接口约定：为接收富文本的接口设计独立的DTO或使用特定的参数名（如contentHtml），在过滤器或Controller中根据字段名判断。
2. 注解标记：自定义一个注解（如@RichText），在DTO的字段上标注。然后通过AOP或自定义参数解析器，在数据绑定后对标记了注解的字段进行白名单过滤。这种方式更优雅，但实现稍复杂。

实操心得：白名单策略务必收紧。例如，a标签的href属性必须严格校验协议，只允许http://,https://,mailto:，绝对禁止javascript:。img标签的src属性也应限制为可信的域名或Base64 Data URL（需注意大小）。建议参考OWASP的XSS防护白名单推荐。

4.2 场景二：忽略特定字段或类型的过滤

有些字段可能包含需要原样存储的代码片段、模板语法或加密数据，过滤会破坏其功能。

解决方案：在包装器中增加忽略逻辑。

我们可以通过配置一个“忽略字段名”列表来实现。

public class XssHttpServletRequestWrapper extends HttpServletRequestWrapper { private static final Set<String> IGNORE_FIELDS = new HashSet<>(Arrays.asList("signature", "encryptedData", "codeSnippet")); // ... 其他代码 ... private String cleanXss(String value, String parameterName) { if (StrUtil.isBlank(value) || IGNORE_FIELDS.contains(parameterName)) { return value; // 忽略字段，直接返回 } // ... 后续判断是否是富文本字段，然后调用相应的过滤方法 ... return HtmlUtil.filter(value); } // 然后修改 getParameter, getParameterValues 等方法，将参数名传入 cleanXss @Override public String getParameter(String name) { String value = super.getParameter(name); return cleanXss(value, name); } }

注意事项：忽略字段必须谨慎评估其安全性。确保这些字段的值来自绝对可信的来源（如系统自身生成的签名、来自可信合作伙伴的加密数据），或者后续有独立的安全校验流程。

4.3 场景三：性能优化与缓存

在高并发场景下，频繁的字符串过滤和JSON解析可能成为瓶颈。

优化思路：

1. 路径排除精细化：将确无需过滤的API（如健康检查/actuator/health、内部状态接口）加入排除列表，减少不必要的过滤开销。
2. 缓存过滤结果：对于相同的恶意模式（如常见的<script>），过滤结果总是相同的。可以考虑使用一个简单的LRU缓存（如使用Collections.synchronizedMap包装LinkedHashMap或使用Caffeine库）来缓存(原始字符串, 过滤后字符串)键值对。但要注意缓存大小和字符串长度，避免内存溢出。
3. 异步过滤：对于非关键路径或可接受轻微延迟的请求，可以考虑将过滤操作放入单独的线程池处理。但这会显著增加复杂度，需要权衡。
4. 使用更快的库：如果性能测试发现HtmlUtil.filter是热点，可以评估其他库，如OWASP Java Encoder的forHtmlContent方法，它在某些基准测试中可能更快。

我的经验：在99%的业务系统中，上述基础过滤器的性能开销是可以接受的。过早优化是万恶之源。建议先上线基础版本，通过APM工具（如SkyWalking, Pinpoint）监控过滤器的平均耗时和P99耗时，确认其成为瓶颈后再进行优化。我曾在一个人均QPS过千的系统中使用类似方案，CPU增幅不到2%，完全在可接受范围。

5. 测试、部署与问题排查

5.1 如何测试过滤器的有效性？

不要只靠“感觉”，必须进行系统化测试。

1. 单元测试：为XssHttpServletRequestWrapper和cleanXss方法编写单元测试。

   @Test void testCleanXss() { XssHttpServletRequestWrapper wrapper = ... // 需要Mock HttpServletRequest String input = "<script>alert('xss')</script><p>正常文本</p>"; String output = wrapper.cleanXss(input, false); Assertions.assertThat(output).isEqualTo("正常文本"); // 测试富文本白名单 String richInput = "<p>一段<strong>加粗</strong>文本</p><script>alert(1)</script>"; String richOutput = wrapper.cleanXss(richInput, true); Assertions.assertThat(richOutput).contains("<p>", "<strong>"); Assertions.assertThat(richOutput).doesNotContain("<script>"); }

2. 集成测试：使用MockMvc或TestRestTemplate对真实接口发起包含XSS payload的请求，断言响应中不包含恶意脚本，且业务逻辑正确。

   @SpringBootTest @AutoConfigureMockMvc class UserControllerTest { @Test void testCreateUserWithXss(@Autowired MockMvc mvc) throws Exception { String maliciousName = "张三<script>alert(1)</script>"; mvc.perform(post("/api/user") .contentType(MediaType.APPLICATION_JSON) .content("{\"username\": \"" + maliciousName + "\"}")) .andExpect(status().isOk()) .andExpect(jsonPath("$.data.username").value("张三")); // 期望过滤后的名字 } }

3. 手动渗透测试：使用浏览器或工具（如Burp Suite）手动尝试各种XSS payload，包括大小写混淆、编码绕过、利用HTML事件等。以下是一些测试向量：
   • <script>alert(1)</script>
   • <img src=x onerror=alert(1)>
   • <svg/onload=alert(1)>
   • javascript:alert(1)(在<a href>中测试)
   • "><script>alert(1)</script>(测试是否破坏了HTML属性上下文)

5.2 常见问题排查实录

在实际部署和运行中，你可能会遇到以下问题：

问题1：过滤器导致application/json请求的@RequestBody对象绑定失败。

• 现象：Controller方法参数使用@RequestBody接收的对象，所有字段都为null。
• 原因：我们的XssHttpServletRequestWrapper重写了getInputStream()，但Spring的HttpMessageConverter（如MappingJackson2HttpMessageConverter）在读取流时，如果流已经被读取过（我们在cacheRequestBody中读了），并且没有正确重置，就会导致读取不到数据。
• 解决方案：我们的实现中，cacheRequestBody在构造器中读取了流并存入byte[] body，然后重写的getInputStream()返回的是基于这个body的新流。这是正确的做法，确保了流可重复读。如果出现问题，检查是否在其他地方（如另一个过滤器）提前消费了请求体且未包装。确保XSS过滤器在过滤器链中顺序靠前。

问题2：文件上传（multipart/form-data）接口出错。

• 现象：上传文件时，接口报错或文件损坏。
• 原因：multipart请求的解析通常由MultipartResolver（如StandardServletMultipartResolver）处理，它会在过滤器链之前或特定阶段解析请求，将文件部分和表单字段部分分开。我们的过滤器对原始参数进行过滤，可能会干扰这个过程。
• 解决方案：将文件上传接口的路径加入到过滤器的排除列表（exclusions）中。这是最安全、最直接的做法。文件内容本身是二进制流，不应进行字符串过滤。

问题3：过滤后，前端显示出现了奇怪的&或<。

• 现象：用户输入了&或<，存入数据库的是&或<，前端显示也是这些字符实体。
• 原因：HtmlUtil.filter默认会进行HTML转义。输入a < b会被转义成a < b。这是正确的安全行为，防止了HTML注入。
• 解决方案：这通常不是过滤器的问题，而是输出上下文的问题。在前端渲染时，如果你使用的是类似{{ content }}的语法（Thymeleaf, FreeMarker默认会转义），那么<会被正确渲染为<显示在页面上。如果你是在非HTML上下文（如纯文本、JSON API）中返回，或者前端使用了v-html（Vue）等危险操作，那么你需要决定是否在输出时进行反转义。我的建议是：保持数据库存储转义后的安全文本。在前端，除非确需渲染HTML（如富文本内容），否则永远使用文本插值而非HTML插值。对于需要渲染HTML的情况，确保内容来自可信来源（如经过白名单过滤的富文本）。

问题4：某些复杂的、编码过的XSS Payload似乎绕过了过滤。

• 现象：输入<img src=x onerror=&#x61;&#x6c;&#x65;&#x72;&#x74;&#x28;&#x31;&#x29;>，可能未被完全过滤。
• 原因：Hutool的HtmlUtil.filter默认能处理常见的HTML实体和十进制/十六进制编码。但攻击者的编码方式千奇百怪（如JSFuck、多重编码）。
• 解决方案：
  1. 标准化输入：在过滤前，尝试对输入进行规范化或解码。但要注意，这可能引入新的复杂度。
  2. 依赖更强大的库：例如OWASP Java Encoder，它提供了针对不同上下文（HTML内容、HTML属性、JavaScript、CSS、URL）的编码器，遵循“输出编码”原则，可能更安全。
  3. 纵深防御：记住，过滤器只是第一层。务必启用CSP（Content-Security-Policy）。即使有脚本被注入，一个严格的CSP也能阻止浏览器执行它。在SpringBoot中，可以很容易地通过配置或HttpSecurity来添加CSP头。
  4. 定期更新与审计：关注安全社区，更新Hutool等依赖库到最新版本，定期进行安全扫描和渗透测试。

5.3 部署上线检查清单

在将这套过滤器部署到生产环境前，请对照此清单进行检查：

• [ ]依赖检查：Hutool版本是否稳定？是否存在已知安全漏洞？
• [ ]排除路径：是否已将所有文件上传、WebSocket、第三方回调等特殊接口路径加入排除列表？
• [ ]富文本处理：如果业务涉及富文本，白名单是否已根据最小权限原则配置完成？是否测试过各种合法标签和属性？
• [ ]JSON处理：JSON过滤逻辑是否经过测试，确保不会破坏正常JSON结构？
• [ ]性能基线：在测试环境，对关键接口进行压测，记录增加过滤器前后的RT（响应时间）和CPU使用率变化，确保在可接受范围内。
• [ ]监控与日志：是否在过滤器中添加了必要的WARN或ERROR日志（例如JSON解析失败）？监控系统是否能捕获这些日志？
• [ ]回滚方案：是否准备了快速禁用过滤器的方案（如通过配置开关）？以防出现不可预见的兼容性问题。
• [ ]安全测试：是否进行了至少一轮涵盖反射型、存储型XSS的渗透测试？

最后，我想强调的是，没有任何单一技术能提供100%的安全。这个基于SpringBoot和Hutool的XSS过滤器是一个强大、实用的基础防御组件，它能帮你挡住绝大部分自动化攻击和常见的手工测试。但真正的安全是一个持续的过程，需要将安全编码规范（如对输出进行编码）、定期依赖更新、安全特性配置（如CSP、HttpOnly Cookie）和安全意识培训结合起来。把这个过滤器当作你应用安全铠甲中的一块坚实护板，然后继续构建和完善你的整体防御体系吧。