若依框架实战：5分钟搞定XSS攻击防护（附完整代码示例）

若依框架实战：5分钟搞定XSS攻击防护（附完整代码示例）

最近在帮几个初创团队做技术架构评审，发现一个挺普遍的现象：很多开发者对业务逻辑的实现非常上心，但在基础安全防护上却常常“偷懒”，总觉得XSS、SQL注入这些是老生常谈，框架应该都处理好了。结果呢？上周就有一个朋友的项目，因为一个富文本评论区的XSS漏洞，被恶意脚本刷了满屏的弹窗广告，用户体验直接崩盘，紧急加班排查了大半天。其实，在若依（RuoYi）这类成熟的Spring Boot框架里，集成一套可靠的XSS防护机制，远没有想象中那么复杂。今天，我就结合自己最近在几个中型项目中的落地经验，带你走一遍从零到一的完整防护流程。我们不谈太多晦涩的理论，就聚焦在如何用最少的时间、最清晰的代码，为你的若依应用穿上这件“防弹衣”。无论你是刚接手若依项目的开发者，还是希望快速提升应用安全水位的中小企业技术负责人，这篇实战指南都能让你在5分钟内，获得一套可直接复制粘贴的生产级代码。

1. 理解核心：为什么你的若依应用需要独立的XSS过滤器？

你可能会有疑问：Spring框架本身不是有一些安全机制吗？若依也自带了一些安全配置，为什么我们还要额外处理XSS？这里的关键在于 “默认配置”与“深度防御” 的差别。Spring Security等组件主要防范的是CSRF、认证授权等层面，而对于请求参数中夹杂的HTML或JavaScript脚本，通常不会进行主动的、针对性的过滤。若依框架的原始设计更偏向于提供基础脚手架和通用功能，在安全过滤的颗粒度和策略上，留给开发者自定义的空间很大。

XSS攻击的本质，是攻击者将可执行代码“注入”到网页中，被其他用户的浏览器当成正常脚本执行。它主要分为三类：

• 反射型XSS：恶意脚本作为请求参数的一部分，服务器直接“反射”回响应页面中。常见于搜索框、错误提示页。
• 存储型XSS：恶意脚本被持久化保存到服务器数据库，当其他用户浏览相关页面时触发。论坛发帖、用户评论是重灾区。
• DOM型XSS：前端的JavaScript在处理DOM时，不安全地操作了包含恶意代码的数据源。

若依作为一个后台管理系统，用户输入点极多：数据表格的查询条件、表单的提交字段、系统通知的编辑内容等等。任何一个输入点失守，都可能导致后台数据被篡改、用户会话被盗用，甚至成为攻击内网的跳板。因此，在请求进入业务逻辑的第一时间，就对所有参数进行净化和转义，是成本最低、效果最显著的一道防线。

实现这道防线的经典模式，就是利用Servlet规范中的Filter（过滤器）。它的位置在请求旅程的最前沿，如下图所示：

客户端请求 -> Tomcat容器 -> **XSS Filter** -> Spring MVC DispatcherServlet -> 你的Controller

通过在Filter层对HttpServletRequest进行包装和改造，我们就能实现一种对业务代码透明无侵入的防护。接下来，我们就动手实现这个核心过滤器。

2. 实战第一步：构建可复用的XSS请求包装器

一切的核心在于HttpServletRequestWrapper这个类。它是装饰器模式（Decorator Pattern）在Servlet API中的典型应用，允许我们在不改变原对象结构的情况下，增强或改变其行为。我们的目标就是创建一个自定义的Wrapper，重写其获取参数的方法，在返回值给Controller之前，先进行清洗。

首先，我们需要一个HTML标签过滤工具。这里我推荐一个简单直接的实现，它基于jsoup这个强大的HTML解析库，能精准地移除潜在的恶意标签，同时保留安全的文本内容。

步骤1：添加依赖 在你的pom.xml中加入：

<dependency>
    <groupId>org.jsoup</groupId>
    <artifactId>jsoup</artifactId>
    <version>1.17.2</version>
</dependency>

步骤2：创建XSS过滤工具类 我们创建一个XssUtil类，它不依赖任何Spring组件，是纯工具性质。

import org.jsoup.Jsoup;
import org.jsoup.safety.Safelist;

/**
 * XSS过滤工具类
 * 使用Jsoup进行HTML净化，只允许安全的文本通过。
 */
public class XssUtil {

    /**
     * 使用Jsoup的白名单机制清理HTML，只保留文本（移除所有标签）。
     * 这是最严格的过滤策略，适用于大多数输入场景（如用户名、搜索词）。
     *
     * @param html 可能包含HTML的输入字符串
     * @return 纯净的文本内容
     */
    public static String clean(String html) {
        if (html == null || html.isEmpty()) {
            return html;
        }
        // 使用Safelist.none()，表示不允许任何HTML标签，全部转为纯文本
        return Jsoup.clean(html, Safelist.none());
    }

    /**
     * 宽松的清理策略，允许一些安全的HTML标签（如b, i, u），但会移除危险属性（如onclick, href=javascript:）。
     * 适用于需要保留简单格式的富文本场景（如系统公告内容），但需谨慎评估风险。
     *
     * @param html 输入的HTML片段
     * @return 经过净化的HTML片段
     */
    public static String cleanWithSimpleFormat(String html) {
        if (html == null || html.isEmpty()) {
            return html;
        }
        // 允许基本的文本格式标签，但会过滤掉所有属性
        Safelist safelist = Safelist.simpleText();
        return Jsoup.clean(html, safelist);
    }
}

提示：Safelist.none()是最安全的选项。如果你的应用有富文本编辑器（如通知内容），可以考虑使用cleanWithSimpleFormat或自定义更复杂的Safelist，但务必进行严格的测试。

步骤3：创建请求包装器 现在，创建核心的XssHttpServletRequestWrapper类，它继承自HttpServletRequestWrapper。

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletRequestWrapper;
import java.util.Map;
import java.util.HashMap;

/**
 * 防XSS攻击的HttpServletRequest包装器
 * 重写所有获取参数的方法，对值进行过滤。
 */
public class XssHttpServletRequestWrapper extends HttpServletRequestWrapper {

    public XssHttpServletRequestWrapper(HttpServletRequest request) {
        super(request);
    }

    /**
     * 重写getParameter，对