Java AWS Lambda拉取GCP Pub/Sub时遇ClassNotFoundException求助

问题场景 #

用Java开发AWS Lambda拉取GCP Pub/Sub队列消息，获取SubscriberStub的代码如下：

private static SubscriberStub getSubscriber() throws IOException {
    SubscriberStubSettings subscriberStubSettings =
            SubscriberStubSettings.newBuilder()
                    .setCredentialsProvider(new GcpCredentialsUtil().getCredentialsProvider())
                    .setTransportChannelProvider(
                            SubscriberStubSettings.defaultGrpcTransportProviderBuilder()
                                    .setMaxInboundMessageSize(20 * 1024 * 1024) // 20MB (maximum message size).
                                    .setKeepAliveWithoutCalls(false)
                                    .build())
                    .build();
    return GrpcSubscriberStub.create(subscriberStubSettings);
}

Maven依赖配置：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>libraries-bom</artifactId>
            <version>26.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.google.cloud</groupId>
        <artifactId>google-cloud-pubsub</artifactId>
    </dependency>
</dependencies>

本地运行Lambda时出现错误：

com/google/api/gax/rpc/TransportChannelProvider: java.lang.NoClassDefFoundError
java.lang.NoClassDefFoundError: com/google/api/gax/rpc/TransportChannelProvider
        at lambdas.teams.ProcessMessageLambda.handleRequest(ProcessMessageLambda.java:33)
        at lambdas.teams.ProcessMessageLambda.handleRequest(ProcessMessageLambda.java:15)
Caused by: java.lang.ClassNotFoundException: com.google.api.gax.rpc.TransportChannelProvider
        at java.net.URLClassLoader.findClass(URLClassLoader.java:387)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:418)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:351)
        ... 2 more

本地M2仓库存在TransportChannelProvider类，但运行时环境缺失，以下是解决思路：

解决思路 #

• 调整Maven打包方式：AWS Lambda需要包含所有依赖的fat jar才能正常运行，普通打包只会包含自身代码，依赖不会被打入。使用maven-shade-plugin构建fat jar，配置示例：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.4.1</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <createDependencyReducedPom>false</createDependencyReducedPom>
                        <transformers>
                            <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                                <!-- 替换为你的Lambda入口类 -->
                                <mainClass>lambdas.teams.ProcessMessageLambda</mainClass>
                            </transformer>
                        </transformers>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

• 确认依赖传递有效性：执行mvn dependency:tree查看依赖树，确认com.google.api:gax（包含目标类）是否被正确引入，是否存在依赖冲突或被排除的情况。如果发现依赖缺失，手动添加：

<dependency>
    <groupId>com.google.api</groupId>
    <artifactId>gax</artifactId>
</dependency>

• 对齐运行时JDK版本：确保本地编译使用的JDK版本和AWS Lambda配置的运行时版本（如Corretto 8/11）一致，版本不匹配可能导致类兼容性问题。
• 验证打包产物内容：解压打包后的jar包，检查com/google/api/gax/rpc/TransportChannelProvider.class是否存在。如果不存在，调整shade插件配置，排除不必要的过滤规则，或重新确认依赖引入是否正确。
• 排查BOM版本兼容性：尝试升级或降级libraries-bom版本（如换成25.12.0或26.1.0），重新打包测试，确认版本间的兼容性问题。

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