Spring Boot集成AWS SQS时@SqsListener无法消费队列消息问题求助

问题解决方案 #

按优先级排查以下项：

• 1. 缺失@EnableSqs注解

  必须在启动类或者SQS配置类上添加@EnableSqs注解，否则@SqsListener不会被Spring容器注册，自然不会监听消费，且无任何报错。
  示例代码：

  @SpringBootApplication
  @EnableSqs // 必须添加该注解
  public class DemoApplication {
      public static void main(String[] args) {
          SpringApplication.run(DemoApplication.class, args);
      }
  }
  

• 2. 队列地址配置错误

  @SqsListener的value属性在官方AWS环境下不能填写Localstack的完整HTTP路径，只能填写队列名称，只有Localstack测试环境支持填写完整URL。多环境下建议通过配置项注入，不要硬编码地址。
  修正示例：

  // 仅Localstack测试可填完整URL，官方环境直接填写队列名即可
  @SqsListener(value = {"employeeTest"}, deletionPolicy = SqsMessageDeletionPolicy.ON_SUCCESS)
  public void receiveMessage(String stringJson) {
      logger.info("Message Received using SQS Listener " + stringJson);
  }
  

• 3. AWS客户端配置异常

  检查application.yml/application.properties中是否有正确的SQS相关配置，本地测试时必须禁用Spring Cloud AWS的自动栈检测和元数据region获取，否则会导致客户端初始化异常但无显性报错：

  cloud:
    aws:
      stack:
        auto: false # 禁用CloudFormation栈自动检测
      region:
        static: us-east-1 # 替换为你队列实际所在region，Localstack默认用us-east-1
      credentials:
        access-key: test # Localstack随便填有效值即可，官方环境填实际凭证
        secret-key: test
  

  另外要确认你使用的AWS凭证有sqs:ReceiveMessage、sqs:DeleteMessage、sqs:GetQueueUrl权限，发送消息只需要sqs:SendMessage权限，消费需要额外权限。

• 4. 版本兼容性问题

  你使用的spring-cloud-aws:2.2.6.RELEASE仅支持Spring Boot 2.3.x/2.4.x版本，如果你的Spring Boot版本高于2.4.x（比如2.7+或者3.x），会因为jakarta/servlet包不兼容导致监听器不生效且无报错，建议升级Spring Cloud AWS到对应匹配版本，或者降级Spring Boot到兼容版本。

• 5. 消息序列化校验

  如果以上配置都没问题，可以先把监听器入参改为原始SQS消息类型，跳过序列化转换，验证是否能收到消息：

  @SqsListener(value = {"employeeTest"}, deletionPolicy = SqsMessageDeletionPolicy.ON_SUCCESS)
  public void receiveMessage(com.amazonaws.services.sqs.model.Message message) {
      logger.info("原始消息内容：{}", message.getBody());
  }
  

  如果能收到原始消息，说明你配置的全局消息转换器和发送的消息格式不兼容，调整序列化配置即可。

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