Criar um emulador local de nuvem que funcione com os SDKs e CLIs oficiais

## Igualar os formatos de requisição e resposta da nuvem real antes de buscar atalhos Priorize: 1. a compatibilidade com o protocolo de nuvem da plataforma de origem; 2. o comportamento esperado pelos clientes oficiais de SDK e CLI; 3. a reutilização dos padrões existentes do emulador; 4. a correção em vez da conveniência; 5. mudanças restritas e testáveis. Não adicione formatos personalizados de endpoint nem simplifique os formatos de solicitação e resposta para facilitar a implementação. Não faça uma refatoração ampla, a menos que o comportamento solicitado exija isso. Antes de editar, identifique o serviço, sua função no plano de controle ou no plano de dados, a família de protocolos, a implementação existente a ser tomada como modelo, o impacto na configuração, no armazenamento e na documentação, além do menor plano de testes que seja útil. Quando o comportamento não estiver claro, prefira primeiro o contrato da plataforma de origem, depois o comportamento consolidado do emulador e, por fim, as expectativas da suíte de compatibilidade. Se a tarefa exigir uma mudança de arquitetura entre serviços, apresente as contrapartidas em vez de refatorar sem critério. ## Manter os handlers de protocolo enxutos e a lógica de negócio nos serviços Use um projeto de serviço em camadas: - controladores ou manipuladores analisam a entrada do protocolo e produzem respostas compatíveis com ele; - serviços contêm a lógica de negócios e lançam a exceção compartilhada do domínio de nuvem; - modelos representam os dados do domínio; - registros, configurações, fábricas de armazenamento, serviços de ciclo de vida, analisadores, construtores e mapeadores de exceção fornecem a infraestrutura compartilhada. Mantenha os controladores enxutos. Reutilize utilitários compartilhados e reproduza a estrutura do serviço consolidado mais próximo antes de introduzir um novo padrão. Encaminhe falhas do domínio pelo tipo de exceção compartilhado. Os fluxos de consulta e XML devem usar o mapeador de exceção padrão; os fluxos de protocolo JSON devem retornar o corpo de erro estruturado exigido. Os tipos de retorno dos controladores devem continuar compatíveis com as restrições de reflexão da compilação antecipada e de serialização. Use injeção por construtor, chaves em instruções condicionais e código autoexplicativo. Nunca deixe um bloco `catch` vazio; se uma exceção for tolerada intencionalmente, registre contexto suficiente para diagnosticá-la. ## Confirmar o protocolo real de cada serviço antes de adicionar uma operação Determine o protocolo de comunicação real antes de adicionar uma operação: - protocolos de consulta usam ações codificadas como formulário e respostas XML; - protocolos no estilo JSON RPC usam um cabeçalho de destino e JSON estruturado; - REST JSON e REST XML usam caminhos de recursos com seus formatos de corpo nativos; - serviços do plano de dados podem exigir proxies TCP nativos em vez de APIs de gerenciamento HTTP. Use o construtor e o analisador XML compartilhados, além das constantes de namespace. Nunca analise XML com expressões regulares. Mantenha os erros JSON alinhados à estrutura de erros do protocolo de destino. Alguns serviços expõem mais de um caminho de compatibilidade. Mantenha os manipuladores alternativos alinhados e teste-os em conjunto. Trate os endpoints de descoberta de identidade de acordo com seu protocolo aberto real, em vez de forçá-los a seguir o modelo da API de gerenciamento. Valide as APIs de gerenciamento por meio de clientes SDK oficiais, não apenas com solicitações HTTP elaboradas manualmente. A aceitação de uma carga útil manual não comprova a compatibilidade da serialização do cliente, dos cabeçalhos, dos erros, da paginação nem da geração de URL. ## Atualizar sempre juntos os modos de armazenamento e os arquivos de configuração Ofereça suporte ao armazenamento por meio da fábrica compartilhada e dos modos declarados; nunca instancie uma implementação de armazenamento diretamente dentro de um serviço. Respeite os hooks de ciclo de vida para carregamento, flush, pontos de verificação ou comportamento de gravação antecipada. Quando os valores padrão da interface e os valores implantados forem diferentes, trate o arquivo de configuração de execução do repositório como a fonte de verdade efetiva. Para comportamentos relacionados ao armazenamento: 1. atualize a interface de configuração canônica; 2. atualize a configuração principal de execução; 3. atualize a configuração de testes; 4. conecte o modo por meio da fábrica de armazenamento; 5. verifique a integração com o ciclo de vida. Para qualquer configuração voltada ao usuário, atualize também a documentação e siga a convenção estabelecida para nomes de variáveis de ambiente. Analise a URL base, o nome do host, os valores padrão de região e conta, os intervalos de portas, as raízes de persistência e a rede de contêineres quando afetarem os identificadores ou endpoints gerados. Adicione novos campos de modo compatível e mantenha sincronizados a configuração compartilhada, o armazenamento e o registro de serviços. ## Testar a compatibilidade com os SDKs oficiais, não com requisições manuais Use testes unitários para o comportamento isolado do serviço e testes de integração para o processamento de protocolos, a persistência e o estado visível para o cliente. A execução ordenada de testes de integração só é aceitável quando o comportamento é intencionalmente dotado de estado. Qualquer mudança na análise, no formato da resposta, nos erros, na semântica da persistência, na geração de URL, na habilitação do serviço ou nos caminhos alternativos de protocolo exige cobertura automatizada. Durante a iteração, execute primeiro um teste específico e depois a suíte diretamente relevante. Use o projeto de compatibilidade quando uma mudança puder afetar o comportamento real do SDK. Prefira as asserções baseadas em SDK a solicitações HTTP brutas e documente qualquer desvio intencional em relação à plataforma de origem. Quando caminhos alternativos de protocolo expuserem a mesma operação, teste se a semântica é equivalente. Quando o estado persistir, verifique o comportamento de carregamento e flush nos modos de armazenamento relevantes. Não alegue compatibilidade com base apenas em solicitações manuais. Se o comportamento mudar sem cobertura automatizada, explique qual teste está faltando e por que não foi possível adicioná-lo. ## Concluir cada serviço novo por completo sem mudar de passagem o fluxo de lançamento Ao adicionar um serviço, crie o controlador, o serviço e os modelos correspondentes; registre-o; adicione a configuração canônica e a configuração de testes; conecte o armazenamento por meio da fábrica; adicione testes; e atualize a documentação. Antes de concluir: - execute os testes relevantes e as verificações de compatibilidade de protocolo; - confirme que nenhum endpoint personalizado nem formato de comunicação criado por conveniência tenha sido introduzido; - verifique as atualizações de configuração, armazenamento, ciclo de vida e documentação; - confira a consistência das URLs e dos identificadores de recursos gerados; - mantenha os registros estruturados e silenciosos nos caminhos críticos. Mantenha as solicitações de incorporação focadas, preserve o comportamento existente, a menos que a mudança seja explícita, e separe refatorações não relacionadas. Use tipos convencionais de commit e atribuição exclusivamente humana. Trate ramificações de lançamento, tags e fluxos de publicação como infraestrutura crítica. Uma mesclagem na ramificação de desenvolvimento não comprova, por si só, que um lançamento seja estável. Não altere incidentalmente o comportamento de lançamento ao implementar a funcionalidade do serviço.