Java Filter 過濾器解決中文亂碼的統一編碼最佳實踐

問題背景

在 Servlet 開發中，中文亂碼是高頻痛點。常見錯誤是：Filter 初始化參數配置 UTF-8，但 JSP 頁面卻用 GBK，導致請求/響應編碼不一致，最終出現亂碼。本文提供基於全鏈路統一編碼的標准解決方案。

核心原則：全鏈路統一編碼

請求解碼、響應編碼、頁面編碼、數據庫連接、JVM 文件編碼 —— 必須全部統一為 UTF-8（推薦）或 GBK，絕不混用。

標準 Filter 實現

1. 過濾器類

package cn.com.filter;

import jakarta.servlet.*;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.annotation.WebInitParam;
import java.io.IOException;

/**
 * 字符編碼過濾器
 * 統一設置請求解碼與響應編碼
 */
@WebFilter(
    urlPatterns = "/*",
    initParams = @WebInitParam(name = "encoding", value = "UTF-8")
)
public class CharacterEncodingFilter implements Filter {

    private String encoding = "UTF-8"; // 默認值

    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
        String configEncoding = filterConfig.getInitParameter("encoding");
        if (configEncoding != null && !configEncoding.isEmpty()) {
            this.encoding = configEncoding;
        }
    }

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        
        // 1. 設置請求字符編碼（解決 POST 請求體亂碼）
        if (request.getCharacterEncoding() == null) {
            request.setCharacterEncoding(encoding);
        }
        
        // 2. 設置響應內容類型與字符編碼（解決輸出亂碼）
        response.setContentType("text/html;charset=" + encoding);
        response.setCharacterEncoding(encoding);
        
        // 3. 繼續鏈路
        chain.doFilter(request, response);
    }

    @Override
    public void destroy() {
        // 清理資源（如有）
    }
}

2. web.xml 配置方式（傳統項目）

<filter>
    <filter-name>CharacterEncodingFilter</filter-name>
    <filter-class>cn.com.filter.CharacterEncodingFilter</filter-class>
    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>CharacterEncodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

全鏈路編碼一致性清單

進階：Spring Boot 自動配置

Spring Boot 2.1+ 默認提供 CharacterEncodingFilter，只需配置：

# application.yml
server:
  servlet:
    encoding:
      charset: UTF-8
      enabled: true
      force: true # 強制覆蓋請求/響應編碼
      force-request: true
      force-response: true

常見誤區避坑

1. 只設置 response.setContentType 不設置 request 編碼：POST 請求體仍會亂碼。
2. Filter 映射順序錯誤：編碼 Filter 必須在最前面（web.xml 中第一個 filter-mapping），確保後續 Servlet/Filter 讀取到正確編碼。
3. GET 請求亂碼：需在 Tomcat server.xml 的 Connector 添加 URIEncoding="UTF-8"，或 Spring Boot 配置 server.tomcat.uri-encoding=UTF-8。
4. 混用 GBK/UTF-8：歷史項目遷移時務必全站統一，否則極難排查。

總結

解決中文亂碼的核心是建立全鏈路 UTF-8 編碼閉環。通過 Filter 統一請求/響應編碼，配合頁面、數據庫、容器、構建工具的協同配置，可徹底消除亂碼問題。現代項目優先使用 Spring Boot 自動配置，傳統項目按本文 Filter 模板標準化部署。