System Design: dos requisitos a um fluxo confiável

TL;DR

System Design é decidir como as partes de um sistema de software funcionam juntas para atender às necessidades de um produto. É conectar a solicitação do usuário aos dados, ao processamento, às permissões e a um resultado verificável, incluindo o que acontece quando alguma coisa falha.

• Defina as promessas: quem pode fazer o quê, quanto pode demorar e o que precisa sobreviver.
• Escolha responsabilidades e contratos antes de escolher a infraestrutura.
• Inclua repetição, capacidade limitada e recuperação no desenho.

Vamos projetar um fluxo fictício de relatórios de despesas. Uma pessoa envia comprovantes, o sistema extrai os campos e disponibiliza um rascunho para revisão. Ele não aprova despesas nem movimenta dinheiro. REPORT-42 é um exemplo inventado, não um registro de uma empresa.

1. Começar pela promessa ao usuário

“Processar comprovantes” deixa decisões importantes em aberto. A pessoa pode fechar o navegador e voltar depois? Os arquivos precisam ficar restritos à organização dela? Como aparece um upload recusado? Alguém precisa conferir os valores extraídos? As respostas orientam a solução.

Neste exemplo, um trabalho aceito deve sobreviver ao reinício do worker, o usuário deve acompanhar o progresso e cada organização deve acessar apenas seus próprios documentos. Registre limites de tamanho, formatos aceitos e prazo de retenção. Combine uma meta de tempo de conclusão e como medi-la; evite inventar uma porcentagem só porque parece impressionante. O guia do Google sobre objetivos de serviço relaciona metas úteis ao comportamento percebido pelo usuário.

Separe requisitos de hipóteses. O volume esperado é uma estimativa até ser medido. Um mecanismo de recuperação proposto é um plano até ser implementado e testado. Preserve essa distinção no documento para que um diagrama não vire uma promessa de confiabilidade sem evidência.

2. Dar uma responsabilidade clara a cada parte

Comece com uma aplicação responsável pelo upload, pelas permissões e pelo status; um armazenamento durável para arquivos e registros; e um worker, um processo que executa tarefas em segundo plano. Tudo isso pode compartilhar a mesma base de código. A leitura dos arquivos fica atrás de uma interface clara, sem obrigar a página a conhecer cada formato.

Uma API, sigla em inglês para interface de programação de aplicações, é um contrato de comunicação. Aqui, ela especifica entradas válidas, identificação do relatório, estados possíveis e erros. A aplicação obtém a organização pela sessão autenticada. O identificador localiza um relatório; não concede acesso. Confira a permissão também nas consultas de status e nos downloads. A OWASP recomenda verificar a autorização em cada requisição.

Mantenha arquivos grandes no armazenamento de arquivos e passe referências para as tarefas. Defina quem é responsável pelo estado oficial do relatório e como ele muda. Um responsável claro facilita o raciocínio mais do que vários componentes decidindo, por conta própria, que o relatório terminou.

3. Separar aceitação de conclusão

Extrair dados de comprovantes pode levar mais tempo do que convém manter uma requisição aberta. Retorne o identificador depois que a aplicação registrar a responsabilidade pelo trabalho de forma durável e disponibilize o status separadamente. Aceitar significa registrar o trabalho; não significa terminar. A página pode mostrar na fila, processando, concluído ou falhou. A Microsoft descreve essa separação no padrão de requisição e resposta assíncronas.

Salvar um registro no banco e publicar uma mensagem na fila são duas gravações. Se a segunda falhar, o relatório pode ficar parado. Uma opção é o transactional outbox: salvar o relatório e um registro de envio na mesma transação do banco; outro processo publica o que está pendente. A publicação pode se repetir, então o consumidor ainda precisa se proteger contra duplicatas. A AWS documenta o problema das duas gravações e esse padrão de recuperação.

O upload também precisa de um ciclo de vida. Confirme que o arquivo está disponível antes de aceitar o trabalho e remova uploads abandonados depois do prazo definido. Registre uma falha compreensível quando o processamento não puder continuar. Atualizar a página deve recuperar o trabalho existente, sem criar outro relatório silenciosamente.

4. Tratar falhas e repetições explicitamente

Imagine que o resultado foi salvo, mas o worker caiu antes de confirmar a mensagem. A fila pode entregá-la novamente. Idempotência significa que repetir a mesma operação lógica preserva o efeito de negócio pretendido.

Associe ao envio uma chave de operação vinculada ao seu responsável. Confira se ela corresponde à entrada original, defina sua retenção e use uma transação ou atualização condicional para proteger o resultado contra tentativas simultâneas. Consultar “já existe?” antes de gravar, por si só, permite uma disputa entre workers. O guia da Amazon aborda identidade da requisição, mudança de intenção e tentativas tardias.

Um timeout indica que quem chamou parou de esperar; a operação remota pode ter dado certo. Antes de repetir um efeito externo, use a idempotência oferecida pelo provedor ou confira o status. Repita falhas temporárias com prazo, limite de tentativas e intervalos crescentes com pequenas variações aleatórias, chamadas jitter. Arquivos inválidos precisam de correção, não de tentativas infinitas. A Amazon explica como retentativas podem ampliar uma indisponibilidade sem esses controles.

5. Decidir o que acontece sob carga

Quando muitos relatórios chegam juntos, a fila pode guardar tarefas enquanto os workers processam em ritmo controlado. Isso também cria espera. Se as entradas continuarem acima das conclusões, o trabalho pendente cresce; uma fila não cria capacidade de processamento. O padrão de nivelamento de carga da Microsoft explica essa troca.

Limite tarefas simultâneas e a expansão dos arquivos em memória. Combine limites de admissão com limites de concorrência por organização ou agendamento justo para que um lote grande não ocupe todas as vagas. Proteja dependências compartilhadas considerando todas as instâncias. Na saturação, adie ou recuse novas tarefas explicitamente e explique o próximo passo. Isso é backpressure: comunicar a capacidade limitada a quem produz trabalho, em vez de aceitar uma promessa sem limite.

6. Conferir as promessas na operação

Meça falhas de requisição, tempo até um relatório utilizável, idade da tarefa pendente mais antiga e saturação de recursos. Separe espera na fila de tempo de processamento para que um leitor de arquivos rápido não esconda uma espera longa. O guia de monitoramento do Google organiza sinais por latência, tráfego, erros e saturação. Relacione eventos de requisição e tarefa sem registrar conteúdo dos comprovantes, tokens de acesso ou dados pessoais desnecessários. A OWASP descreve quais informações sensíveis excluir dos logs.

Exercite os limites antes de depender deles:

• Derrube o worker depois de salvar, reentregue a tarefa e confira o estado final.
• Interrompa a publicação na fila e confirme a recuperação do trabalho registrado.
• Envie um pico de arquivos grandes e examine espera, memória e comportamento das recusas.
• Solicite o relatório de outra organização e verifique que nenhum dado é retornado.

Se a extração usar inteligência artificial, avalie a qualidade dos campos separadamente. Entregar um resultado com confiabilidade não prova que o valor extraído esteja correto. O guia de avaliações de IA explica como definir e conferir esse tipo de comportamento esperado.

7. Adicionar complexidade por um motivo

Comece pelo menor desenho que atende aos requisitos. Uma aplicação modular e um worker podem bastar. Serviços separados permitem escalar e publicar de forma independente, mas introduzem falhas de rede, coordenação de versões e mais dificuldade para manter os dados consistentes. O guia de arquitetura da Microsoft descreve essas vantagens e custos dos microsserviços.

Perguntas frequentes

Fontes e próximas leituras

As pesquisas originais que fundamentam o artigo, para quem deseja explorar os detalhes.

1. Service Level Objectives Google SRE Book
2. Authorization Cheat Sheet OWASP
3. Asynchronous Request-Reply pattern Microsoft Azure Architecture Center
4. Transactional outbox pattern AWS Prescriptive Guidance
5. Making retries safe with idempotent APIs Amazon Builders’ Library
6. Timeouts, retries, and backoff with jitter Amazon Builders’ Library
7. Queue-Based Load Leveling pattern Microsoft Azure Architecture Center
8. Monitoring Distributed Systems Google SRE Book
9. Logging Cheat Sheet OWASP
10. Microservices architecture style Microsoft Azure Architecture Center