Consumidores AWS SQS

Q: Pacote npm sqs-consumer?

sqs-consumer encapsula o polling com eventos. Bom para workers ECS. Entenda a semântica de visibilidade de qualquer forma.

Q: Quantos pollers?

Escalone os consumidores pela métrica ApproximateNumberOfMessagesVisible. Evite loops apertados duplicados sem long polling.

Q: IAM para worker?

sqs:ReceiveMessage, DeleteMessage, ChangeMessageVisibility apenas no ARN da fila.

Q: Enfileirar API Express?

SendMessageCommand da API com corpo JSON pequeno. Mesmas regras de idempotência do produtor BullMQ.

O Amazon SQS oferece filas gerenciadas sem a necessidade de operar Redis. Workers Node.js utilizam o AWS SDK v3 com long polling, timeouts de visibilidade e filas de mensagens mortas (DLQ).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import {
  SQSClient,
  ReceiveMessageCommand,
  DeleteMessageCommand,
} from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({});
const queueUrl = process.env.SQS_QUEUE_URL!;
 
const res = await sqs.send(
  new ReceiveMessageCommand({
    QueueUrl: queueUrl,
    MaxNumberOfMessages: 10,
    WaitTimeSeconds: 20,
    VisibilityTimeout: 60,
  })
);
 
for (const msg of res.Messages ?? []) {
  await processBody(msg.Body!);
  await sqs.send(
    new DeleteMessageCommand({ QueueUrl: queueUrl, ReceiptHandle: msg.ReceiptHandle! })
  );
}

Quando usar isso:

Pilha nativa da AWS sem Redis
Necessidade de escalabilidade gerenciada e precificação por mensagem
Fan-out entre contas ou regiões com SNS

Exemplo de Trabalho

// src/sqs/poll.ts
import {
  SQSClient,
  ReceiveMessageCommand,
  DeleteMessageCommand,
  ChangeMessageVisibilityCommand,
} from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({ region: process.env.AWS_REGION });
const queueUrl = process.env.SQS_QUEUE_URL!;
 
async function handleMessage(body: string) {
  const payload = JSON.parse(body) as { type: string; orderId: string };
  if (payload.type === "fulfill") {
    await fulfillOrder(payload.orderId);
  }
}
 
export async function pollForever(signal: AbortSignal) {
  while (!signal.aborted) {
    const res = await sqs.send(
      new ReceiveMessageCommand({
        QueueUrl: queueUrl,
        MaxNumberOfMessages: 10,
        WaitTimeSeconds: 20,
        VisibilityTimeout: 120,
        MessageAttributeNames: ["All"],
      })
    );
 
    for (const msg of res.Messages ?? []) {
      try {
        await handleMessage(msg.Body ?? "{}");
        await sqs.send(
          new DeleteMessageCommand({
            QueueUrl: queueUrl,
            ReceiptHandle: msg.ReceiptHandle!,
          })
        );
      } catch (err) {
        console.error({ msg: "sqs_handler_error", messageId: msg.MessageId, err });
        // A mensagem retorna para a fila após o timeout de visibilidade
      }
    }
  }
}
 
// src/worker-main.ts
const ac = new AbortController();
process.on("SIGTERM", () => ac.abort());
await pollForever(ac.signal);

O que isso demonstra:

Long poll WaitTimeSeconds: 20 reduz custo e uso de CPU
Exclusão apenas após o handler bem-sucedido
Falha do handler depende da nova tentativa de timeout de visibilidade (além da DLQ em nível de infraestrutura)

Mergulho Profundo

Matemática do Timeout de Visibilidade

visibility_timeout >= p99_processing_time * 1.5

Muito curto: processamento duplicado enquanto o primeiro handler ainda está em execução
Muito longo: nova tentativa lenta em caso de falha
Estender com ChangeMessageVisibility para trabalhos de duração variável

Dead-Letter Queue (Infraestrutura)

{
  "RedrivePolicy": {
    "deadLetterTargetArn": "arn:aws:sqs:...:dlq",
    "maxReceiveCount": 5
  }
}

Após 5 recebimentos falhados, a mensagem é movida para a DLQ
Runbook: inspecionar DLQ, corrigir bug, reenviar mensagens

FIFO vs Standard

Tipo	Ordenação	Throughput	Deduplicação
Standard	Melhor esforço	Muito alto	Idempotência em nível de aplicativo
FIFO	Por grupo de mensagens	300 TPS/grupo	Deduplicação de conteúdo opcional

Pagamentos e inventário frequentemente usam FIFO com MessageGroupId

// O corpo da mensagem pode ser um JSON wrapper do SNS - desembrulhar o Envelope
const outer = JSON.parse(body);
const inner = outer.Message ? JSON.parse(outer.Message) : outer;

Falha Parcial de Lote do SDK v3 (Lambda)

O mapeamento de origem de eventos SQS da Lambda suporta falhas de itens em lote
O loop de long polling do ECS/EC2 lida com uma mensagem por vez ou confirmação manual em lote

Armadilhas

Excluir antes de concluir o trabalho - perda de mensagem. Correção: excluir por último.
Visibilidade mais curta que o trabalho - preenchimentos duplicados. Correção: estender a visibilidade ou aumentar o timeout.
Sem DLQ - loop infinito de mensagens venenosas. Correção: maxReceiveCount + alarme DLQ.
Análise incorreta do wrapper SNS - handlers silenciosamente inoperantes. Correção: desembrulhar o campo Message.
Ignorar idempotência - entrega "pelo menos uma vez" duplica o trabalho. Correção: chaves de idempotência no banco de dados.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
BullMQ	Redis já em execução, API rica de jobs	Desejar infraestrutura de fila zero
Kinesis	Análise de streaming	Fila de tarefas simples
EventBridge	Regras de roteamento de eventos	Apenas fila de workers ponto a ponto
Google Pub/Sub	Pilha GCP	Organização apenas com AWS

FAQs

Pacote npm sqs-consumer?

sqs-consumer encapsula o polling com eventos. Bom para workers ECS. Entenda a semântica de visibilidade de qualquer forma.

Quantos pollers?

Escalone os consumidores pela métrica ApproximateNumberOfMessagesVisible. Evite loops apertados duplicados sem long polling.

Exatamente uma vez?

Não. A fila padrão é "pelo menos uma vez". Projete handlers idempotentes.

Payloads grandes?

Use o padrão de cliente estendido S3 - SQS carrega o ponteiro S3 quando >256KB.

IAM para worker?

sqs:ReceiveMessage, DeleteMessage, ChangeMessageVisibility apenas no ARN da fila.

Desenvolvimento local?

LocalStack ou ElasticMQ para testes de integração. Docker ElasticMQ para laptop.

Enfileirar API Express?

SendMessageCommand da API com corpo JSON pequeno. Mesmas regras de idempotência do produtor BullMQ.

Retenção de mensagem?

Padrão de 4 dias. Aumente para 14 para janelas de repetição durante interrupções.

Throughput FIFO?

Batching e múltiplos IDs de grupo de mensagens escalam fluxos ordenados paralelos.

Drivers de custo?

Contagem de requisições. Long polling reduz recebimentos vazios. Receba em lote até 10 mensagens.

Relacionados

Básicos de Filas - modelo mental assíncrono
AWS SDK v3 - configuração do cliente
Chaves de Idempotência - entrega duplicada
BullMQ - alternativa Redis
Melhores Práticas de Filas - runbooks DLQ

Versões da Pilha: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import {
  SQSClient,
  ReceiveMessageCommand,
  DeleteMessageCommand,
} from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({});
const queueUrl = process.env.SQS_QUEUE_URL!;
 
const res = await sqs.send(
  new ReceiveMessageCommand({
    QueueUrl: queueUrl,
    MaxNumberOfMessages: 10,
    WaitTimeSeconds: 20,
    VisibilityTimeout: 60,
  })
);
 
for (const msg of res.Messages ?? []) {
  await processBody(msg.Body!);
  await sqs.send(
    new DeleteMessageCommand({ QueueUrl: queueUrl, ReceiptHandle: msg.ReceiptHandle! })
  );
}

Quando usar isso:

Pilha nativa da AWS sem Redis
Necessidade de escalabilidade gerenciada e precificação por mensagem
Fan-out entre contas ou regiões com SNS

Exemplo de Trabalho

// src/sqs/poll.ts
import {
  SQSClient,
  ReceiveMessageCommand,
  DeleteMessageCommand,
  ChangeMessageVisibilityCommand,
} from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({ region: process.env.AWS_REGION });
const queueUrl = process.env.SQS_QUEUE_URL!;
 
async function handleMessage(body: string) {
  const payload = JSON.parse(body) as { type: string; orderId: string };
  if (payload.type === "fulfill") {
    await fulfillOrder(payload.orderId);
  }
}
 
export async function pollForever(signal: AbortSignal) {
  while (!signal.aborted) {
    const res = await sqs.send(
      new ReceiveMessageCommand({
        QueueUrl: queueUrl,
        MaxNumberOfMessages: 10,
        WaitTimeSeconds: 20,
        VisibilityTimeout: 120,
        MessageAttributeNames: ["All"],
      })
    );
 
    for (const msg of res.Messages ?? []) {
      try {
        await handleMessage(msg.Body ?? "{}");
        await sqs.send(
          new DeleteMessageCommand({
            QueueUrl: queueUrl,
            ReceiptHandle: msg.ReceiptHandle!,
          })
        );
      } catch (err) {
        console.error({ msg: "sqs_handler_error", messageId: msg.MessageId, err });
        // A mensagem retorna para a fila após o timeout de visibilidade
      }
    }
  }
}
 
// src/worker-main.ts
const ac = new AbortController();
process.on("SIGTERM", () => ac.abort());
await pollForever(ac.signal);

O que isso demonstra:

Long poll WaitTimeSeconds: 20 reduz custo e uso de CPU
Exclusão apenas após o handler bem-sucedido
Falha do handler depende da nova tentativa de timeout de visibilidade (além da DLQ em nível de infraestrutura)

Mergulho Profundo

Matemática do Timeout de Visibilidade

visibility_timeout >= p99_processing_time * 1.5

Muito curto: processamento duplicado enquanto o primeiro handler ainda está em execução
Muito longo: nova tentativa lenta em caso de falha
Estender com ChangeMessageVisibility para trabalhos de duração variável

Dead-Letter Queue (Infraestrutura)

{
  "RedrivePolicy": {
    "deadLetterTargetArn": "arn:aws:sqs:...:dlq",
    "maxReceiveCount": 5
  }
}

Após 5 recebimentos falhados, a mensagem é movida para a DLQ
Runbook: inspecionar DLQ, corrigir bug, reenviar mensagens

FIFO vs Standard

Tipo	Ordenação	Throughput	Deduplicação
Standard	Melhor esforço	Muito alto	Idempotência em nível de aplicativo
FIFO	Por grupo de mensagens	300 TPS/grupo	Deduplicação de conteúdo opcional

Pagamentos e inventário frequentemente usam FIFO com MessageGroupId

// O corpo da mensagem pode ser um JSON wrapper do SNS - desembrulhar o Envelope
const outer = JSON.parse(body);
const inner = outer.Message ? JSON.parse(outer.Message) : outer;

Falha Parcial de Lote do SDK v3 (Lambda)

O mapeamento de origem de eventos SQS da Lambda suporta falhas de itens em lote
O loop de long polling do ECS/EC2 lida com uma mensagem por vez ou confirmação manual em lote

Armadilhas

Excluir antes de concluir o trabalho - perda de mensagem. Correção: excluir por último.
Visibilidade mais curta que o trabalho - preenchimentos duplicados. Correção: estender a visibilidade ou aumentar o timeout.
Sem DLQ - loop infinito de mensagens venenosas. Correção: maxReceiveCount + alarme DLQ.
Análise incorreta do wrapper SNS - handlers silenciosamente inoperantes. Correção: desembrulhar o campo Message.
Ignorar idempotência - entrega "pelo menos uma vez" duplica o trabalho. Correção: chaves de idempotência no banco de dados.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
BullMQ	Redis já em execução, API rica de jobs	Desejar infraestrutura de fila zero
Kinesis	Análise de streaming	Fila de tarefas simples
EventBridge	Regras de roteamento de eventos	Apenas fila de workers ponto a ponto
Google Pub/Sub	Pilha GCP	Organização apenas com AWS

FAQs

Pacote npm sqs-consumer?

sqs-consumer encapsula o polling com eventos. Bom para workers ECS. Entenda a semântica de visibilidade de qualquer forma.

Quantos pollers?

Escalone os consumidores pela métrica ApproximateNumberOfMessagesVisible. Evite loops apertados duplicados sem long polling.

Exatamente uma vez?

Não. A fila padrão é "pelo menos uma vez". Projete handlers idempotentes.

Payloads grandes?

Use o padrão de cliente estendido S3 - SQS carrega o ponteiro S3 quando >256KB.

IAM para worker?

sqs:ReceiveMessage, DeleteMessage, ChangeMessageVisibility apenas no ARN da fila.

Desenvolvimento local?

LocalStack ou ElasticMQ para testes de integração. Docker ElasticMQ para laptop.

Enfileirar API Express?

SendMessageCommand da API com corpo JSON pequeno. Mesmas regras de idempotência do produtor BullMQ.

Retenção de mensagem?

Padrão de 4 dias. Aumente para 14 para janelas de repetição durante interrupções.

Throughput FIFO?

Batching e múltiplos IDs de grupo de mensagens escalam fluxos ordenados paralelos.

Drivers de custo?

Contagem de requisições. Long polling reduz recebimentos vazios. Receba em lote até 10 mensagens.

Relacionados

Básicos de Filas - modelo mental assíncrono
AWS SDK v3 - configuração do cliente
Chaves de Idempotência - entrega duplicada
BullMQ - alternativa Redis
Melhores Práticas de Filas - runbooks DLQ

Versões da Pilha: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Consumidores AWS SQS

Buscar na documentação

Consumidores AWS SQS