Maven Shade重定位AWS依赖后SQS客户端请求处理链实例化失败的解决方案咨询

Let’s start by aligning on your scenario—this is a super common pain point when shading AWS SDK v1 dependencies:

• You’re using aws-java-sdk-sqs to interact with SQS
• You configured Maven Shade to relocate AWS classes from com.amazonaws to com.shaded.amazonaws with this config:

<relocation>
  <pattern>com.amazonaws</pattern>
  <shadedPattern>com.shaded.amazonaws</shadedPattern>
</relocation>

• When creating your SQS client with:

AmazonSQS amazonSQS = AmazonSQSClientBuilder.standard().withRegion(region).build();

• You hit this error:

com.shaded.amazonaws.AmazonClientException: Unable to instantiate request handler chain for client: Unable to instantiate request handler chain for client. Listed request handler ('com.amazonaws.services.sqs.QueueUrlHandler') does not implement the interface com.shaded.amazonaws.handlers.RequestHandler API.

Root Cause #

As you correctly identified, the Maven Shade plugin doesn’t automatically update the fully qualified class names inside the request.handlers and request.handler2s resource files. These files (stored at /com/amazonaws/services/sqs/request.handlers and /com/amazonaws/services/sqs/request.handler2s) list the request handler classes the client needs to load—but they still reference the original com.amazonaws package path instead of your shaded com.shaded.amazonaws path. When the client tries to load these handlers, it pulls in unrelocated classes that don’t match the shaded RequestHandler interface, causing the mismatch error.

Solution 1: Add a Resource Transformer to Maven Shade #

The cleanest, most maintainable fix is to add a content replacement transformer to your Shade plugin configuration. This will modify the text inside those resource files to replace the old package name with the shaded one.

Add this transformer inside the <transformers> section of your Shade plugin config:

<transformer implementation="org.apache.maven.plugins.shade.resource.ReplaceContentTransformer">
  <resource>**/request.handlers</resource>
  <resource>**/request.handler2s</resource>
  <replaceString>com.amazonaws</replaceString>
  <replacementString>com.shaded.amazonaws</replacementString>
</transformer>

Your full Shade plugin config will look something like this:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.4.1</version> <!-- Use the latest compatible version for your project -->
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
      <configuration>
        <relocations>
          <relocation>
            <pattern>com.amazonaws</pattern>
            <shadedPattern>com.shaded.amazonaws</shadedPattern>
          </relocation>
        </relocations>
        <transformers>
          <!-- Keep your existing manifest transformer if you have one -->
          <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
            <mainClass>your.main.class.path.Here</mainClass>
          </transformer>
          <!-- Add the content replacement transformer here -->
          <transformer implementation="org.apache.maven.plugins.shade.resource.ReplaceContentTransformer">
            <resource>**/request.handlers</resource>
            <resource>**/request.handler2s</resource>
            <replaceString>com.amazonaws</replaceString>
            <replacementString>com.shaded.amazonaws</replacementString>
          </transformer>
        </transformers>
      </configuration>
    </execution>
  </executions>
</plugin>

This transformer scans all request.handlers and request.handler2s files across your dependencies, replacing every instance of com.amazonaws with com.shaded.amazonaws. This ensures the client loads handlers from the correct shaded package, matching the relocated interface.

Alternative Solutions #

If the transformer doesn’t fit your setup for some reason, here are two fallback options:

• Manual resource file editing: Extract the AWS SQS JAR, edit the request.handlers and request.handler2s files to update the package names, then repackage the JAR. This is error-prone and not ideal for ongoing builds.
• Upgrade to AWS SDK v2: The v2 SDK (e.g., software.amazon.awssdk:sqs) uses a different architecture that avoids these resource file/classpath conflicts when shading. If you’re open to upgrading, this is a more future-proof solution.

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