Java Web全局编码过滤器实现方法

本文深入剖析了Java Web开发中全局编码过滤器的实现要点与常见陷阱，指出setCharacterEncoding仅对POST等请求体有效、对GET参数完全无效，强调GET乱码需依赖容器URI配置或前端编码，而POST处理必须在getParameter()前完成；详解了如何通过HttpServletRequestWrapper安全缓存请求体以支持多次读取，避免二进制数据损坏；澄清了Filter执行顺序与Spring MVC的兼容性风险，推荐使用FilterRegistrationBean精准控制优先级；同时揭示了中文文件名下载时Content-Disposition头的跨浏览器编码难题，主张采用filename*+fallback双头方案而非Filter统一干预。全文直击生产环境高频踩坑点，倡导分层治理编码问题——将URL解析、请求体解码、响应头编码、文件路径处理各归其位，拒绝“一锅煮”式粗暴封装，为构建健壮、可维护的Web应用提供切实可行的最佳实践。

Filter 中 setCharacterEncoding 不生效的常见原因

直接调用 request.setCharacterEncoding("UTF-8") 无效，是因为它只影响后续对 getParameter() 等方法的调用，而请求体（如 POST 表单、JSON）的解码时机更早，且某些容器（如 Tomcat 8.5+）默认不自动解析 body 编码。更关键的是：GET 请求的参数编码由容器在解析 URL 时决定，setCharacterEncoding 对它完全没用。

• GET 参数乱码必须靠容器层面配置（如 Tomcat 的 URIEncoding="UTF-8"）或前端 URL 编码（encodeURIComponent）
• POST 表单乱码才适合用 Filter 处理，但必须在调用 getParameter() 前完成编码设置
• 如果 Filter 链里有其他 Filter 先读了 request body（比如 Spring 的 ContentCachingRequestWrapper），再设编码就晚了

HttpServletRequestWrapper 如何正确包装 request 以支持多次读取 body

原生 HttpServletRequest 的 input stream 只能读一次，但很多场景（如日志、签名、鉴权）需要反复读 body。这时候得自己继承 HttpServletRequestWrapper，缓存 body 字节，并重写 getInputStream() 和 getReader()。

• 缓存必须在构造函数里一次性读完原始 getInputStream()，并用 ByteArrayInputStream 包装
• 重写 getContentType()，确保后续逻辑能识别 JSON / form-data 类型
• 不要在包装类里做字符解码（比如 new String(bytes, "UTF-8")），否则会丢失原始字节，导致二进制上传失败
• Spring Boot 用户注意：ContentCachingRequestWrapper 已内置类似逻辑，但默认不启用，需配 server.tomcat.relaxed-query-chars 或自定义 Filter

public class BodyCachingRequestWrapper extends HttpServletRequestWrapper {
    private final byte[] cachedBody;

    public BodyCachingRequestWrapper(HttpServletRequest request) throws IOException {
        super(request);
        InputStream is = request.getInputStream();
        this.cachedBody = is.readAllBytes(); // Java 9+
    }

    @Override
    public ServletInputStream getInputStream() {
        return new CachedServletInputStream(cachedBody);
    }
}

Filter 执行顺序和 Spring MVC 的兼容性问题

Filter 在 Spring MVC 的 DispatcherServlet 之前执行，所以它能拦截所有请求；但如果你用 @WebFilter 注解声明 Filter，又同时用了 Spring 的 WebMvcConfigurer，容易因加载顺序错乱导致编码设置被覆盖。

• 推荐用 Java Config 方式注册 Filter：在配置类中返回 @Bean 类型为 FilterRegistrationBean，并设 setOrder(Ordered.HIGHEST_PRECEDENCE)
• 避免在同一个 Filter 里既处理编码又做鉴权或日志——职责混杂会导致调试困难，尤其当 body 被提前读取后，Controller 层拿不到原始数据
• Tomcat 9 默认启用 parseBodyMethods=POST,PUT,PATCH，如果你的接口用 PUT 提交 JSON，记得确认该配置未被禁用
• Spring Boot 2.3+ 默认禁用 HiddenHttpMethodFilter，如果依赖 _method 参数模拟 PUT/DELETE，要手动开启，否则 Filter 可能收不到预期 method

中文路径、文件名下载时的 Content-Disposition 编码陷阱

用 response.setHeader("Content-Disposition", "attachment; filename=中文.pdf") 会在 Chrome/Firefox 下变成乱码或下划线，这不是 Filter 能解决的问题，而是 HTTP 协议本身对 header 字符编码无强制规范。

• 老办法是用 filename*=UTF-8''%E4%B8%AD%E6%96%87.pdf（RFC 5987 格式），但 IE 不支持
• 稳妥做法是 fallback：同时写两个 header：filename（ASCII 文件名） + filename*（带编码的）
• Spring 的 ResponseEntity 会自动处理这个双 header，但原生 Servlet 需手动拼接，且 filename* 的空格必须 URL 编码成 %20
• 别在 Filter 里统一改 Content-Disposition —— 下载逻辑应由业务 Controller 明确控制，Filter 做全局编码已经够重了

实际项目里最常踩的坑不是不会写 Filter，而是把「请求体解码」「URL 解码」「响应头编码」「文件系统路径编码」全混在一个地方处理。它们分属不同协议层，强行统一反而增加耦合和出错概率。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~