Como extrair um serviço de um monólito com segurança

O primeiro serviço extraído deve provar que o monólito pode entregar uma responsabilidade sem perder o controle. Escolha-o pela propriedade dos dados e pelo risco de implantação, não pela facilidade de desenhar uma caixa bonita ao redor de um módulo. Um pacote organizado que compartilha tabelas, recebe chamadas síncronas e participa de uma transação grande continua sendo parte do monólito em todos os aspectos importantes.

Já vi equipes extraírem o código que parecia mais isolado, comemorarem um repositório limpo e depois descobrirem que cada versão exigia uma mudança coordenada no banco e uma chamada de madrugada com três responsáveis. O serviço existia como processo, mas não como unidade operacional. A primeira falha real em produção o mandou direto de volta para o monólito.

Uma boa primeira extração tem uma superfície de escrita estreita, dados que podem ganhar um proprietário claro, consumidores que toleram uma fronteira de rede e um caminho de implantação reversível sem consertar dados à mão. Ela pode parecer sem graça no diagrama de arquitetura. Isso ajuda quando a equipe ainda está aprendendo como o sistema realmente se comporta.

Comece pela propriedade dos dados, não por um substantivo de negócio

O melhor primeiro serviço possui um conjunto coerente de fatos e pode rejeitar escritas sem consultar metade do monólito. Esse critério é mais rigoroso do que ter classes chamadas Billing, Customer ou Inventory. Um substantivo de negócio costuma abranger fluxos, relatórios, permissões e tabelas históricas que diferentes caminhos de código alteram por motivos distintos.

Pergunte qual componente pode se tornar a única autoridade sobre um pequeno conjunto de registros. Ser proprietário significa validar mudanças, confirmá-las, atribuir identificadores e publicar o resultado. Outros componentes podem guardar esses fatos em cache ou copiá-los, mas deixam de editar as linhas autoritativas. Se o monólito e o novo serviço continuam sendo escritores legítimos, você criou uma corrida distribuída, não uma fronteira.

Rastreie escritas antes de leituras. Leituras costumam ser mais fáceis de duplicar, colocar em cache ou servir por uma visão de compatibilidade. Escritas revelam as regras que mantêm os dados válidos. Procure no código da aplicação, em procedimentos armazenados, tarefas agendadas, gatilhos do banco, scripts de importação, ferramentas de suporte e comandos diretos de operadores. Sistemas antigos frequentemente escondem escritas decisivas em lugares que o repositório principal não mostra.

Um candidato útil pode possuir pedidos de geração de documentos, preferências de notificação, registros de taxas de câmbio ou trabalhos de exportação concluídos. Esses exemplos têm uma transição de estado limitada e muitas vezes aceitam trabalho assíncrono. Um candidato ruim geralmente se chama cliente, pedido, conta ou direito quando esses registros participam de toda transação importante. Esses domínios podem virar serviços depois, mas escolhê-los primeiro força a migração a ensinar a lição mais difícil pelo maior preço.

Não confunda um grupo de tabelas com um domínio. Se uma tabela recebe doze chaves estrangeiras, tem dois gatilhos que atualizam outros agregados e passa por uma correção noturna, movê-la não cria independência. Apenas desloca o centro de uma rede de dependências. A documentação do PostgreSQL descreve chaves estrangeiras como dependências entre linhas que referenciam e linhas referenciadas. Essa garantia é local à transação do banco. Quando as tabelas ficam atrás de serviços separados, a aplicação precisa substituí-la de propósito ou aceitar uma consistência mais fraca.

Meça o acoplamento com evidências de execução

Grafos estáticos de dependência são um começo, mas as evidências de produção mostram se um candidato suporta uma fronteira entre processos. Instrumente o monólito por tempo suficiente para observar consumidores, formatos de consulta, frequência de escrita, duração de transações, tamanho de cargas, sensibilidade à latência, comportamento de repetição e picos de tráfego. A unidade importante não é um arquivo fonte. É uma solicitação ou tarefa que cruza a fronteira proposta.

Monte um registro com uma linha para cada serviço candidato. Anote as tabelas lidas e escritas, cada consumidor, se a chamada ocorre dentro de uma solicitação do usuário, se uma falha pode esperar e quais invariantes dependem hoje de uma única transação de banco. Acrescente o responsável pela implantação e a ação de reversão. Se uma dessas células disser “a definir”, o candidato não está pronto.

A busca no repositório não encontra SQL dinâmico, reflexão, consultas geradas ou código implantado fora dele. Logs de comandos e rastros do banco capturam esses caminhos. Observe por tempo suficiente para incluir trabalhos agendados como liquidação, faturamento, conciliação, arquivamento e fechamento do mês. O endpoint calmo de terça-feira pode ser o centro do sistema no último dia útil do mês.

Conte operações que cruzam a fronteira, não chamadas de métodos. Um método de repositório falante pode executar vinte consultas e ainda assim se mover de modo limpo com seus dados. Um getter aparentemente inocente pode participar de uma transação que bloqueia linhas em quatro domínios. A documentação do PostgreSQL sobre bloqueio explícito explica que SELECT FOR UPDATE bloqueia atualizações e pedidos de bloqueio conflitantes até o fim da transação. Trocar essa espera local por uma chamada remota muda tempos, tipos de falha e impasses, mesmo quando os campos retornados continuam iguais.

Trate tráfego desconhecido como risco, não como zero. Quando os logs não identificam quem atualiza uma tabela, acrescente observação antes da extração. Um proxy, um gatilho temporário de auditoria ou uma etiqueta de rastreamento na camada de dados pode revelar o escritor. Adivinhar só é mais rápido até o escritor desconhecido sobrescrever o estado do serviço novo.

As evidências devem responder a quatro perguntas desconfortáveis: o serviço pode ficar indisponível sem bloquear a transação principal? Um consumidor pode repetir sem duplicar trabalho? Um operador consegue explicar qual cópia de um registro é autoritativa? A equipe pode desativar a rota mantendo os dois armazenamentos internamente coerentes? O primeiro serviço não precisa de uma resposta perfeita para as quatro, mas cada resposta fraca exige um controle testado.

Um diagrama limpo pode esconder um primeiro corte péssimo

Descarte candidatos cujo apelo dependa principalmente da organização. Equipes costumam escolher um módulo porque uma equipe já cuida dele, porque seu namespace é organizado ou porque um diagrama de fornecedor o chama de contexto delimitado. Nenhum desses fatos prova que o código possa ser implantado sozinho.

Autenticação é uma armadilha comum. Parece horizontal e independente, mas toda solicitação depende de sua latência e disponibilidade. Seus dados também podem misturar credenciais, sessões, funções, associação a tenants, histórico de auditoria e fluxos de recuperação. A extração da autenticação pode fazer sentido, mas é um ensaio ruim quando um erro de roteamento bloqueia a empresa inteira.

Dados de referência compartilhados criam outra armadilha. Um módulo de códigos de países ou categorias de produtos parece somente leitura até que administradores o editem, caches se atualizem em momentos diferentes e regras de negócio esperem uma mudança dentro da mesma transação. O volume é baixo, mas a propagação é enorme. Pouco tráfego não significa baixo risco de implantação.

O código de relatórios parece mais seguro porque os relatórios raramente escrevem registros centrais. O custo escondido está na propriedade das consultas. Um relatório que une trinta tabelas do monólito não ganha independência quando um endpoint HTTP envolve o mesmo SQL. Ele vira um serviço remoto de consulta preso a cada esquema que lê. Extrair uma projeção de relatórios pode funcionar depois de definir sua fonte e aceitar atraso. Extrair as junções atuais apenas adiciona um salto de rede.

Eu discordo da recomendação “extraia primeiro o módulo mais fácil”. Ela é popular porque uma separação rápida do repositório cria progresso visível e oferece uma nova esteira de implantação. Está errada quando facilidade significa apenas mover código. Escolha a responsabilidade mais fácil de operar de modo independente, incluindo dados, falhas, implantação, observação e reversão. Essa definição produz menos encenação e mais aprendizado.

O risco de implantação importa mais do que o tamanho

Um serviço pequeno pode ter um enorme raio de impacto, enquanto um worker assíncrono maior pode falhar em silêncio e recuperar sua fila depois. Classifique a primeira extração pelo que acontece durante uma versão ruim. Volume de código é uma aproximação fraca. A porcentagem de solicitações críticas que cruza a fronteira revela muito mais.

Prefira um candidato fora do caminho síncrono de login, checkout, autorização ou atualização principal do registro. Envio de notificações, conversão de arquivos, geração de exportações e indexação de documentos costumam ser limites melhores porque o monólito pode enfileirar o trabalho e continuar. Isso não os torna descartáveis. Dá tempo para a equipe observar, repetir e reparar sem transformar cada falha do serviço em uma indisponibilidade geral.

Verifique também o acoplamento de recursos. Um processo novo pode sobrecarregar o mesmo banco com outro pool de conexões, repetir uma consulta lenta de forma mais agressiva ou esgotar uma fila compartilhada. A separação no diagrama de implantação não separa CPU, bloqueios, conexões nem cotas de sistemas seguintes. Coloque limites explícitos em concorrência e repetições antes de deslocar tráfego de produção.

Avalie cada candidato por consequências que os operadores reconhecem:

• Uma parada de dez minutos tem menos risco quando o trabalho espera e depois alcança; falhar solicitações centrais é um alerta.
• Um componente deve escrever os dados autoritativos; várias aplicações e tarefas são um alerta.
• Uma chave de idempotência estável torna repetições mais seguras; repetir a solicitação às cegas é um alerta.
• Uma troca de rota ou consumidor deve reverter a versão; fundir dados e reverter esquema é um alerta.
• Saídas comparadas e métricas de domínio devem encontrar falhas semânticas; apenas a saúde do processo é um alerta.

Não transforme a tabela em uma fórmula numérica falsa. Uma pontuação de 17 não cancela uma resposta que diga “não conseguimos reconstruir as escritas ausentes”. Use-a para expor condições de veto e forçar uma conversa explícita. Na primeira extração, divergência irreversível de dados é um veto. Uma dependência que exige implantar todos os consumidores na mesma janela também é.

Defina o contrato antes de mover a implementação

O contrato de extração precisa descrever o comportamento diante de repetições, entradas antigas, duplicatas, timeouts e falhas parciais. Uma lista de endpoints e campos não basta. Os consumidores precisam saber qual identidade de solicitação permanece estável, qual transição é permitida e que resposta significa que o serviço aceitou a responsabilidade de forma durável.

Escreva o contrato segundo o comportamento existente, inclusive as partes de que ninguém gosta. Se o monólito aceita envios duplicados e devolve o trabalho original, o serviço novo não pode passar a responder com conflitos apenas porque isso parece mais limpo. Modernize depois que a paridade estiver visível ou por trás de uma mudança explicitamente versionada. Caso contrário, toda diferença vira uma discussão sobre qual resultado era o pretendido.

Para um candidato de exportação, uma solicitação mínima torna concreto o comportamento de repetição:

{
  "request_id": "01JEXAMPLE8M4Q2",
  "account_id": "A1842",
  "report_type": "ledger",
  "cutoff": "2026-08-01T00:00:00Z"
}

O serviço guarda request_id sob uma restrição única antes de começar o trabalho. Repetir a solicitação devolve o trabalho existente e seu estado atual. Um timeout após a aceitação passa a ser recuperável: o consumidor repete a mesma identidade em vez de inventar outro trabalho. O contrato também precisa de um estado final de falha e de uma regra sobre a possibilidade de um operador repeti-lo com a mesma identidade.

Especifique erros pela ação do consumidor. “Data de corte inválida, não repita” é útil. “Dependência indisponível, repita com espera limitada” é útil. Um erro interno genérico empurra todos os consumidores para a resposta mais perigosa, a repetição cega imediata. Limite tamanhos e prazos de solicitação no contrato, ou a maior entrada histórica descobrirá esses limites em produção.

Mantenha a primeira interface menor que a antiga API interna. Não exponha tabelas por endpoints genéricos de criar, ler, atualizar e excluir. Ofereça operações que preservam invariantes, como request_export, cancel_pending_export e get_export_status. Uma superfície estreita de comandos permite mudar detalhes da implementação sem coordenar todos os consumidores outra vez.

Um escritor evita dados com duas autoridades

A migração precisa declarar o momento em que o novo serviço se torna o único escritor de seus registros. Fazer escrita dupla no código da aplicação não é uma ponte segura. Uma escrita pode funcionar enquanto a outra expira, e o consumidor não sabe se repetir vai reparar ou duplicar o estado.

Transfira a propriedade em etapas. Primeiro, torne escritores escondidos visíveis e leve-os por uma única interface do monólito. Depois, introduza identidades estáveis e registre o comportamento antigo. Deixe o novo serviço processar tráfego copiado sem publicar resultados. Quando as verificações de paridade passarem, encaminhe escritas autoritativas ao serviço enquanto o monólito lê por um caminho de compatibilidade. Remova o escritor antigo somente depois de fechar a janela de retorno. Isso é uma sequência integrada, não cinco projetos independentes.

Se o monólito precisa reagir a uma mudança confirmada pelo serviço, publique um evento na mesma transação que registra a mudança. Uma caixa de saída transacional é o mecanismo comum: o serviço confirma o estado do domínio e uma linha da caixa juntos, depois um relay publica a linha. Os consumidores ainda precisam tratar duplicatas, pois o relay pode publicar e falhar antes de marcar a linha como concluída.

Evite chaves estrangeiras entre serviços. Elas não impõem integridade entre bancos separados, e manter um banco compartilhado conserva o acoplamento de implantação. Transporte o identificador referenciado, valide-o onde o fluxo exigir e decida como tratar exclusões ou cópias antigas. Algumas invariantes precisam de uma consulta síncrona à autoridade; outras toleram uma projeção local. A decisão pertence ao contrato de domínio, não a uma junção acidental.

A carga inicial de dados precisa de uma marca d'água e uma consulta de conciliação. “Copie a tabela e depois troque” deixa uma corrida entre o instantâneo e as escritas ao vivo. Capture mudanças depois de uma posição conhecida, carregue o instantâneo, aplique as mudanças na ordem e compare contagens com totais de domínio ou hashes. Uma contagem igual não encontra valores trocados, relações ausentes nem um padrão cujo significado mudou.

O plano de corte deve nomear a autoridade antiga e a nova em cada fase. Se a pessoa que comanda o incidente precisa deduzir a propriedade pelos painéis enquanto as escritas continuam, o plano já falhou antes do incidente começar.

O tráfego sombra deve comparar significado

Uma implantação sombra prova mais quando compara resultados de domínio, não apenas códigos de status. Envie uma cópia de solicitações de produção elegíveis ao novo serviço, isole seus efeitos e registre saídas normalizadas das duas implementações. Depois, classifique as diferenças por campo e regra de negócio.

Normalize valores não determinísticos antes da comparação. Timestamps, identificadores gerados, coleções sem ordem e formatação podem diferir sem mudar o comportamento. Não normalize campos que carregam significado, como arredondamento monetário, decisões de permissão, ordem prometida ao consumidor ou momento de uma transição. Cada regra de normalização deve ter responsável e motivo.

Tráfego de produção gravado encontra combinações que dados de teste não contêm, mas também carrega dados sensíveis e acidentes históricos. Defina retenção, acesso, mascaramento e controles de reprodução antes da coleta. Em ambientes regulados, manter o mecanismo dentro do perímetro do cliente pode importar mais que a conveniência de um sistema de teste hospedado. Dar suporte a esse ambiente não concede certificação de conformidade. São afirmações separadas.

Compare efeitos por meio de um receptor, em vez de permitir que o serviço sombra envie e-mails reais, cobre uma conta ou publique eventos autoritativos. Substitua esses adaptadores por registradores de intenção. A comparação útil é “a nova implementação teria emitido este evento com estes campos”, não “o manipulador devolveu 202”.

Defina os portões de promoção sobre o comportamento observado. Cubra volume normal, maiores cargas, repetições, entradas inválidas, timeouts de dependências e trabalhos agendados encontrados na análise. Exija zero diferenças sem explicação em invariantes que afetam dinheiro, permissões ou estado durável. Para formatação cosmética, documente diferenças aceitas em vez de fingir que igualdade byte a byte é o objetivo.

CodeHero usa um mecanismo de paridade contra tráfego de produção gravado ao reescrever um sistema antigo, e eu exigiria essa parte mesmo que outra equipe construísse o substituto. A saúde do processo mostra que o código novo funciona. As evidências de paridade mostram se ele ainda faz o trabalho.

A reversão deve mudar o roteamento, não consertar o histórico

Uma reversão segura impede novo tráfego de chegar ao serviço extraído sem pedir aos operadores que unam dois históricos conflitantes. Essa propriedade precisa ser projetada antes do corte. Se reverter exige transformar dados de volta, restaurar uma tabela compartilhada ou reimplantar todos os consumidores, será lento demais quando a falha for ambígua.

Mantenha o caminho antigo de leitura durante a janela de observação, mas não dois escritores sem restrições. Quando o serviço novo possui as escritas, devolva suas mudanças confirmadas ao armazenamento de compatibilidade do monólito ou faça o monólito ler pelo serviço. A primeira opção permite um retorno rápido de leitura quando o atraso de réplica é visível. A segunda mantém uma verdade, mas torna a disponibilidade do serviço parte do caminho antigo. Escolha conforme a interrupção que consegue suportar.

Use um controle de rota que mude sem uma implantação da aplicação. Ele pode ficar no gateway, em uma atribuição de consumidor ou atrás de uma configuração do servidor. Proteja-o com controle de acesso e registro de auditoria. Teste a reversão exata sob carga antes do corte, incluindo solicitações em andamento e mensagens na fila.

Defina gatilhos de reversão em termos observáveis. Aumento da taxa de erro não encontra corrupção semântica. Inclua diferenças de paridade, idade da fila, taxa de duplicatas, transições rejeitadas e totais de domínio. Atribua quem pode ordenar a reversão e quem investiga depois da mudança de tráfego. Uma reunião de emergência não é um plano de controle.

Mudanças de esquema devem continuar compatíveis durante a janela de reversão. Adicione campos antes de exigi-los, aceite representações antigas e novas enquanto as duas versões rodam e remova os campos antigos depois. Scripts de reversão de banco acalmam no papel, mas desfazer uma migração destrutiva depois que novas escritas chegaram costuma ser impossível. Mudanças compatíveis para a frente preservam a opção de roteamento.

Não chame todo recuo de fracasso. Se a troca de rota funciona, as evidências ficam intactas e a equipe encontra uma diferença semântica antes que os clientes dependam dela, o mecanismo de extração cumpriu seu papel. O fracasso é descobrir que o único caminho de volta exige uma edição improvisada dos dados.

A promoção precisa de responsáveis, limites e um relógio

Um corte está pronto quando pessoas nomeadas podem decidir, com evidências atuais, se devem continuar, pausar ou reverter. Um convite de calendário e um painel não dão essa capacidade. A equipe precisa de um registro operacional que ligue cada sinal a uma ação e cada ação a uma função responsável.

Escreva uma ficha de promoção antes do tráfego sombra. Nomeie a versão candidata, o controle de rota, a marca d'água, o modo de compatibilidade, a profundidade esperada da fila, a mudança de latência permitida, as regras de paridade e quem pode mover o tráfego. Registre os comandos ou ações exatos para cada incremento e reversão. Se o procedimento depende de um engenheiro lembrar uma opção não documentada, ensaie até eliminar essa dependência.

Mova o tráfego em incrementos que revelem efeitos de carga sem criar uma nova autoridade de dados em cada fase. Para leituras sem estado, roteamento percentual pode bastar. Para trabalho com estado, roteie por uma partição estável, como identificador da conta, tipo de tarefa ou tenant, para impedir que uma unidade salte entre implementações. Grave a atribuição. Um percentual aleatório em escritas relacionadas pode dividir um fluxo entre dois proprietários e fazer a falha parecer intermitente.

O tempo importa de duas formas. O novo serviço precisa de exposição suficiente para encontrar trabalho representativo, e cada etapa precisa de duração máxima antes de uma escolha explícita. Uma implantação parcial sem fim pode virar arquitetura permanente, com dois painéis, dois manuais e nenhum proprietário claro. Defina o momento pela forma do tráfego, não pela paciência da gestão. Um serviço com lote diário importante deve vê-lo antes da promoção. Um caminho de fim de trimestre exige reprodução gravada quando esperar pelo evento real não fizer sentido.

Separe limites de infraestrutura e de semântica. Saturação de CPU, conexões esgotadas, crescimento da fila e timeouts dizem se o serviço suporta a carga. Totais de estado, números de transições, arredondamentos, decisões de permissão e efeitos pretendidos dizem se ele mantém o comportamento certo. Uma versão rápida e errada deve parar antes de uma temporariamente lenta e correta.

Use um registro curto de decisão durante a implantação:

1. O responsável pela versão registra a partição de tráfego e a marca d'água antes de mudar a rota.
2. O observador confirma sinais de infraestrutura e resultados de paridade para essa partição.
3. O responsável pelo domínio classifica cada diferença semântica nova como explicada, bloqueadora ou aceita com justificativa escrita.
4. O responsável pelo incidente confirma que a reversão continua possível com o esquema atual e o trabalho na fila.
5. O responsável pela versão promove, mantém ou reverte e registra as evidências usadas.

Isso não é cerimônia vazia. Evita um padrão conhecido: a infraestrutura parece saudável, a implantação avança e uma diferença de negócio sem explicação fica para o turno seguinte porque ninguém tem autoridade para interromper a promoção. O registro torna a incerteza visível enquanto reverter ainda custa pouco.

Mantenha um relógio para recuperação técnica e outro para dados. Mudar a rota de volta pode levar segundos, enquanto reproduzir eventos perdidos ou reconstruir uma projeção leva mais. Declare os dois objetivos. Considerar a reversão concluída quando as solicitações voltam ao monólito esconde reparos pendentes e incentiva a apagar evidências cedo demais.

A promoção termina somente depois de limpar a propriedade. Remova caminhos temporários de leitura dupla, revogue permissões antigas de banco, arquive os resultados conforme a retenção combinada e atualize o catálogo e a escala de plantão. Deixar permissões de migração transforma uma ponte controlada em interface permanente não oficial. A próxima extração deve começar com menos caminhos escondidos.

A primeira extração testa o sistema de migração

O primeiro serviço tem sucesso quando a organização consegue repetir o método com melhores evidências e menos coordenação. Seu valor de negócio importa, mas seu segundo resultado é um sistema de migração testado: descoberta de dependências, captura de contrato, reprodução de tráfego, transferência de dados, portões de promoção e roteamento reversível.

Registre onde o plano discordou da produção. Talvez um procedimento armazenado tivesse uma escrita ausente da busca no código. Talvez as repetições não reutilizassem identificador algum. Talvez a maior carga viesse de uma tarefa trimestral. Transforme cada surpresa em consulta automatizada, rastro ou portão para o próximo candidato. Uma retrospectiva sem um controle alterado apenas preserva a história.

Mantenha o serviço novo independente na operação após o lançamento. Dê a ele seu próprio artefato implantável, sinais técnicos e de domínio, limites de recursos, responsável de plantão e um manual para trabalho travado. Não exija uma versão do monólito para mudar sua implementação. Não deixe seu banco virar um esquema conveniente de relatórios para novos consumidores. Cada leitor direto cria outro problema futuro de extração.

A modernização da arquitetura deve seguir o comportamento observado, não transportar literalmente módulos antigos para processos novos. Uma análise do código inteiro ajuda porque o comportamento legado costuma atravessar linguagens, procedimentos armazenados, arquivos em lote e código cliente. CodeHero lê essas fontes em conjunto e entrega reescritas em menos de 30 dias, mas rapidez não elimina a necessidade de nomear um proprietário dos dados e testar a reversão.

Escolha o candidato cuja falha pode ser contida, cujas escritas podem ter um proprietário e cujos consumidores suportam uma fronteira de rede sem entrar em uma transação distribuída. Prove isso com tráfego gravado e volte a rota uma vez antes do corte real. Uma equipe que nunca executou a reversão tem um documento de reversão, não uma capacidade de reversão.