Spring Cloud AWS SQS PayloadTypeHeader配置报错求助：跨服务消息解析问题

问题根源 #

两个服务各自定义了同名称但不同包路径的PayloadWrapper类，而Spring Cloud AWS SQS默认的消息转换器会在消息头中写入JavaType（类的全限定名），导致接收方无法识别发送方的类路径，从而反序列化失败。你遇到的payload must be instance of String: [B异常，是因为错误配置了消息转换器（比如误用StringMessageConverter），导致字节数组与字符串类型不匹配。

正确配置方案 #

核心思路是自定义消息转换器，禁用JavaType的序列化/反序列化，让消息以纯JSON格式传输，接收方直接将JSON反序列化为本地的PayloadWrapper类。

1. 发送方（ServiceA）配置

自定义SqsTemplate，使用MappingJackson2MessageConverter并禁用类型信息写入：

@Configuration
public class SqsSenderConfig {

    @Bean
    public SqsTemplate sqsTemplate(SqsAsyncClient sqsAsyncClient, ObjectMapper objectMapper) {
        MappingJackson2MessageConverter converter = new MappingJackson2MessageConverter();
        // 禁用Jackson自动写入类型信息，只输出纯JSON
        objectMapper.disable(SerializationFeature.WRITE_TYPE_INFO_AS_PROPERTY);
        converter.setObjectMapper(objectMapper);

        return SqsTemplate.builder(sqsAsyncClient)
                .messageConverter(converter)
                .build();
    }
}

发送消息时直接传入PayloadWrapper实例即可：

sqsTemplate.send("your-queue-name", Message.builder().payload(payloadWrapper).build());

2. 接收方（ServiceB）配置

配置消息监听容器工厂，使用同样的转换器，指定本地PayloadWrapper为反序列化目标：

@Configuration
public class SqsReceiverConfig {

    @Bean
    public SimpleMessageListenerContainerFactory sqsListenerContainerFactory(SqsAsyncClient sqsAsyncClient, ObjectMapper objectMapper) {
        MappingJackson2MessageConverter converter = new MappingJackson2MessageConverter();
        // 禁用类型信息读取，直接反序列化为本地类
        converter.setObjectMapper(objectMapper);
        converter.setTargetType(PayloadWrapper.class);

        SimpleMessageListenerContainerFactory factory = new SimpleMessageListenerContainerFactory();
        factory.setSqsAsyncClient(sqsAsyncClient);
        factory.setMessageConverter(converter);
        return factory;
    }
}

监听方法直接接收本地PayloadWrapper：

@SqsListener("your-queue-name")
public void processMessage(@Payload PayloadWrapper payload) {
    // 业务逻辑处理
}

关键注意事项 #

• 两个服务的PayloadWrapper类必须字段完全一致：包括字段名、类型、Jackson注解（如@JsonProperty），否则会出现字段缺失或类型不匹配的解析错误。
• 确保两边的ObjectMapper配置统一：比如日期格式化规则、空值处理策略、枚举序列化方式等，避免JSON解析差异。
• 不要混用不同类型的消息转换器：比如发送方用Jackson转换器，接收方不能用String转换器，否则会触发类型不匹配异常。

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