Tomcat部署非Spring Boot Spring Rest接口Multipart表单编码错误排查

部署在Tomcat Servlet容器中的Spring REST接口（非Spring Boot）接收Multipart表单时，德语变音符号（如ö、ä、ü）出现乱码，其他非Multipart接口工作正常，使用JavaScript fetch或Postman测试均复现该问题。

接口核心代码：

@PostMapping(value = "/audit/{auditNumber}/file", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<?> uploadFileForAudit(//
        @PathVariable String peNumber, //
        @RequestParam("category") String category, //
        @RequestParam("documents") MultipartFile file, //
        @RequestParam("description") String description, //
        @RequestHeader Map<String, String> headers) {


    System.out.println("category "+category);
    System.out.println("description "+description);

控制台乱码输出示例：

category Prüfungsanordnung
description öäü

排查与解决建议 #

• 调整Tomcat的Multipart编码配置
  Tomcat默认对Multipart表单参数采用ISO-8859-1编码，需手动指定为UTF-8：

  1. 编辑Tomcat conf/server.xml，在Connector标签添加编码配置：

     <Connector port="8080" protocol="HTTP/1.1"
                connectionTimeout="20000"
                redirectPort="8443"
                URIEncoding="UTF-8"
                useBodyEncodingForURI="true"/>
     

  2. 可在conf/web.xml中配置Spring的MultipartFilter并指定编码：

     <filter>
         <filter-name>multipartFilter</filter-name>
         <filter-class>org.springframework.web.multipart.support.MultipartFilter</filter-class>
         <init-param>
             <param-name>encoding</param-name>
             <param-value>UTF-8</param-value>
         </init-param>
     </filter>
     <filter-mapping>
         <filter-name>multipartFilter</filter-name>
         <url-pattern>/*</url-pattern>
     </filter-mapping>
     

• 配置Spring的MultipartResolver编码
  若手动配置了CommonsMultipartResolver，需设置默认编码：

  @Bean
  public CommonsMultipartResolver multipartResolver() {
      CommonsMultipartResolver resolver = new CommonsMultipartResolver();
      resolver.setDefaultEncoding("UTF-8");
      // 可添加上传大小限制等其他配置
      return resolver;
  }
  

  若使用StandardServletMultipartResolver，则依赖Tomcat的Connector编码配置，确保已完成第一步的设置。

• 验证请求头的Content-Type编码
  确认请求的Content-Type是否指定charset=utf-8，示例：
  Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryxxxx; charset=utf-8
  手动指定后可验证是否为请求编码导致的问题。

• 排查控制台输出编码问题
  部分情况乱码仅为控制台编码不匹配，而非参数接收错误：

  1. 用日志框架（如SLF4J）将参数输出到UTF-8编码的日志文件验证；
  2. 临时在代码中转换编码测试：

     String correctedCategory = new String(category.getBytes("ISO-8859-1"), "UTF-8");
     System.out.println("corrected category: " + correctedCategory);
     

     若转换后输出正常，说明Tomcat的Multipart解析确实使用了ISO-8859-1编码。

• 调整编码过滤器顺序
  确保UTF-8编码过滤器在Multipart过滤器之前执行，配置示例：

  <filter>
      <filter-name>encodingFilter</filter-name>
      <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
      <init-param>
          <param-name>encoding</param-name>
          <param-value>UTF-8</param-value>
      </init-param>
      <init-param>
          <param-name>forceEncoding</param-name>
          <param-value>true</param-value>
      </init-param>
  </filter>
  <filter-mapping>
      <filter-name>encodingFilter</filter-name>
      <url-pattern>/*</url-pattern>
      <dispatcher>REQUEST</dispatcher>
      <dispatcher>FORWARD</dispatcher>
  </filter-mapping>
  

内容的提问来源于stack exchange，提问作者phe