Spring版本升级后文件上传报DecoderException问题的原因及解决方法求助

应用环境与问题背景 #

• 微服务：Spring Boot 1.3.5.RELEASE，JDK 8
• 应用：Spring Framework 5.3.15，JDK 8
• 功能：应用上传Excel文件后由上述微服务处理，该功能在应用基于Spring 4.2.1.RELEASE时运行正常，升级至Spring 5.3.15后出现报错。

报错信息 #

io.netty.handler.codec.DecoderException: java.lang.NoClassDefFoundError: org/owasp/esapi/errors/EncodingException
    at io.netty.handler.codec.ByteToMessageDecoder.callDecode(ByteToMessageDecoder.java:278) ~[netty-all-4.0.24.Final.jar:4.0.24.Final]
    at io.netty.handler.codec.ByteToMessageDecoder.channelRead(ByteToMessageDecoder.java:147) ~[netty-all-4.0.24.Final.jar:4.0.24.Final]

可能原因及解决办法 #

1. ESAPI依赖未正确引入或运行时类路径缺失 #

虽然升级了ESAPI，但可能存在以下情况：

• 依赖的scope被设置为provided或test，导致打包时未包含进最终产物；
• 构建工具（Maven/Gradle）的配置问题，导致依赖未被正确拉取或打包。

解决办法：

• 检查项目依赖声明，确保ESAPI的scope为compile（Maven）或implementation（Gradle）：

  <!-- Maven 示例 -->
  <dependency>
      <groupId>org.owasp.esapi</groupId>
      <artifactId>esapi</artifactId>
      <version>2.2.3.1</version> <!-- 推荐使用兼容JDK8的稳定版本 -->
      <scope>compile</scope>
  </dependency>
  

• 执行mvn clean install（Maven）或gradle clean build（Gradle）重新构建，确保依赖被正确打包到应用/微服务的jar包中。

2. 版本兼容性冲突 #

Spring 5.3.15、Spring Boot 1.3.5与最新版ESAPI可能存在依赖冲突：

• Spring 5.x引入的部分依赖与ESAPI新版本不兼容；
• 微服务使用的Netty 4.0.24.Final与新版ESAPI存在类加载或依赖冲突。

解决办法：

• 执行依赖树分析命令，排查是否存在ESAPI的多版本冲突：

  # Maven 查看依赖树
  mvn dependency:tree | grep esapi
  # Gradle 查看依赖树
  gradle dependencies | grep esapi
  

• 排除冲突的旧版本ESAPI依赖，或降级ESAPI至兼容Spring 5.3.15和JDK8的稳定版本（如2.2.3.1），避免使用要求更高JDK版本的最新版。

3. ESAPI核心配置文件缺失 #

ESAPI运行时必须依赖ESAPI.properties和validation.properties配置文件，若这些文件缺失，可能引发类加载异常（表现为NoClassDefFoundError）。

解决办法：

• 从ESAPI官方包中获取这两个配置文件，放置到项目的src/main/resources目录下；
• 确保配置文件中关键配置项正确，例如：

  # ESAPI.properties 示例关键配置
  ESAPI.Encoder=org.owasp.esapi.reference.DefaultEncoder
  ESAPI.Validator=org.owasp.esapi.reference.DefaultValidator
  

4. 类加载器隔离问题 #

微服务（Spring Boot 1.3.5）与应用（Spring 5.3.15）的类加载器层级不同，可能导致ESAPI的类无法被微服务的类加载器正确加载。

解决办法：

• 若使用Spring Cloud等微服务架构，检查是否存在类加载器隔离配置（如spring-boot-devtools可能影响类加载），必要时移除相关配置；
• 确保ESAPI依赖在微服务项目中直接声明，而非仅通过应用传递依赖，避免类加载器无法获取到目标类。

5. JDK字节码兼容性问题 #

部分最新版ESAPI可能使用JDK9+的字节码特性编译，导致JDK8环境下无法加载类。

解决办法：

• 查看ESAPI版本文档，确认其支持的JDK版本；
• 若最新版要求JDK11+，则降级至支持JDK8的ESAPI版本（如2.2.3.1）。

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