SpringBoot非UTF-8请求配置方法

本文深入解析了Spring Boot应用处理非UTF-8编码请求时，常见的乱码问题及解决方案。重点强调了客户端请求编码与Content-Type头声明一致性的重要性，并揭示了使用curl命令模拟不同编码请求时可能存在的陷阱，提供了创建和发送正确编码请求的详细步骤，确保模拟测试的准确性。同时，分析了Spring Boot的字符编码处理机制，包括Servlet容器、HttpMessageConverter以及相关配置的影响。针对无法控制客户端编码行为的特殊情况，提出了使用RequestBodyAdvice进行自定义处理的方案。强调了UTF-8编码的优势，并推荐尽可能统一使用UTF-8编码，从而避免编码问题。通过本文，开发者能够更好地理解Spring Boot的字符编码处理逻辑，掌握排查和解决乱码问题的有效方法，提升应用在复杂环境下的兼容性和稳定性。

问题剖析：非UTF-8请求的乱码现象

在Spring Boot应用中，当处理来自遗留系统或特定客户端的请求时，可能会遇到请求体编码与预期不符导致乱码的问题。典型的场景是，客户端发送的JSON数据声称使用Windows-1252编码，但服务端接收后却出现字符错乱。

例如，一个包含特殊字符（如çâãéüûà）的JSON请求：

{
    "text": "Apenas um teste técnico çâãéüûà"
}

当客户端声称使用charset=Windows-1252发送此请求时，Spring Boot应用日志中可能会出现以下乱码：

Read "application/json;charset=Windows-1252" to [MyString{text='Apenas um teste técnico çâãéüûà'}]

而如果客户端使用charset=UTF-8发送相同的请求，则一切正常：

Read "application/json;charset=UTF-8" to [MyString{text='Apenas um teste técnico çâãéüûà'}]

这表明Spring Boot的RequestResponseBodyMethodProcessor在尝试根据Content-Type头中的charset信息来解码请求体。当charset被指定为Windows-1252时，如果传入的字节流实际上是UTF-8编码的，就会导致上述乱码。

根源揭示：客户端测试的陷阱

上述乱码现象的核心原因往往不在于Spring Boot的配置，而在于客户端在模拟请求时，发送的字节流与声明的编码不符。

以curl命令为例，当您直接在命令行中输入或粘贴包含特殊字符的JSON字符串，并使用--data参数发送时，curl默认会以您的终端或系统默认编码（通常是UTF-8）来编码该字符串。即使您在Content-Type头中明确指定了charset=Windows-1252，curl发送的字节流仍然是UTF-8编码的。

curl --request POST \
  --url http://localhost:8080/string-encoding/v1/my-string \
  --header 'Content-Type: application/json; charset=Windows-1252' \
  --data '{
    "text": "Apenas um teste técnico çâãéüûà"
}'

这条命令的真实意图是发送Windows-1252编码的数据，但它实际上发送的是UTF-8编码的字节。当Spring Boot接收到这些UTF-8字节，并被告知它们是Windows-1252时，它会尝试用Windows-1252解码器去解释UTF-8的字节序列，从而产生乱码。日志中Apenas um teste técnico çâãéüûà正是UTF-8编码的特殊字符在被Windows-1252解码时产生的典型结果。

正确模拟非UTF-8请求的方法

要正确模拟一个使用Windows-1252编码的请求，您需要确保实际发送的请求体数据是经过Windows-1252编码的字节流。这可以通过以下步骤实现：

1. 创建实际编码为Windows-1252的文件： 首先，将您的JSON内容保存到一个文件中，并确保该文件本身是Windows-1252编码的。您可以使用支持选择编码的文本编辑器（如Notepad++、VS Code、Sublime Text等）来创建并保存文件，选择Windows-1252或CP1252编码。

   或者，在Linux/macOS环境下，您可以使用iconv工具将UTF-8编码的字符串转换为Windows-1252编码并保存到文件：

   echo '{ "text": "Apenas um teste técnico çâãéüûà" }' | iconv -f UTF-8 -t Windows-1252 > test-1252.json

   验证文件编码（可选）：

   file -i test-1252.json
   # Output might be: test-1252.json: application/json; charset=windows-1252

2. 使用curl -d @filename发送文件： 一旦您有了正确编码的文件，就可以使用curl的-d @选项来发送文件内容。这样curl会直接读取文件的字节流并发送，而不是重新编码命令行参数。

   curl --request POST \
     --url http://localhost:8080/string-encoding/v1/my-string \
     --header 'Content-Type: application/json; charset=Windows-1252' \
     --data @test-1252.json

   通过这种方式，Spring Boot应用将接收到真正Windows-1252编码的字节流，并且由于Content-Type头也正确地声明了charset=Windows-1252，MappingJackson2HttpMessageConverter将能够正确地解码请求体，从而避免乱码。

Spring Boot的字符编码处理机制

Spring Boot应用（特别是基于Spring MVC的Web应用）对字符编码的处理主要依赖于以下几个层面：

1. Servlet容器（Tomcat/Jetty/Undertow）层面： 内嵌的Servlet容器会根据请求的Content-Type头中的charset参数来设置请求的字符编码。如果Content-Type头中没有charset，容器通常会使用默认编码（通常是ISO-8859-1），或者Spring Boot的server.servlet.encoding.charset配置。

2. Spring MVC的消息转换器（HttpMessageConverter）层面： 对于JSON或XML等结构化数据，Spring MVC会使用相应的HttpMessageConverter（如MappingJackson2HttpMessageConverter用于JSON）来反序列化请求体。这些转换器会优先遵循Content-Type头中指定的charset。这意味着，即使Servlet容器的默认编码是UTF-8，如果请求头明确指定了charset=Windows-1252，MappingJackson2HttpMessageConverter也会尝试用Windows-1252来解码。

3. Spring Boot的application.properties配置：

   • server.servlet.encoding.charset=UTF-8：此配置设置了Servlet容器的默认字符编码。它主要影响那些没有明确指定Content-Type编码的请求（如表单提交），以及响应的编码。
   • server.servlet.encoding.force=true：如果设置为true，则会强制使用server.servlet.encoding.charset指定的编码，即使请求头中指定了不同的编码。但对于请求体解析，通常HttpMessageConverter会优先使用Content-Type中的charset。

4. CharacterEncodingFilter： Spring Boot会自动注册一个CharacterEncodingFilter，其行为受server.servlet.encoding配置控制。这个过滤器可以在请求到达DispatcherServlet之前设置请求的字符编码。然而，对于像JSON这样的请求体，HttpMessageConverter通常会在过滤器之后进行处理，并再次根据Content-Type头来决定解码方式。

何时考虑自定义处理？

• RequestBodyAdvice： 如果您的客户端行为不可控，例如它们总是发送UTF-8字节但错误地声明为Windows-1252，并且您无法纠正客户端，那么您可能需要一个自定义的RequestBodyAdvice。这允许您在请求体被HttpMessageConverter处理之前，截获并手动重新编码或转换字节流。但这通常是最后的手段，因为它增加了复杂性。

  @ControllerAdvice
  public class CustomRequestBodyAdvice implements RequestBodyAdvice {
  
      @Override
      public boolean supports(MethodParameter methodParameter, Type targetType, Class> converterType) {
          // 只有当目标类型是MyString且转换器是MappingJackson2HttpMessageConverter时才应用
          return MyString.class.equals(targetType) && converterType.isAssignableFrom(MappingJackson2HttpMessageConverter.class);
      }
  
      @Override
      public HttpInputMessage beforeBodyRead(HttpInputMessage inputMessage, MethodParameter parameter, Type targetType, Class> converterType) throws IOException {
          MediaType contentType = inputMessage.getHeaders().getContentType();
          if (contentType != null && "Windows-1252".equalsIgnoreCase(contentType.getCharset().name())) {
              // 假设客户端发送的是UTF-8，但声明为Windows-1252
              // 这里需要读取原始字节流，然后以UTF-8解码，再重新包装成HttpInputMessage
              ByteArrayOutputStream buffer = new ByteArrayOutputStream();
              byte[] data = new byte[1024];
              int nRead;
              while ((nRead = inputMessage.getBody().read(data, 0, data.length)) != -1) {
                  buffer.write(data, 0, nRead);
              }
              buffer.flush();
              byte[] originalBytes = buffer.toByteArray();
  
              // 假设原始字节是UTF-8，但被错误地标记为Windows-1252
              // 我们需要将其作为UTF-8来处理，但保持Content-Type为Windows-1252
              // 实际上，更安全的做法是将其解码为String，然后以UTF-8重新编码
              String decodedString = new String(originalBytes, StandardCharsets.UTF_8);
              byte[] reEncodedBytes = decodedString.getBytes(StandardCharsets.UTF_8);
  
              // 返回一个新的HttpInputMessage，包含修正后的字节流和原始头部
              return new HttpInputMessage() {
                  @Override
                  public InputStream getBody() throws IOException {
                      return new ByteArrayInputStream(reEncodedBytes);
                  }
  
                  @Override
                  public HttpHeaders getHeaders() {
                      // 保持Content-Type不变，让后续的转换器以为它是Windows-1252，但实际字节是UTF-8
                      // 或者更彻底地，修改charset为UTF-8
                      HttpHeaders headers = inputMessage.getHeaders();
                      // headers.setContentType(new MediaType(contentType.getType(), contentType.getSubtype(), StandardCharsets.UTF_8)); // 这样可能更合理
                      return headers;
                  }
              };
          }
          return inputMessage; // 否则不作处理
      }
  
      @Override
      public Object afterBodyRead(Object body, HttpInputMessage inputMessage, MethodParameter parameter, Type targetType, Class> converterType) {
          return body;
      }
  
      @Override
      public Object handleEmptyBody(Object body, HttpInputMessage inputMessage, MethodParameter parameter, Type targetType, Class> converterType) {
          return body;
      }
  }

  请注意，上述RequestBodyAdvice的实现是针对特定场景的示例，实际应用中需要根据具体需求进行调整。通常，最佳实践是修复客户端的编码问题，而不是在服务端进行复杂的字节流转换。

• 自定义HttpMessageConverter： 如果需要对特定MIME类型和编码组合进行更细粒度的控制，可以注册一个自定义的HttpMessageConverter，使其优先于默认的转换器。

最佳实践与总结

1. 客户端与服务端编码一致性至关重要： 确保客户端在发送请求时，其数据编码与Content-Type头中声明的charset参数完全一致。这是解决字符编码问题的最根本方法。
2. 推荐使用UTF-8： 在现代应用开发中，UTF-8是处理字符编码的最佳选择，因为它支持几乎所有语言的字符，并且兼容ASCII。尽可能将所有系统（包括遗留系统）迁移到UTF-8。
3. 正确模拟测试场景： 在调试编码问题时，务必使用正确的方法来模拟不同编码的请求。对于文件内容，使用curl -d @filename并确保文件本身是目标编码。
4. 排查流程：
   • 检查HTTP请求的Content-Type头，确认charset参数是否正确。
   • 使用网络抓包工具（如Wireshark、Fiddler、Charles）检查实际发送的请求体字节流。
   • 检查Spring Boot日志中RequestResponseBodyMethodProcessor读取到的字符串，这能直观反映出解码后的结果。
   • 确认Spring Boot的server.servlet.encoding配置。
5. 遗留系统适配： 如果无法控制客户端的编码行为，并且客户端确实发送了非UTF-8编码的正确字节流，Spring Boot通常能通过Content-Type头正确处理。如果客户端行为不规范（例如发送UTF-8但声明非UTF-8），则可能需要服务端进行适配，但应谨慎考虑其复杂性。

总而言之，Spring Boot在处理字符编码方面是相当灵活和智能的，它会优先尊重HTTP Content-Type头中提供的编码信息。大多数乱码问题并非Spring Boot的缺陷，而是由于客户端发送的数据与声明的编码不一致所导致。理解这一核心原理，并掌握正确的测试和排查方法，是解决此类问题的关键。

以上就是《SpringBoot非UTF-8请求配置方法》的详细内容，更多关于的资料请关注golang学习网公众号！