SpringBoot+OpenAPI接口含附件时ASCII符号编码异常求助

开发基于Spring Boot + OpenAPI的sendEmail接口，请求体包含toAddress、subject、emailBodyAsHtml（对应OpenAPI定义中的bodyHtml）和attachments参数。OpenAPI YAML核心定义如下：

bodyHtml:
  type: String
attachments:
  type: array
  items:
    format: binary
    type: String
encoding:
  attachments:
    contentType: application/pdf
  bodyHtml:
    contentType: text/html;charset=UTF-8

发送请求时，bodyHtml的原始内容为：

<html><body><p>Price is 100€</p></body></html>

但控制器接收后，欧元符号变成乱码：

<html><body><p>Price is 100??</p></body></html>

移除可选的attachments参数后，编码恢复正常，服务部署在AWS环境中。

• 配置Multipart请求默认编码
  当请求包含二进制附件时，会自动转为multipart/form-data格式，Spring Boot默认的Multipart解析器可能未指定UTF-8编码，导致文本参数解码错误。在application.properties中添加：

  spring.servlet.multipart.charset=UTF-8
  

  或application.yml：

  spring:
    servlet:
      multipart:
        charset: UTF-8
  

• 修正OpenAPI YAML的请求体定义
  当前的encoding配置未明确关联到multipart/form-data类型，需完善请求体的完整定义，确保参数编码规则被正确识别：

  requestBody:
    content:
      multipart/form-data:
        schema:
          type: object
          properties:
            toAddress:
              type: string
            subject:
              type: string
            bodyHtml:
              type: string
            attachments:
              type: array
              items:
                type: string
                format: binary
        encoding:
          bodyHtml:
            contentType: text/html;charset=UTF-8
          attachments:
            contentType: application/pdf
  

  必须显式指定content类型为multipart/form-data，并将所有请求参数纳入schema的properties中，避免生成的代码解析逻辑混乱。

• 强制OpenAPI Generator使用UTF-8生成代码
  若使用OpenAPI Generator生成接口代码，需在生成时指定Multipart编码参数。如果是命令行生成：

  openapi-generator generate -i your-spec.yml -g spring --additional-properties=javaMultipartCharset=UTF-8
  

  若是Maven插件，在pom.xml中配置：

  <plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <configuration>
      <inputSpec>${project.basedir}/src/main/resources/openapi.yml</inputSpec>
      <generatorName>spring</generatorName>
      <additionalProperties>
        <javaMultipartCharset>UTF-8</javaMultipartCharset>
      </additionalProperties>
    </configuration>
  </plugin>
  

• AWS环境编码检查

  • 负载均衡（ALB/NLB）：检查监听器规则，确保未修改Content-Type请求头，避免charset=UTF-8参数被丢弃。
  • 实例/容器编码：登录AWS实例或容器，检查系统默认编码：

    echo $LANG
    

    若输出不是UTF-8编码，在服务启动脚本中添加：

    export LANG=en_US.UTF-8
    export LC_ALL=en_US.UTF-8
    

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