Criar serviços Rust assíncronos que resistam a cancelamentos e falhas

## Concluir o código real em vez de usar simulações ou stubs Implemente o comportamento solicitado por completo, do início ao fim. Não substitua a lógica de produção ausente por objetos simulados, implementações alternativas, esboços ou atalhos exclusivos para testes. - Use dependências reais e o caminho efetivo de integração. - Não manipule testes para ocultar uma implementação defeituosa. - Evite contornos no ambiente que ignorem a configuração necessária. - Registre explicitamente qualquer trabalho incompleto inevitável no plano ou na especificação resultante. - Nunca afirme que um recurso funciona sem evidências obtidas pelo caminho que os usuários percorrerão. Execução autônoma significa concluir o caminho rigoroso, não reduzir a definição de pronto. ## Aplicar as mesmas decisões de design a todos os tipos de dados relacionados Quando um sistema processa várias famílias relacionadas de sinais ou dados, projete um comportamento compartilhado para todas elas, mesmo que uma família seja a prioridade atual. - Identifique a semântica comum à ingestão, ao armazenamento, à pesquisa, à análise e ao gerenciamento do ciclo de vida. - Mantenha as otimizações específicas de cada família atrás de limites explícitos. - Teste se as decisões compartilhadas não privilegiam acidentalmente a primeira família implementada. - Preserve um comportamento consistente de erros, configuração e observabilidade em todos os caminhos. - Documente as diferenças intencionais em vez de permitir que as implementações se distanciem. A priorização pode controlar a ordem de entrega, mas não deve restringir silenciosamente a arquitetura. ## Colocar a segurança em primeiro lugar, depois a velocidade e, por último, a conveniência Use esta ordem de prioridade na engenharia: segurança em primeiro lugar, desempenho em segundo e conveniência para quem desenvolve em terceiro. Otimize somente depois de compreender as invariantes e o comportamento das falhas. - Rejeite entradas inválidas nos limites públicos. - Defina limites explícitos como constantes nomeadas e retorne erros estruturados quando eles forem excedidos. - Não mascare falhas de dependências, armazenamento ou rede com uma alternativa aparentemente bem-sucedida. - Trate um estado inesperado como erro ou invariante violada, não como uma operação sem efeito aparentemente bem-sucedida. - Permita a ausência de dados opcionais somente quando o contrato os definir explicitamente como opcionais. O trabalho de desempenho deve preservar a correção durante falhas, novas tentativas, cancelamento e progresso parcial. ## Usar asserções de depuração para regras internas e erros para entradas inválidas Use asserções ativas somente durante a depuração para documentar invariantes internas que os revisores possam analisar. Use resultados de erro recuperáveis para entradas inválidas do usuário, dados externos e condições de execução, pois as asserções de depuração podem desaparecer em compilações otimizadas. - Propague erros de bibliotecas com `Result` e o operador `?`. - Evite métodos de extração incondicional em código reutilizável de bibliotecas. - Preserve tipos de erro significativos em vez de nivelar todas as falhas. - Use operações falíveis de sistema de arquivos e metadados quando os erros transmitirem informações. - Acrescente contexto sem descartar a causa original. - Nunca ignore silenciosamente um erro por meio de uma atribuição não utilizada. Um estado impossível deve falhar de modo visível o bastante para permitir o diagnóstico. ## Manter o código assíncrono seguro quando tarefas são canceladas Presuma que o trabalho assíncrono possa ser cancelado em qualquer ponto de suspensão. Estruture as transições de estado para que o cancelamento não exponha um estado parcialmente atualizado nem provoque perda de dados. - Prefira a posse segundo o modelo de atores e a troca de mensagens para estados mutáveis sensíveis ao cancelamento. - Não mantenha um bloqueio durante um ponto de espera assíncrona. - Use seções críticas síncronas quando a alteração precisar ser atômica. - Cancele de forma cooperativa por meio de um sinal de cancelamento, em vez de interromper tarefas arbitrariamente. - Em laços de seleção, fixe e retome um futuro em andamento, em vez de recriá-lo e descartá-lo. - Torne o encerramento e a limpeza idempotentes. Escolha uma clonagem mais simples ou posse compartilhada em código assíncrono e baseado em atores quando isso tornar mais seguros o comportamento da posse e do cancelamento. ## Manter claros os tipos e a posse, e dividir arquivos grandes Use identificadores de domínio e nomes alternativos de tipos já estabelecidos, em vez de passar sequências de caracteres brutas para novos conceitos. Permita que o sistema de tipos diferencie valores que não devem ser misturados. - Evite ocultar nomes dentro de uma função quando isso tornar as transições de estado menos claras. - Retorne referências quando a posse permanecer local e a clonagem for desnecessária. - Use posse compartilhada explícita quando os valores atravessarem os limites das tarefas. - Prefira laços procedurais quando cadeias de iteradores tornarem difícil ler um fluxo de controle falível. - Divida arquivos e funções grandes demais segundo responsabilidades coerentes. - Mantenha as interfaces públicas separadas dos detalhes de implementação. A legibilidade é uma ferramenta de confiabilidade quando o código coordena estados assíncronos. ## Testar pela interface real do serviço que os usuários acessam Não declare um recurso concluído até que ele seja exercitado pela pilha pública real. Se os usuários acessarem um comportamento por um protocolo de rede, um intermediário ou um limite de serviço, teste por esse limite em vez de chamar diretamente uma função interna. 1. Inicie o serviço real com uma configuração representativa. 2. Envie a entrada pela interface compatível de ingestão ou comando. 3. Recupere o resultado pela interface compatível de consulta ou resposta. 4. Verifique a persistência, o mapeamento de erros e os efeitos colaterais observáveis. 5. Confirme que os comportamentos interno e público estão de acordo. Os testes internos são úteis, mas não substituem a comprovação pelo caminho de produção. ## Escolher o tipo de teste conforme o objetivo, incluindo testes de falha Use testes unitários rápidos para lógica isolada, testes baseados em propriedades para espaços de estado amplos, testes com injeção de falhas para resiliência e testes de integração para o comportamento completo do serviço. - Restrinja suficientemente as entradas dos testes baseados em propriedades para produzir contraexemplos úteis. - Use preparações de teste com serviços reais quando o comportamento do armazenamento ou do protocolo for relevante. - Limite as novas tentativas às baterias de testes que tolerem intencionalmente o escalonamento não determinístico. - Execute a cobertura dos pontos de falha quando as alterações afetarem a recuperação ou as transições de estado. - Acrescente um teste de integração para cada novo ponto de acesso público. - Teste o caminho de erro tão deliberadamente quanto o caminho de sucesso. Não permita que tentativas repetidas transformem um defeito determinístico em uma aprovação aparente. ## Rodar as verificações com a cadeia de ferramentas fixada e os comandos do repositório Execute compilação, formatação, análises estáticas, testes, verificações da documentação, verificações de licença, auditorias de dependências e verificações ortográficas pelos comandos definidos no repositório. - Use a cadeia de ferramentas fixada e o canal exigido do formatador. - Inicie os serviços locais declarados antes das baterias de integração e encerre-os depois. - Forneça a configuração dos testes por variáveis de ambiente documentadas, sem incorporar credenciais reais. - Execute primeiro o pacote específico afetado e depois a bateria de testes de todo o espaço de trabalho com todos os recursos. - Trate cada aviso da análise estática como trabalho a resolver ou justifique-o com a menor permissão específica possível. - Verifique se cada alteração é compilada de forma independente, não apenas como parte de uma alteração posterior empilhada. Comandos diretos são aceitáveis somente quando preservam a configuração realizada pelo fluxo de trabalho canônico. ## Registrar mudanças de arquitetura em três tipos de registro Acompanhe as mudanças arquitetônicas por meio de três registros complementares: - **características:** requisitos proativos que a arquitetura deve satisfazer; - **lacunas:** limitações descobertas por incidentes, testes ou comportamento em produção; - **desvios:** afastamentos intencionais da arquitetura preferida, incluindo justificativa e restrições. Vincule as alterações de código ao registro pertinente quando elas modificarem as garantias do sistema. Mantenha distintos os modelos formais, os fluxos de simulação, os registros de decisão e o estado da implementação, para que um projeto almejado não seja confundido com um comportamento concluído. Atualize o registro quando as evidências alterarem a arquitetura, não somente quando um novo recurso for anunciado. ## Responder aos comentários de revisão no próprio tópico Facilite a revisão das alterações mantendo as diferenças concentradas e as explicações anexadas à decisão a que se referem. - Responda a um comentário de revisão no tópico existente, em vez de criar outro comentário no mesmo local. - Verifique pela interface da plataforma de hospedagem se a resposta está vinculada ao comentário principal pretendido. - Explique por que uma invariante, permissão, clonagem ou desvio não evidente é necessário. - Separe a refatoração não relacionada das alterações funcionais. - Atualize as orientações mantidas continuamente quando um padrão recorrente de falha revelar uma regra duradoura. A disciplina nas revisões preserva o contexto e impede que o mesmo problema seja resolvido em conversas paralelas. ## Passar em todas as verificações do diff final antes de dizer que terminou Antes de informar a conclusão, inspecione as diferenças finais e confirme: - todas as análises estáticas aplicáveis são aprovadas sem avisos sem explicação; - as verificações de formatação são aprovadas para todos os arquivos-fonte e arquivos de teste alterados; - não resta nenhuma extração incondicional, supressão silenciosa de erros nem clonagem injustificada; - os testes pela interface de produção e os testes de integração afetados são aprovados; - os cabeçalhos, as convenções de registro, a documentação e as auditorias de dependências exigidos são aprovados; - os novos arquivos e funções permanecem concentrados e fáceis de manter; - não há credenciais nem valores confidenciais. Corrija as falhas na causa. Não desative verificações, enfraqueça testes nem contorne o caminho de produção para obter um resultado aprovado.