Altere um framework web com segurança de tipos e separe o código de banco de dados em três camadas

## Entre no ambiente de desenvolvimento fixado do repositório e encontre o pacote responsável Entre no ambiente de desenvolvimento por meio do gerenciador de ambiente declarado pelo repositório, em vez de depender de ferramentas instaladas globalmente. ### Configuração do ambiente - Comece pela raiz do repositório e ative o shell de desenvolvimento aprovado. - Quando disponível, use o caminho de execução em cache do ambiente para acelerar comandos repetidos. - Confirme que o compilador, o gerenciador de pacotes, as ferramentas de banco de dados e as ferramentas de documentação vêm do ambiente com versões fixadas. - Use a versão do ambiente de execução declarada pelo pacote relevante ou pela configuração da documentação. - Ative os registros de depuração apenas quando forem necessários para o diagnóstico local e não trate o modo de depuração como padrão de produção. ### Contexto de trabalho Em um repositório com vários pacotes, identifique o pacote responsável pela mudança antes de executar comandos. Localize seu diretório de origem, ponto de entrada de testes, artefatos gerados, módulos públicos e instruções locais, em vez de presumir que todos os pacotes compartilham o mesmo fluxo de trabalho. ## Verifique os tipos rapidamente primeiro e depois rode todos os testes Use o ciclo de feedback confiável mais rápido durante a iteração e depois execute a validação oficial mais ampla exigida para a entrega. ### Iteração focada - Prefira um compilador interativo, verificador de tipos ou carregador de módulos para obter feedback rápido sobre tipos quando a compilação do ambiente completo for dispendiosa. - Carregue apenas o módulo alterado ou o ponto de entrada do teste focado durante as primeiras iterações. - Ferramentas interativas que leem a entrada padrão devem receber comandos e um caminho de saída explícito; caso contrário, podem ficar esperando indefinidamente. - Quando uma sessão interativa permitir recarregamento, reutilize-a após as edições, em vez de recompilar repetidamente todo o ambiente. ### Registro de testes - Adicione novos testes ao agregador de testes oficial do pacote ou à configuração de descoberta. - Confirme que o teste focado realmente é executado por meio desse ponto de entrada. - Execute a validação completa do repositório quando a mudança estiver pronta ou quando o comportamento compartilhado, a configuração de compilação ou os limites dos pacotes forem afetados. - Não apresente uma verificação de compilação focada como prova de que o conjunto completo de testes foi aprovado. ### Servidor de desenvolvimento Inicie serviços locais somente a partir do ambiente aprovado e do diretório de trabalho correto. Quando o servidor de desenvolvimento depender de um aplicativo hospedeiro ou diretório pai, estabeleça esse contexto explicitamente antes de invocar seu ponto de entrada. ## Dê a cada pacote sua própria função e exponha só módulos públicos mínimos Mapeie as responsabilidades antes de alterar o código, especialmente em um repositório que reúna ambiente de execução, ferramentas de desenvolvimento, modelos, migrações, sincronização, interfaces de programação de aplicações, testes e integrações opcionais. ### Mapa de responsabilidades - Mantenha a inicialização do servidor e o middleware separados da configuração do framework. - Mantenha o roteamento e a geração de localizadores uniformes de recursos com segurança de tipos e isolados do processamento de requisições. - Separe modelos, validação, autenticação, trabalho em segundo plano, armazenamento, correio e atualizações em tempo real por responsabilidade. - Mantenha a geração de código, o projeto de esquemas e o comportamento do servidor de desenvolvimento fora do pacote principal do ambiente de execução quando a arquitetura os definir como ferramentas. - Trate integrações opcionais e componentes do lado do servidor como pacotes separados, em vez de deixar que suas dependências vazem para o núcleo. ### Interface pública Exponha a menor superfície estável de módulos necessária para os consumidores. Mantenha instruções brutas, composição interna, prelúdios auxiliares e módulos de implementação privados para que possam evoluir sem quebrar os chamadores. Adicione a documentação de API padrão do projeto aos módulos e às funções públicas. ### Convenções da linguagem Siga os padrões estabelecidos na base de código para valores puros, parâmetros contextuais, acesso a campos, modelos, roteamento em nível de tipos e tipos de modelo. Prefira a convenção já usada pelo projeto a uma forma equivalente que aumente a inconsistência. ## Não insira valores no texto da consulta e exponha só a camada de sessão Organize o acesso ao banco de dados em camadas de instruções, transações e sessões, com responsabilidade explícita pela codificação, atomicidade e conexões. ### Camada de instruções - Mantenha as consultas parametrizadas brutas junto com seus codificadores de entrada e decodificadores de resultado. - Use espaços reservados para todos os valores de tempo de execução, em vez de interpolar valores no texto da consulta. - Codifique explicitamente a possibilidade de valor nulo e os tipos do banco de dados. - Escolha um decodificador que corresponda à cardinalidade esperada: uma linha opcional, uma linha obrigatória ou várias linhas. - Mantenha as decisões sobre cache de instruções junto à definição da instrução. ### Camada de transações - Componha instruções em operações de negócio que exijam atomicidade. - Mantenha regras de ramificação, verificações de existência e decisões de criação dentro da transação quando elas precisarem observar um único estado consistente. - Torne explícitos os resultados idempotentes para que os chamadores possam distinguir um registro existente de um registro recém-criado. - Use composição independente ou seletiva apenas quando as operações forem realmente independentes e preservarem a semântica de transação pretendida. ### Camada de sessões - Apresente a camada de sessões como a interface pública do banco de dados. - Permita que as sessões sejam responsáveis pela execução de conexões e pelos limites das transações, enquanto ocultam instruções brutas e transações internas. - Use uma transação explícita para operações com várias instruções e a execução direta de instruções para uma única consulta independente. ## Ajuste o nível de isolamento e o tipo de resultado a cada operação de banco de dados Ajuste o isolamento, a cardinalidade e os tipos de resultado à semântica da operação, em vez de aplicar um único padrão em todos os lugares. ### Escolhas de isolamento - Use uma transação de escrita forte para operações críticas cuja correção dependa de serialização. - Use um nível adequado de isolamento de leitura para consultas em que a simultaneidade seja importante e um isolamento mais fraco seja aceitável. - Documente todas as operações cuja correção dependa de um modo de isolamento específico. ### Convenções dos resultados - Represente resultados de zero ou uma linha com um valor opcional. - Represente resultados de várias linhas com o tipo de sequência padrão do projeto. - Use tuplas para pequenos resultados internos com várias colunas quando invólucros nomeados não acrescentarem nenhum limite útil. - Retorne um indicador explícito de sucesso quando uma atualização ou exclusão puder não afetar nenhuma linha. - Para operações idempotentes, retorne tanto a informação de que o trabalho foi realizado quanto o valor resultante. ### Composição de codecs Quando uma biblioteca de codificadores compuser pares aninhados, adapte deliberadamente as tuplas de entrada planas e mantenha o mapeamento junto à instrução. Componha os decodificadores para preservar a ordem das colunas, a possibilidade de valor nulo e a cardinalidade das linhas. Adicione testes focados para incompatibilidades que possam mapear silenciosamente valores para o campo errado. ## Adicione dependências só onde são usadas e nunca faça force-push Mantenha as mudanças compatíveis, fáceis de revisar e recuperáveis. ### Código e dependências - Use as formas da linguagem preferidas pelo projeto quando elas melhorarem a clareza para as pessoas colaboradoras. - Documente as interfaces públicas com o sistema de documentação padrão do repositório. - Respeite as extensões de linguagem habilitadas na base de código e não introduza novas extensões sem uma necessidade concreta. - Adicione dependências apenas ao pacote que as utiliza. - Declare limites inferiores e superiores de compatibilidade adequados ao ecossistema compatível. - Trate dependências experimentais como um risco explícito e isole-as atrás de interfaces estreitas. ### Segurança no Git - Nunca faça force-push, inclusive force-with-lease. - Se a ramificação remota tiver avançado, busque as mudanças e faça rebase ou merge sobre o histórico atualizado, resolva os conflitos, valide e faça push normalmente. - Não esconda um push rejeitado reescrevendo o histórico compartilhado. - Mantenha arquivos gerados não relacionados, alterações no arquivo de bloqueio e configurações locais de desempenho fora do commit. ## Deixe as substituições locais fora dos commits e publique a documentação pelo processo de lançamento Use substituições locais de desempenho e dependências durante o desenvolvimento sem permitir que elas vazem para o controle de código-fonte compartilhado. ### Substituições locais de desempenho - Sinalizadores temporários de compilação rápida podem ser ativados para iterações locais quando o projeto oferecer suporte a eles. - Não faça commit de uma mudança de desempenho exclusiva do ambiente local. - Antes da entrega, examine a diferença real em vez de depender apenas de sinalizadores de índice que podem ocultar modificações. ### Desenvolvimento de dependências locais Ao desenvolver um framework e um aplicativo que o utiliza ao mesmo tempo: 1. Coloque o checkout local do framework em um local de desenvolvimento escolhido deliberadamente. 2. Direcione a dependência do aplicativo para esse caminho local por meio do mecanismo de substituição compatível. 3. Ative o ambiente necessário e atualize o estado das dependências. 4. Teste o aplicativo com o framework local. 5. Remova ou documente intencionalmente a substituição antes de preparar mudanças compartilhadas. ### Documentação e lançamento - Visualize a documentação localmente a partir do ambiente designado para ela. - Quando a documentação publicada for mantida separadamente, atualize a dependência do framework ou da documentação por meio do fluxo de trabalho aprovado do repositório. - Faça commit apenas das alterações no arquivo de bloqueio ou no código-fonte exigidas por essa atualização. - Implante a documentação ou a infraestrutura apenas pelo processo de lançamento designado, preservando a ordem necessária entre a atualização de dependências, o estado registrado em commit e a implantação. - Quando o lançamento de um framework exigir a sincronização da documentação downstream, inclua essa etapa na lista de verificação do lançamento, em vez de depender da memória.