运行GCP Dataflow Flex模板报NoClassDefFoundError:DoFn异常如何解决

在GCP Dataflow中使用Flex模板启动作业时抛出启动异常：

Error: Unable to initialize main class. 
com.mycompany.pubsubdfjobs.protocol1_0.PubSubRedis

根异常为：java.lang.NoClassDefFoundError: org/apache/beam/sdk/transforms/DoFn
本地运行代码无异常，build.gradle中已声明所有依赖，构建Flex模板的Dockerfile中也已复制build.gradle文件。

该问题和是否将build.gradle复制到Docker镜像无关，核心原因是最终构建出的Flex模板镜像内的运行JAR没有包含Apache Beam的核心依赖，属于Fat JAR打包配置错误：

• 本地直接通过Gradle运行代码时，Gradle会自动将所有声明的依赖加入运行时类路径，因此不会出现类找不到的问题
• Dataflow Flex模板启动时直接运行镜像内打包好的JAR，如果构建出的是仅包含业务代码的瘦包，镜像运行环境又没有提前预置Beam相关依赖，JVM加载主类时就会找不到DoFn这类Beam核心类，直接抛出NoClassDefFoundError。

常见触发场景：

• Gradle构建配置未引入Fat JAR打包插件，默认jar task打出的包不包含第三方依赖
• 引入了打包插件，但错误将Beam核心依赖标记为compileOnly/provided作用域，打包阶段自动排除了这部分依赖
• Dockerfile中执行Gradle构建时调用了错误的task，没有触发依赖打包逻辑，最终拷贝到运行层的是瘦包。

按以下步骤逐一排查调整：

1. 修正Gradle打包配置
   在build.gradle中引入Shadow打包插件（Gradle生态常用的Fat JAR打包工具），确保所有运行时依赖被打入最终JAR，参考配置如下：

   plugins {
       id 'java'
       // 引入Shadow插件，版本选择和你本地Gradle版本兼容的即可
       id 'com.github.johnrengelman.shadow' version '7.1.2'
   }
   
   dependencies {
       // 注意Beam依赖不要用compileOnly/provided声明，使用implementation即可
       implementation "org.apache.beam:beam-sdks-java-core:你项目中使用的Beam版本号"
       // 其余业务依赖正常声明
   }
   
   shadowJar {
       mergeServiceFiles() // 必须配置，处理Beam依赖中的SPI服务配置文件，避免打包后出现服务加载失败
       archiveClassifier.set("") // 用Shadow打出的包替换默认jar task的输出
       manifest {
           // 显式指定主类，避免启动时找不到主类
           attributes 'Main-Class': 'com.mycompany.pubsubdfjobs.protocol1_0.PubSubRedis'
       }
   }
   

2. 修正Dockerfile构建逻辑
   确保Docker构建阶段执行shadowJar task完成Fat JAR构建，同时确认拷贝到运行层的是Shadow打出的包含依赖的JAR包，核心参考配置：

   # 构建层
   FROM gradle:7.6-jdk11 AS builder
   WORKDIR /workspace
   COPY gradle gradlew build.gradle settings.gradle ./
   RUN ./gradlew dependencies --no-daemon
   COPY src ./src
   # 执行shadowJar构建，不要调用默认的jar/build task
   RUN ./gradlew clean shadowJar --no-daemon
   
   # 运行层
   FROM openjdk:11-jre-slim
   WORKDIR /app
   # 从构建层拷贝打好的Fat JAR
   COPY --from=builder /workspace/build/libs/*.jar ./app.jar
   ENTRYPOINT ["java", "-jar", "/app/app.jar"]
   

3. 本地预验证
   本地先执行./gradlew shadowJar，然后直接通过java -jar build/libs/对应生成的jar包名.jar运行，如果本地直接运行JAR不报类找不到的错误，再重新构建镜像、上传Flex模板即可。

补充注意：使用的Apache Beam版本需要和Dataflow运行环境支持的版本对齐，避免后续出现版本兼容类问题。

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