Back to Details

sqs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Amazon SQS Core Knowledge

Amazon SQS 核心知识

Full Reference: See advanced.md for Java/Python/Go producers, Spring Cloud AWS consumers, Lambda integration, IAM policies, and CloudWatch monitoring.
Deep Knowledge: Use 
mcp__documentation__fetch_docs
with technology: 
sqs
for comprehensive documentation.
完整参考：查看 advanced.md 了解 Java/Python/Go 生产者、Spring Cloud AWS 消费者、Lambda 集成、IAM 策略、CloudWatch 监控相关内容。
深度知识：使用 
mcp__documentation__fetch_docs
指定 technology 为 
sqs
获取完整文档。

Quick Start (LocalStack)

快速开始（LocalStack）

yaml
undefined
yaml
undefined

docker-compose.yml

docker-compose.yml

services: localstack: image: localstack/localstack ports: - "4566:4566" environment: - SERVICES=sqs - DEFAULT_REGION=us-east-1 volumes: - localstack_data:/var/lib/localstack
volumes: localstack_data:

```bash
services: localstack: image: localstack/localstack ports: - "4566:4566" environment: - SERVICES=sqs - DEFAULT_REGION=us-east-1 volumes: - localstack_data:/var/lib/localstack
volumes: localstack_data:

```bash

Create queue

Create queue

aws --endpoint-url=http://localhost:4566 sqs create-queue
--queue-name orders-queue
aws --endpoint-url=http://localhost:4566 sqs create-queue
--queue-name orders-queue

Create FIFO queue

Create FIFO queue

aws --endpoint-url=http://localhost:4566 sqs create-queue
--queue-name orders-queue.fifo
--attributes FifoQueue=true,ContentBasedDeduplication=true
undefined
aws --endpoint-url=http://localhost:4566 sqs create-queue
--queue-name orders-queue.fifo
--attributes FifoQueue=true,ContentBasedDeduplication=true
undefined

Core Concepts

核心概念

ConceptDescription
Standard QueueAt-least-once, best-effort ordering
FIFO QueueExactly-once, strict ordering
Visibility TimeoutMessage lock period
Dead Letter QueueFailed message destination
Long PollingEfficient message retrieval
Message GroupsFIFO ordering within group
概念描述
Standard Queue至少一次投递，尽力排序
FIFO Queue恰好一次投递，严格排序
Visibility Timeout消息锁定周期
Dead Letter Queue失败消息的存储目的地
Long Polling高效的消息检索方式
Message GroupsFIFO 队列中组内严格排序

Queue Types Comparison

队列类型对比

FeatureStandardFIFO
ThroughputUnlimited300 msg/s (3000 with batching)
OrderingBest-effortStrict (per group)
DeliveryAt-least-onceExactly-once
DeduplicationNone5-minute window
特性标准队列FIFO 队列
吞吐量无限制300 条/秒（批量发送可达 3000 条/秒）
排序能力尽力排序严格排序（组维度）
投递模式至少一次投递恰好一次投递
去重能力无5 分钟窗口去重

Producer Pattern (Node.js)

生产者实现（Node.js）

typescript
import { SQSClient, SendMessageCommand, SendMessageBatchCommand } from '@aws-sdk/client-sqs';

const client = new SQSClient({
  region: 'us-east-1',
  // For LocalStack: endpoint: 'http://localhost:4566',
});

const queueUrl = 'https://sqs.us-east-1.amazonaws.com/123456789/orders-queue';

// Send single message
await client.send(new SendMessageCommand({
  QueueUrl: queueUrl,
  MessageBody: JSON.stringify(order),
  MessageAttributes: {
    'OrderType': {
      DataType: 'String',
      StringValue: order.type,
    },
    'CorrelationId': {
      DataType: 'String',
      StringValue: correlationId,
    },
  },
  DelaySeconds: 0,
}));

// Send batch (up to 10)
await client.send(new SendMessageBatchCommand({
  QueueUrl: queueUrl,
  Entries: orders.map((order, index) => ({
    Id: `msg-${index}`,
    MessageBody: JSON.stringify(order),
    MessageAttributes: {
      'OrderType': { DataType: 'String', StringValue: order.type },
    },
  })),
}));

// FIFO queue
const fifoQueueUrl = 'https://sqs.us-east-1.amazonaws.com/123456789/orders-queue.fifo';

await client.send(new SendMessageCommand({
  QueueUrl: fifoQueueUrl,
  MessageBody: JSON.stringify(order),
  MessageGroupId: order.customerId,      // Required for FIFO
  MessageDeduplicationId: order.orderId, // Or use ContentBasedDeduplication
}));
typescript
import { SQSClient, SendMessageCommand, SendMessageBatchCommand } from '@aws-sdk/client-sqs';

const client = new SQSClient({
  region: 'us-east-1',
  // For LocalStack: endpoint: 'http://localhost:4566',
});

const queueUrl = 'https://sqs.us-east-1.amazonaws.com/123456789/orders-queue';

// Send single message
await client.send(new SendMessageCommand({
  QueueUrl: queueUrl,
  MessageBody: JSON.stringify(order),
  MessageAttributes: {
    'OrderType': {
      DataType: 'String',
      StringValue: order.type,
    },
    'CorrelationId': {
      DataType: 'String',
      StringValue: correlationId,
    },
  },
  DelaySeconds: 0,
}));

// Send batch (up to 10)
await client.send(new SendMessageBatchCommand({
  QueueUrl: queueUrl,
  Entries: orders.map((order, index) => ({
    Id: `msg-${index}`,
    MessageBody: JSON.stringify(order),
    MessageAttributes: {
      'OrderType': { DataType: 'String', StringValue: order.type },
    },
  })),
}));

// FIFO queue
const fifoQueueUrl = 'https://sqs.us-east-1.amazonaws.com/123456789/orders-queue.fifo';

await client.send(new SendMessageCommand({
  QueueUrl: fifoQueueUrl,
  MessageBody: JSON.stringify(order),
  MessageGroupId: order.customerId,      // Required for FIFO
  MessageDeduplicationId: order.orderId, // Or use ContentBasedDeduplication
}));

Consumer Pattern (Node.js)

消费者实现（Node.js）

typescript
import { SQSClient, ReceiveMessageCommand, DeleteMessageCommand } from '@aws-sdk/client-sqs';

const client = new SQSClient({ region: 'us-east-1' });

async function pollMessages() {
  while (true) {
    const response = await client.send(new ReceiveMessageCommand({
      QueueUrl: queueUrl,
      MaxNumberOfMessages: 10,
      WaitTimeSeconds: 20,           // Long polling
      VisibilityTimeout: 30,
      MessageAttributeNames: ['All'],
      AttributeNames: ['All'],
    }));

    if (!response.Messages) continue;

    for (const message of response.Messages) {
      try {
        const order = JSON.parse(message.Body!);
        await processOrder(order);

        // Delete on success
        await client.send(new DeleteMessageCommand({
          QueueUrl: queueUrl,
          ReceiptHandle: message.ReceiptHandle!,
        }));
      } catch (error) {
        // Message will return to queue after visibility timeout
        console.error('Processing failed:', error);
      }
    }
  }
}
typescript
import { SQSClient, ReceiveMessageCommand, DeleteMessageCommand } from '@aws-sdk/client-sqs';

const client = new SQSClient({ region: 'us-east-1' });

async function pollMessages() {
  while (true) {
    const response = await client.send(new ReceiveMessageCommand({
      QueueUrl: queueUrl,
      MaxNumberOfMessages: 10,
      WaitTimeSeconds: 20,           // Long polling
      VisibilityTimeout: 30,
      MessageAttributeNames: ['All'],
      AttributeNames: ['All'],
    }));

    if (!response.Messages) continue;

    for (const message of response.Messages) {
      try {
        const order = JSON.parse(message.Body!);
        await processOrder(order);

        // Delete on success
        await client.send(new DeleteMessageCommand({
          QueueUrl: queueUrl,
          ReceiptHandle: message.ReceiptHandle!,
        }));
      } catch (error) {
        // Message will return to queue after visibility timeout
        console.error('Processing failed:', error);
      }
    }
  }
}

Dead Letter Queue

死信队列配置

typescript
// Create DLQ
await client.send(new CreateQueueCommand({
  QueueName: 'orders-dlq',
}));

// Main queue with DLQ
await client.send(new CreateQueueCommand({
  QueueName: 'orders-queue',
  Attributes: {
    RedrivePolicy: JSON.stringify({
      deadLetterTargetArn: 'arn:aws:sqs:us-east-1:123456789:orders-dlq',
      maxReceiveCount: '3',
    }),
    VisibilityTimeout: '30',
    MessageRetentionPeriod: '1209600', // 14 days
  },
}));
hcl
undefined
typescript
// Create DLQ
await client.send(new CreateQueueCommand({
  QueueName: 'orders-dlq',
}));

// Main queue with DLQ
await client.send(new CreateQueueCommand({
  QueueName: 'orders-queue',
  Attributes: {
    RedrivePolicy: JSON.stringify({
      deadLetterTargetArn: 'arn:aws:sqs:us-east-1:123456789:orders-dlq',
      maxReceiveCount: '3',
    }),
    VisibilityTimeout: '30',
    MessageRetentionPeriod: '1209600', // 14 days
  },
}));
hcl
undefined

Terraform

Terraform

resource "aws_sqs_queue" "orders_dlq" { name = "orders-dlq" message_retention_seconds = 1209600 }
resource "aws_sqs_queue" "orders" { name = "orders-queue" visibility_timeout_seconds = 30 message_retention_seconds = 1209600
redrive_policy = jsonencode({ deadLetterTargetArn = aws_sqs_queue.orders_dlq.arn maxReceiveCount = 3 }) }
undefined
resource "aws_sqs_queue" "orders_dlq" { name = "orders-dlq" message_retention_seconds = 1209600 }
resource "aws_sqs_queue" "orders" { name = "orders-queue" visibility_timeout_seconds = 30 message_retention_seconds = 1209600
redrive_policy = jsonencode({ deadLetterTargetArn = aws_sqs_queue.orders_dlq.arn maxReceiveCount = 3 }) }
undefined

Lambda Integration

Lambda 集成

typescript
// Lambda handler
export const handler = async (event: SQSEvent): Promise<SQSBatchResponse> => {
  const batchItemFailures: SQSBatchItemFailure[] = [];

  for (const record of event.Records) {
    try {
      const order = JSON.parse(record.body);
      await processOrder(order);
    } catch (error) {
      // Report partial batch failure
      batchItemFailures.push({ itemIdentifier: record.messageId });
    }
  }

  return { batchItemFailures };
};
yaml
undefined
typescript
// Lambda handler
export const handler = async (event: SQSEvent): Promise<SQSBatchResponse> => {
  const batchItemFailures: SQSBatchItemFailure[] = [];

  for (const record of event.Records) {
    try {
      const order = JSON.parse(record.body);
      await processOrder(order);
    } catch (error) {
      // Report partial batch failure
      batchItemFailures.push({ itemIdentifier: record.messageId });
    }
  }

  return { batchItemFailures };
};
yaml
undefined

serverless.yml

serverless.yml

functions: orderProcessor: handler: handler.handler events: - sqs: arn: !GetAtt OrdersQueue.Arn batchSize: 10 functionResponseType: ReportBatchItemFailures
undefined
functions: orderProcessor: handler: handler.handler events: - sqs: arn: !GetAtt OrdersQueue.Arn batchSize: 10 functionResponseType: ReportBatchItemFailures
undefined

When NOT to Use This Skill

不适用场景

Use alternative messaging solutions when:
  • Event streaming with replay - Use Kinesis or Kafka
  • Cross-cloud or hybrid cloud - Use Kafka, RabbitMQ, or Pulsar
  • Complex routing patterns - RabbitMQ provides better routing
  • Message ordering across all messages - FIFO queues have throughput limits
  • Real-time low latency (<10ms) - Use Redis or NATS
  • On-premise deployment - Use RabbitMQ or ActiveMQ
  • Message size >256KB - Use S3 with SQS Extended Client
遇到以下情况时请选择替代消息方案：
  • 需要可回放的事件流 - 使用 Kinesis 或 Kafka
  • 跨云或混合云部署 - 使用 Kafka、RabbitMQ 或 Pulsar
  • 复杂路由需求 - RabbitMQ 提供更完善的路由能力
  • 全量消息全局排序 - FIFO 队列存在吞吐量限制
  • 超低延迟实时场景（<10ms） - 使用 Redis 或 NATS
  • 本地部署场景 - 使用 RabbitMQ 或 ActiveMQ
  • 消息大小超过 256KB - 搭配 SQS Extended Client 使用 S3 存储大消息

Anti-Patterns

反模式说明

Anti-PatternWhy It's BadSolution
Short polling (WaitTime=0)Wasteful API calls, higher costUse long polling (WaitTimeSeconds=20)
No DLQ configuredFailed messages lostAlways configure dead letter queue
Visibility timeout too shortDuplicate processingSet timeout > max processing time
Visibility timeout too longSlow failure recoveryBalance with processing time
Processing before deleteMessage reprocessed on crashDelete only after successful processing
FIFO for high throughputLimited to 300 msg/sUse Standard queue if ordering not critical
No batchingHigher latency and costBatch up to 10 messages per request
Polling in LambdaWasted invocationsUse Lambda event source mapping
No IAM policiesSecurity riskApply least privilege IAM policies
反模式缺陷解决方案
短轮询（WaitTime=0）API 调用冗余、成本更高使用长轮询（WaitTimeSeconds=20）
未配置死信队列失败消息会丢失始终配置死信队列
可见性超时设置过短重复处理消息超时时间设置为大于最大处理耗时
可见性超时设置过长故障恢复速度慢结合处理耗时合理配置
处理消息前先删除程序崩溃时消息会被重复处理仅在处理成功后删除消息
高吞吐量场景使用 FIFO 队列吞吐量上限仅 300 条/秒非强排序需求使用标准队列
不使用批量发送延迟高、成本高单请求最多批量发送 10 条消息
Lambda 中自行轮询队列浪费函数调用资源使用 Lambda 事件源映射能力
未配置 IAM 策略存在安全风险遵循最小权限原则配置 IAM 策略

Quick Troubleshooting

快速排障指南

IssueLikely CauseFix
Messages not appearingWrong queue URL or permissionsVerify URL and IAM permissions
Duplicate messagesStandard queue behavior or visibility timeoutImplement idempotent processing
Messages delayedDelay seconds set or queue backlogCheck DelaySeconds, scale consumers
Messages in DLQMax receives exceededCheck processing logic, increase retries
Visibility timeout errorsMessage processing too slowExtend visibility timeout
Throughput limitedFIFO queue limitUse Standard queue or batch messages
High costsShort polling or frequent sendsUse long polling, batch operations
Access deniedMissing IAM permissionsAdd sqs:SendMessage/ReceiveMessage
Message size limitPayload >256KBUse SQS Extended Client with S3
问题可能原因修复方案
消息未出现在队列中队列 URL 错误或权限不足校验队列 URL 和 IAM 权限
消息重复投递标准队列默认特性或可见性超时过短实现消费幂等逻辑
消息投递延迟设置了延迟时间或队列存在积压检查 DelaySeconds 配置，扩容消费者
消息进入死信队列超过最大消费次数检查消费逻辑，调整重试次数
可见性超时错误消息处理耗时过长延长可见性超时时间
吞吐量受限达到 FIFO 队列上限切换为标准队列或使用批量发送
使用成本过高短轮询或高频单次发送使用长轮询、批量操作
访问被拒绝缺少 IAM 权限新增 sqs:SendMessage/ReceiveMessage 权限
消息大小超限负载超过 256KB搭配 S3 使用 SQS Extended Client

Production Checklist

生产环境检查清单

  • IAM policies with least privilege
  • Server-side encryption enabled
  • Dead letter queue configured
  • Visibility timeout set appropriately
  • Long polling enabled (20s)
  • Message retention configured
  • CloudWatch alarms set up
  • DLQ monitoring alerts
  • VPC endpoints (if needed)
  • Access logging enabled
  • 配置了最小权限的 IAM 策略
  • 开启了服务端加密
  • 配置了死信队列
  • 可见性超时配置合理
  • 开启了长轮询（20s）
  • 配置了消息保留周期
  • 配置了 CloudWatch 告警
  • 配置了死信队列监控告警
  • 按需配置了 VPC 端点
  • 开启了访问日志

Key Metrics to Monitor

核心监控指标

MetricAlert Threshold
ApproximateNumberOfMessagesVisible> 10000
ApproximateAgeOfOldestMessage> 3600s
NumberOfMessagesReceivedAnomaly
NumberOfMessagesSentAnomaly
ApproximateNumberOfMessagesNotVisible> expected
指标告警阈值
队列中待消费消息数（ApproximateNumberOfMessagesVisible）> 10000
最旧消息留存时间（ApproximateAgeOfOldestMessage）> 3600s
消费消息数（NumberOfMessagesReceived）异常波动
发送消息数（NumberOfMessagesSent）异常波动
处理中消息数（ApproximateNumberOfMessagesNotVisible）超过预期值

Reference Documentation

参考文档

Deep Knowledge: Use 
mcp__documentation__fetch_docs
with technology: 
sqs
for comprehensive documentation.
Available topics: 
basics
, 
producers
, 
consumers
, 
dlq
, 
production
深度知识：使用 
mcp__documentation__fetch_docs
指定 technology 为 
sqs
获取完整文档。
可用主题：
basics
、
producers
、
consumers
、
dlq
、
production