SpringBoot Multipart表单中文乱码解决方案

浏览器/客户端                    Tomcat 容器               Spring MVC              业务代码
     │                              │                        │                      │
     │── HTTP请求 ──→               │                        │                      │
     │  Content-Type:               │                        │                      │
     │  multipart/form-data;        │                        │                      │
     │  boundary=----xxx            │                        │                      │
     │                              │── 解析请求体 ──→        │                      │
     │                              │  request.getParameter() │                      │
     │                              │  使用什么编码？          │                      │
     │                              │                        │── 绑定参数到方法 ──→   │
     │                              │                        │  @RequestParam        │
     │                              │                        │                      │── 使用参数

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

原始文本："张三"

UTF-8 编码字节：     E5 BC A0  E4 B8 89  （6个字节）

用 ISO-8859-1 解码这6个字节：
  E5 → å
  BC → ¼（实际显示可能不同）
  A0 →  （不可见）
  E4 → ä
  B8 → ¸
  89 → ‰

结果：乱码字符串 "å¼ ä¸‰"

// 正确：在读取参数前设置
request.setCharacterEncoding("UTF-8");
String name = request.getParameter("name"); // 用 UTF-8 解码
// 错误：在读取参数后设置（无效）
String name = request.getParameter("name"); // 已经用默认编码解码了
request.setCharacterEncoding("UTF-8");      // 为时已晚

public class CharacterEncodingFilter extends OncePerRequestFilter {

    private String encoding;
    private boolean forceRequestEncoding = false;
    private boolean forceResponseEncoding = false;

    @Override
    protected void doFilterInternal(HttpServletRequest request, 
            HttpServletResponse response, FilterChain filterChain) {

        // 如果请求没有设置编码，或者强制覆盖
        if (this.encoding != null) {
            if (this.forceRequestEncoding || request.getCharacterEncoding() == null) {
                request.setCharacterEncoding(this.encoding);
            }
            if (this.forceResponseEncoding) {
                response.setCharacterEncoding(this.encoding);
            }
        }

        filterChain.doFilter(request, response);
    }
}

请求 → Filter1(编码) → Filter2(安全) → Filter3(日志) → DispatcherServlet → Controller

如果编码Filter不在第一个位置，安全Filter可能先读取了参数，
此时编码已经用默认ISO-8859-1解码了，后面再设置UTF-8也没用。

spring:
  servlet:
    encoding:
      charset: UTF-8
      enabled: true
      force: true

@Bean
public FilterRegistrationBean<Filter> encodingFilter() {
    CharacterEncodingFilter filter = new CharacterEncodingFilter();
    filter.setEncoding("UTF-8");
    filter.setForceRequestEncoding(true);
    filter.setForceResponseEncoding(true);

    FilterRegistrationBean<Filter> reg = new FilterRegistrationBean<>();
    reg.setFilter(filter);
    reg.addUrlPatterns("/api/xxx/import");  // 只对特定接口
    reg.setOrder(Integer.MIN_VALUE);
    return reg;
}

// 应急方案，不推荐长期使用
String name = new String(
    rawName.getBytes(StandardCharsets.ISO_8859_1), 
    StandardCharsets.UTF_8
);

// 方式一：在 FormData 的 Blob 中指定 type
const formData = new FormData();
formData.append('file', file);
formData.append('name', new Blob([JSON.stringify('张三')], { type: 'text/plain; charset=UTF-8' }));

// 方式二：使用 fetch 时不需要额外设置，浏览器默认用 UTF-8 编码 FormData
fetch('/api/import', { method: 'POST', body: formData });

package com.example.controller;

import com.example.dto.UploadResultDto;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

/**
 * 文件上传接口.
 */
@RestController
@RequestMapping("/api/file")
public class FileUploadController {

  @PostMapping("/upload")
  public UploadResultDto upload(
      @RequestParam("file") MultipartFile file,
      @RequestParam("remark") String remark,
      @RequestParam("uploaderName") String uploaderName) {

    // 此时 remark 和 uploaderName 已经是正确的 UTF-8 字符串
    UploadResultDto result = new UploadResultDto();
    result.setFileName(file.getOriginalFilename());
    result.setFileSize(file.getSize());
    result.setRemark(remark);
    result.setUploaderName(uploaderName);
    return result;
  }
}

package com.example.dto;

import lombok.Data;

@Data
public class UploadResultDto {
  private String fileName;
  private Long fileSize;
  private String remark;
  private String uploaderName;
}

package com.example.config;

import jakarta.servlet.Filter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.filter.CharacterEncodingFilter;

/**
 * 字符编码过滤器，解决 multipart/form-data 中文乱码.
 */
@Configuration
public class EncodingConfig {

  @Bean
  public FilterRegistrationBean<Filter> uploadEncodingFilter() {
    // 1. 创建编码过滤器
    CharacterEncodingFilter filter = new CharacterEncodingFilter();
    filter.setEncoding("UTF-8");
    filter.setForceRequestEncoding(true);   // 强制请求编码
    filter.setForceResponseEncoding(true);  // 强制响应编码

    // 2. 注册到 Servlet 容器
    FilterRegistrationBean<Filter> registration = new FilterRegistrationBean<>();
    registration.setFilter(filter);

    // 3. 指定生效的 URL（只对上传接口）
    registration.addUrlPatterns("/api/file/upload");

    // 4. 设置最高优先级，确保在所有其他 Filter 之前执行
    registration.setOrder(Integer.MIN_VALUE);

    return registration;
  }
}

curl -X POST http://localhost:8080/api/file/upload \
  -F "file=@测试文件.xlsx" \
  -F "remark=这是一条中文备注" \
  -F "uploaderName=张三"

{
  "fileName": "测试文件.xlsx",
  "fileSize": 12345,
  "remark": "这是一条中文备注",
  "uploaderName": "张三"
}

{
  "fileName": "测试文件.xlsx",
  "fileSize": 12345,
  "remark": "è¿æ¯ä¸æ¡ä¸­æå¤æ³¨",
  "uploaderName": "å¼ ä¸"
}

问题本质：
  multipart/form-data 请求的 Content-Type 不携带 charset
  → Tomcat 用默认 ISO-8859-1 解码
  → UTF-8 字节被错误解码为乱码

解决本质：
  在 Tomcat 读取参数之前，告诉它"请用 UTF-8 解码"
  → CharacterEncodingFilter 在 Filter 链最前面调用 request.setCharacterEncoding("UTF-8")
  → 后续所有参数读取都使用 UTF-8