Spring Boot 3迁移后@SqsListener无法消费SQS消息求助

常见问题&解决步骤 #

1. AWS SDK版本不兼容 #

Spring Boot 3 默认绑定AWS SDK v2，而Spring Boot 2大多使用SDK v1，版本不匹配会直接导致消费失效：

• 检查pom.xml或build.gradle，将AWS相关依赖替换为**Spring Cloud AWS 3.x+**版本的spring-cloud-starter-aws-messaging，确保适配SDK v2
• 把旧代码中的AmazonSQS客户端全部替换为SqsClient（SDK v2标准客户端）

2. IAM角色权限校验逻辑变更 #

即便集群IAM角色权限未改动，Spring Boot 3的AWS客户端对权限的校验更严格：

• 必须确保IAM角色拥有sqs:ReceiveMessage、sqs:DeleteMessage、sqs:GetQueueAttributes这三个核心权限
• 如果SQS队列开启了加密，还需额外添加kms:Decrypt权限（针对AWS KMS加密场景）

3. Spring Cloud AWS自动配置缩减 #

Spring Boot 3对应的Spring Cloud AWS 3.0+版本取消了部分自动配置，需要手动补充：

• 在application.properties/application.yml中明确配置SQS区域和端点（自定义区域或本地测试场景必备）：

  spring.cloud.aws.region.static=us-east-1
  spring.cloud.aws.sqs.endpoint=https://sqs.us-east-1.amazonaws.com
  

• 若存在冲突的自动配置类，直接排除：

  @SpringBootApplication(exclude = {AwsAutoConfiguration.class})
  

4. @SqsListener注解属性调整 #

Spring Cloud AWS 3.x对@SqsListener的属性做了调整，旧写法可能失效：

• 原Boot2中用value指定队列名，Boot3建议使用queueNames：

  // Boot2 写法
  @SqsListener("my-queue")
  // Boot3 写法
  @SqsListener(queueNames = "my-queue")
  

• 若自定义了消息转换的messageHandlerMethodFactory，需要适配SDK v2的消息格式，否则无法解析消息

5. 开启日志定位问题 #

开启AWS SDK和Spring Cloud AWS的DEBUG日志，直接查看具体报错信息：

• 在配置文件中添加：

  logging.level software.amazon.awssdk=DEBUG
  logging.level org.springframework.cloud.aws.messaging=DEBUG
  

  重点关注权限拒绝、队列不存在、客户端初始化失败这类日志，快速定位根因

社区反馈情况 #

确实有大量开发者在Spring Boot 3迁移过程中遇到该问题，核心集中在SDK版本切换、自动配置变更这两个点。比如Spring Cloud AWS的GitHub Issues中，很多用户提到升级后必须手动配置区域和端点，或者将SDK v1客户端替换为v2才能恢复消费。

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