Nos últimos tempos, as ferramentas de IA (Claude, ChatGPT, Cursor, Gemini, Copilot) passaram a ocupar um espaço cada vez maior ao nosso lado. A velocidade de desenvolvimento cresceu exponencialmente, mas, para ser sincero, tenho a impressão de que a qualidade final dos serviços não acompanhou esse ritmo. Tornou-se comum encontrar tantos bugs quanto funcionalidades novas, assim como ouvir: “Não sei por que isso ficou assim”.

À medida que desenvolvemos mais rápido, deixamos de examinar cada linha de código com o mesmo cuidado. Por isso mesmo, acredito que se tornou ainda mais necessário ter uma base sólida para orientar a IA na direção correta. Para manter a qualidade do resultado, precisamos identificar problemas no código gerado pela IA e redirecioná-la para aquilo que realmente queremos. Essa base pode envolver desenvolvimento orientado ao domínio, abstração, TDD (Test-Driven Development, desenvolvimento orientado a testes), uso adequado de bibliotecas, vantagens de performance, entre outros aspectos.

No entanto, sempre que pergunto a colegas de frontend — e também a profissionais de outras áreas de TI — “Qual é a tarefa mais difícil no desenvolvimento frontend?”, a resposta que mais ouço é sempre a mesma: “Gerenciar o fluxo de estado.”

Neste artigo, pretendo explicar por que gerenciar esse fluxo é tão difícil e que tipo de discernimento e sensibilidade precisamos desenvolver para lidar bem com ele.

O que é estado (State)?

Antes de entrar no assunto propriamente dito, vamos começar pela pergunta mais básica: afinal, o que exatamente chamamos de “estado”?

Enquanto estudava desenvolvimento frontend, eu lia com frequência os textos de hoseung.me. Ali, estado é definido como “todo dado capaz de afetar a UI”. Número de curtidas, itens do carrinho, modal aberto ou fechado, valores digitados, informações do usuário autenticado, aba selecionada, resultados de busca, estado de carregamento: tudo isso é estado.

A documentação oficial do React oferece uma definição mais formal. O próprio título da página é “State: A Component's Memory”; em outras palavras, trata-se de “um mecanismo que permite ao componente reter dados entre renderizações e acionar uma nova renderização no React quando esses dados são atualizados”. Ou seja, são dados que não desaparecem com o tempo, mudam em resposta a algum evento e fazem a UI ser renderizada novamente quando mudam. Há ainda outro ponto importante: o estado é isolado por instância do componente. Mesmo que o mesmo componente apareça dez vezes em uma página, cada instância terá seu próprio estado independente. Esse fato se conecta diretamente à discussão posterior sobre “onde o estado deve ficar”.

As duas definições apontam para o mesmo lugar: estado é “um valor que muda ao longo do tempo e afeta a renderização”. Uma constante que não muda não é estado. Um design token primitivo fixado no build time não é estado, mas um dark mode que o usuário pode alternar é. (A rigor, o valor em si é resolvido conforme o estado do tema, dark ou light; portanto, é mais preciso dizer que a “seleção do tema” é o estado e que o token é o espelho no qual esse estado se reflete.)

Há um aspecto que vale destacar: nem todo estado vive em um componente. Alguns estados vivem em cookies; outros, em localStorage, sessionStorage ou IndexedDB; outros ainda, na URL. Quando trazemos dados do servidor para o cliente e os armazenamos em cache, eles também se tornam uma forma de estado. Até a posição de scroll e a pilha de histórico mantidas pelo próprio navegador às vezes precisam ser tratadas como estado, pois determinam o comportamento da aplicação.

Por que é tão difícil?

Vamos começar pensando de forma simples sobre por que lidar com estado é difícil. Não bastaria criar os estados necessários, levá-los até onde são usados e tratar corretamente suas atualizações e resets?

Com essa pergunta em mente, abra uma página do serviço em que você trabalha hoje.

Quantos componentes existem nessa página? Mesmo em uma página simples, provavelmente há de dezenas a centenas de componentes formando uma árvore. Cada componente pode manter seu próprio estado, compartilhá-lo com componentes irmãos ou recebê-lo do pai. O estado também transita entre páginas; alguns valores precisam sobreviver a um refresh, enquanto outros devem desaparecer quando a aba é fechada.

O verdadeiro motivo de ser tão difícil gerenciar estado é este: não conseguimos visualizar de imediato onde os inúmeros estados são declarados, como são atualizados e quando deixam de existir. Conforme aumenta o número de componentes com papéis semelhantes, torna-se mais difícil tanto nomear estados quanto rastrear o código que os altera.

É assim que surge uma teia invisível. Um clique no componente A invalida os dados de B; a invalidação de B fecha a UI de C; ao fechar C, os dados digitados no formulário desaparecem. Se essa cadeia não estiver explicitada em nenhum lugar do código, teremos de reconstruir mentalmente toda a teia ao depurar um bug.

Como, então, organizar essa teia? Para mim, o primeiro passo é reconhecer que “existem diferentes tipos de estado”.

Nem todo estado é igual

Kent C. Dodds divide o estado em Server Cache (informações que existem no servidor e são mantidas pelo cliente para acesso rápido) e UI State (informações que existem apenas na UI para controlar o comportamento da interface). Muitas vezes erramos justamente ao agrupar os dois.

A documentação oficial do TanStack Query define a ferramenta como uma biblioteca de Server State, responsável por gerenciar operações assíncronas entre servidor e cliente, enquanto Redux, MobX e Zustand são definidos como bibliotecas de Client State. (É possível armazenar dados assíncronos nelas, mas isso é ineficiente.)

O ponto central é claro: Server State e Client State são problemas diferentes. Server State é assíncrono, pode ser alterado por outros usuários e se torna stale com o tempo. Client State é síncrono, está sob nosso controle e desaparece com um refresh. (Mais precisamente, quando a página é descarregada, o runtime JavaScript é reiniciado, e a árvore de componentes mantida na memória heap, junto com seus estados, é coletada. Por isso, na próxima montagem, tudo recomeça pelo valor inicial de useState.) Se tentarmos tratar os dois com a mesma ferramenta, teremos de implementar por conta própria padrões como invalidação de cache, atualização em background e optimistic updates.

Vou um passo além e divido o estado do frontend em sete categorias. Vale esclarecer desde já que essas categorias não se separam perfeitamente em um único eixo. Local de armazenamento, origem, ciclo de vida e função se misturam, de modo que um mesmo estado pode pertencer a mais de uma categoria. Em vez de uma taxonomia perfeita, encare-as como perguntas que ajudam a decidir como gerenciar um estado.

• Estado local (Local State) — Estado usado apenas em um componente ou em uma subárvore restrita
• Estado global (Global State) — Estado que precisa ser compartilhado por toda a aplicação
• Estado do servidor (Server State) — Estado cuja fonte da verdade é o servidor e cuja cópia no cliente é um cache
• Estado de formulário (Form State) — Estado temporário que existe enquanto o usuário preenche dados
• Estado da URL (URL State) — Estado compartilhável que vive na barra de endereços e sobrevive ao refresh
• Estado externo (External State) — Estado fora do React, como cookies, localStorage, sessionStorage e IndexedDB
• Guard de estado (State Guard) — Lógica que bloqueia, permite ou valida acessos e ações conforme combinações de estado, em vez de ser um estado em si

Além dessas categorias, há estados de fluxo que podem exigir uma máquina de estados e estados colaborativos em tempo real baseados em WebSocket ou CRDT.

Vamos analisar, uma a uma, por que cada categoria exige ferramentas diferentes e com que perspectiva devemos abordá-la.

Estado local (Local State)

É a forma mais simples de estado. Ele é usado apenas dentro de um componente, e quem está de fora não precisa — nem deveria precisar — conhecê-lo. Alguns exemplos são: modal aberto ou fechado, botão de alternância on/off, hover e termo de busca enquanto está sendo digitado.

function SearchBox() {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

Isso provavelmente já é familiar. A verdadeira dificuldade do estado local, porém, está na decisão de “onde esse estado deve ficar”.

No artigo de Kent C. Dodds sobre State Colocation, ele observa que as pessoas estão acostumadas a “elevar (lift up)” o estado, mas raramente voltam a “aproximá-lo (colocate)” quando o código muda.

Elevar o estado é algo que fazemos naturalmente quando componentes irmãos precisam compartilhá-lo. Como os dois precisam enxergar os mesmos dados, levamos o estado para o pai comum e o distribuímos via props.

O problema surge quando os componentes irmãos deixam de precisar desse estado. Raramente fazemos o caminho inverso, descendo-o de volta para o filho. Como resultado, o componente pai acumula vários estados que na verdade não lhe dizem respeito e, sempre que renderiza novamente, acaba levando consigo toda a árvore de filhos.

Por isso, o primeiro princípio do estado local é: para tornar o código mais rápido e simples, mantenha o estado o mais próximo possível do código que o utiliza. Se um estado é usado apenas por um único filho, não há motivo para o pai mantê-lo. Mova-o para dentro desse filho; o pai ficará mais leve.

Estado global (Global State)

Estado global é aquele que precisa estar acessível de qualquer ponto da aplicação. Informações de login, tema, idioma e notificações (toasts) são possíveis candidatos.

A diferença entre estado local e global não se resume a “onde ele vive”. O que muda é o contrato de referência. O estado local assume o compromisso de que “isso só tem significado dentro deste componente”; já o estado global publica para todo o código o compromisso de que “esse valor pode ser acessado por esse nome em qualquer lugar da aplicação”. A essência do estado global está no custo desse compromisso.

Criar um estado global significa, na prática, adicionar uma dependência implícita em toda a aplicação.

Estado de servidor (Server State)

Colocamos os dados recebidos de uma API no estado do cliente, gerenciamos loading e error manualmente com booleanos e, em algum momento, chegamos à pergunta: “Por que estou escrevendo o mesmo boilerplate toda vez?”

Tanner Linsley, principal mantenedor do TanStack, diz que “Client State é síncrono e previsível. Server State é assíncrono, compartilhado entre vários componentes e exige atenção ao cache, às atualizações em background e aos estados de erro.” Em outras palavras, Server State é uma espécie fundamentalmente diferente de Client State. Não devemos tratá-los com a mesma ferramenta.

A dificuldade do Server State não decorre das ferramentas, mas da natureza dos dados.

Os dados que o cliente exibe pertencem ao servidor. Aquilo que o cliente possui é apenas um snapshot de determinado momento. Com o passar do tempo, esses dados ficam stale. Além disso, são assíncronos, podem falhar e passam por estados como pending, error e success.

A característica mais importante é que não existe garantia de que as respostas retornarão na ordem em que as requisições foram enviadas. Imagine digitar rapidamente “react” em uma caixa de busca. As requisições r → re → rea → reac → react são enviadas nessa ordem; porém, se a resposta de “react” chegar primeiro e a de “rea” chegar depois, a tela exibirá os resultados de “rea”. Para evitar esse problema, é preciso lidar com riscos de concorrência (race conditions) que exigiriam implementar manualmente, a cada vez, um AbortController ou o rastreamento de IDs das requisições.

Estado de formulário (Form State)

Formulários têm um tipo peculiar de estado. Enquanto o usuário digita, ele muda intensamente; depois do envio, em geral desaparece. Não é compartilhado com nenhum outro lugar e, na maioria dos casos, também não há onde armazená-lo.

O problema é que essa “mudança intensa” custa caro. Se cada tecla pressionada causar uma nova renderização do React, o atraso na digitação pode se tornar perceptível em formulários grandes. Além disso, um formulário não serve apenas para “guardar valores”. Validação, dirty check, estado de envio, mensagens de erro e fluxos em múltiplas etapas coexistem e mudam ao mesmo tempo dentro de um único formulário.

Espera-se que um formulário em várias etapas, como um checkout de três passos, “preserve o progresso mesmo após um refresh no meio do processo”. Se seus valores forem mantidos apenas com useState, todos desaparecerão no refresh. É natural armazená-los em sessionStorage (armazenamento temporário por aba) ou na URL (para etapas compartilháveis). Ou seja, dependendo dos requisitos de ciclo de vida, o estado de formulário se combina com External State ou URL State.

Estado da URL (URL State)

Imagine uma página de busca em que categoria, ordenação e número da página são usados como filtros. Se esses estados forem mantidos com useState, três problemas surgirão ao mesmo tempo.

• Ao atualizar a página, todos os filtros voltam aos valores iniciais
• Ao compartilhar a URL com alguém, essa pessoa verá a página sem os filtros aplicados
• Ao clicar em voltar, você não retornará aos filtros anteriores

Para resolver esses problemas, é natural colocar o estado na URL. A própria URL é um armazenamento persistente gratuito, compatível com refresh, compartilhamento e histórico.

/products?category=shoes&sort=price-desc&page=2

Essa única URL contém o estado completo de “página 2 da categoria de calçados, ordenada por preço decrescente”. Não é necessário mantê-lo separadamente com useState.

Quando, então, é apropriado tratar estado na URL? A URL é uma interface pública. Senhas, tokens de autenticação e anotações temporárias que o usuário não queira mostrar a outras pessoas não devem estar na URL. Além disso, inserir diretamente na URL valores que mudam com muita frequência — como uma busca atualizada a cada tecla — enche a pilha de histórico de lixo. Nesses casos, devemos aplicar a alteração após um debounce, reservar push para quando fizer sentido e usar replace nas atualizações que não devem adicionar uma entrada ao histórico.

Os valores da URL são sempre strings. Números, booleanos, arrays e objetos precisam passar por serialização e desserialização. Além disso, a URL precisa seguir as regras de percent-encoding, que dão tratamento especial a &, =, caracteres coreanos, espaços e outros elementos. Implementar tudo isso manualmente a cada vez logo se transforma em uma fonte de bugs.

const params = new URLSearchParams(location.search);
const page = Number(params.get("page") ?? "1");
params.set("page", String(page + 1));
navigate(`?${params.toString()}`);
 
const [page, setPage] = useQueryState("page", parseAsInteger.withDefault(1));

Bibliotecas como nuqs resolvem os dois problemas por meio do conceito de parser. Parsers como parseAsInteger, parseAsBoolean e parseAsJson cuidam de uma só vez da serialização, da desserialização e dos tipos. A biblioteca oferece suporte à maioria dos ambientes, incluindo Next.js (App Router e Pages Router), React Router v6/v7, TanStack Router e Remix.

Isso significa que podemos colocar qualquer quantidade de estado na URL? Além dos problemas de serialização e tipos, ainda existe uma última restrição a considerar. A RFC 7230 não define um limite exato, mas recomenda que “o servidor ofereça suporte a pelo menos 8.000 octetos” (octeto é a unidade usada em redes e comunicação de dados para designar, sem ambiguidade, um conjunto de 8 bits, isto é, 1 byte). Os limites também variam entre navegadores: browsers modernos geralmente aceitam de 8 KB a dezenas de milhares de caracteres, mas mecanismos de busca, o processamento de OG/compartilhamento em redes sociais e alguns gateways podem truncar a URL por volta de 2 KB. Portanto, não devemos inserir dados indefinidamente na URL. É mais seguro manter nela apenas os principais filtros compartilháveis e deixar o restante a cargo do sessionStorage ou de um armazenamento no servidor.

Estado externo (External State)

O React conhece apenas o estado dentro dele próprio. Nossa aplicação, porém, conversa constantemente com o mundo fora do React. Os estados que vivem nesse mundo sobrevivem e mudam independentemente do ciclo de vida do React. O External State abordado aqui inclui Cookie, localStorage,sessionStorage,IndexedDB.

Como escolher o armazenamento adequado? Costumo pensar em quatro perspectivas: duração, capacidade, sincronicidade e segurança.

Para tokens de autenticação, a recomendação da OWASP prioriza cookies HttpOnly + Secure. Como o localStorage é acessível via JavaScript, basta uma exposição a XSS para que o token seja roubado diretamente. Alguns guias de segurança recomendam um padrão híbrido: access token na memória e refresh token em um cookie HttpOnly. Para dados persistentes, não sensíveis e que mudam pouco, usa-se localStorage; para dados que devem desaparecer com a aba, sessionStorage. IndexedDB costuma ser usado para cache offline, grandes volumes de dados e arquivos.

Cookies e Web Storage (local/session) armazenam apenas strings. Por isso, inserir um objeto exige passar por JSON.stringify/JSON.parse. O JSON, contudo, tem limitações.

JSON.stringify({ when: new Date() });
// → { "when": "2026-05-19T..." } — Date becomes a string
 
JSON.stringify({ map: new Map([["a", 1]]) });
// → { "map": {} } — Map is lost entirely
 
JSON.stringify({ value: undefined });
// → "{}" — the undefined field is omitted

Date se torna string em um round trip por JSON, enquanto Map, Set e undefined podem perder dados. No comportamento padrão, BigInt faz JSON.stringify lançar um TypeError, portanto a serialização falha por completo. Ao armazenar objetos fora do React, devemos sempre ter consciência de quais tipos podem desaparecer, ser alterados ou fazer a serialização falhar e, se necessário, criar um adapter.

A verdadeira dificuldade do External State é que o React não detecta suas mudanças automaticamente. Gravar um valor no localStorage não faz um componente React renderizar novamente. Em geral, há três padrões para resolver isso.

• Encapsular o armazenamento em um hook customizado (useLocalStorage) e sincronizar o External State com o estado do React. É uma solução leve, mas, quando implementada do zero, exige lidar com casos extremos como múltiplas abas, SSR e tearing.
• Usar o hook useSyncExternalStore, introduzido no React 18, para “sincronizar o React com estados externos”. Com isso, é possível garantir que não ocorra tearing durante a renderização concorrente. É a ferramenta padrão para integrar localStorage, APIs do navegador e stores externos.
• Como bibliotecas de estado oferecem integração com armazenamento externo como recurso de primeira classe — por exemplo, o middleware persist do Zustand e o atomWithStorage do Jotai —, podemos aproveitar implementações já prontas.

Há ainda outro princípio importante: no momento em que trazemos um estado externo para o React, a responsabilidade pela sincronização passa a ser nossa. E se ele for atualizado em outra aba? E se o servidor alterar o cookie? E se o usuário modificar diretamente o localStorage pelas ferramentas de desenvolvedor do navegador? Essas situações frequentemente se tornam grandes fontes de bugs.

Guard de estado (State Guard)

A última categoria tem uma natureza um pouco diferente. Não é o estado em si, mas a lógica que usa uma combinação de estados para impedir, permitir ou validar determinado fluxo.

O exemplo mais comum é o guard de autenticação (Auth Guard).

function ProtectedRoute({ children }) {
  const { isAuthenticated, isLoading } = useAuth();
 
  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return children;
}

Aqui, o estado isAuthenticated controla o fluxo de roteamento. Isso é uma lógica de guard. Existem vários tipos: guard de autenticação (usuário autenticado), guard de autorização (papel ou permissão específica), guard de fluxo (ramificação de entrada) e guard de validação (habilitação de etapa), entre outros.

A lógica de guards tende a se concentrar em um único lugar. É comum um componente reunir tudo: “se não estiver autenticado, vá para o login; se não tiver permissão, mostre 403; se o carrinho estiver vazio, vá para a página de produtos; se o usuário estiver suspenso, exiba o aviso de suspensão”. Quanto mais inchado fica o guard, mais difícil é depurar qual condição bloqueou o fluxo e onde isso aconteceu.

Um bom guard verifica apenas uma coisa. A combinação é feita por Composition.

<AuthGuard>
  <RoleGuard role="admin">
    <FlowGuard require={["cartHasItems"]}>
      <CheckoutPage />
    </FlowGuard>
  </RoleGuard>
</AuthGuard>

Cada guard toma apenas uma decisão, e a estrutura em árvore é responsável pela composição. Para adicionar um novo guard, não é necessário alterar os existentes.

Ao trabalhar com guards, há algo que exige ainda mais reflexão do que decidir o que bloquear: definir para onde encaminhar o usuário e como tratar o fluxo depois disso. Um guard que apenas bloqueia, sem fallback, termina em uma tela branca ou em um spinner infinito.

O bug mais comum ocorre quando “o conteúdo protegido pisca brevemente antes de a verificação assíncrona do guard terminar”. A validação do token de autenticação e a consulta de permissões quase sempre são assíncronas; nesse intervalo, isAuthenticated pode ficar temporariamente como undefined ou false. Se o estado de loading não for tratado explicitamente, a tela protegida pode ser exposta nesse intervalo ou o usuário pode ser redirecionado por engano para a página de login.

// Ignores loading and handles only missing data => incorrect
if (!user) return <Navigate to="/login" />;
 
// Treat loading as a first-class state (early return) => correct
if (isLoading) return <Spinner />;
if (!user) return <Navigate to="/login" replace />;
return children;

Dois modelos são usados com frequência na implementação de guards de autorização.

• RBAC (Role-Based Access Control): concede permissões por papel. Por exemplo: “admin pode ver as informações de todos os usuários”. É simples e rápido, mas o número de papéis explode à medida que eles se tornam mais granulares
• ABAC (Attribute-Based Access Control): determina permissões a partir de uma combinação de atributos. Por exemplo: “se o usuário for o autor do post, pertencer à mesma equipe ou for admin”. Tem grande poder de expressão, mas é difícil de implementar e depurar

Como mostra o guia de RBAC do TanStack Router, recomenda-se o padrão de inserir o guard em beforeLoad, no nível do router. O ponto central é que as verificações de permissão devem poder ser representadas como dados — uma lista de papéis ou permissões — em vez de ficarem espalhadas pelo código. Assim, uma mudança na política de acesso se resume a uma mudança de dados.

Conclusão

Vamos recapitular. O gerenciamento de estado não é difícil porque as bibliotecas são difíceis. Ele é difícil porque frequentemente esquecemos que existem diferentes tipos de estado e deixamos passar o fato de que cada tipo exige ferramentas e formas de pensar distintas.

Mantenha o estado local o mais próximo possível; questione mais uma vez se o estado global é realmente global; trate Server State como cache; separe os formulários do domínio; use a URL de forma mais ativa; assuma conscientemente as responsabilidades envolvidas no armazenamento externo; e divida os guards em partes pequenas que possam ser compostas. Esses são os fundamentos para lidar com as sete categorias.

Acima de tudo isso, o discernimento necessário se resume, no fim, a quatro perguntas.

• Onde está a Single Source of Truth destes dados?
• Este valor pode ser calculado ou realmente precisa ser armazenado?
• Existe alguma combinação impossível entre esses estados?
• Este estado realmente deveria estar neste lugar?

Fazer essas perguntas sempre que criamos uma nova tela, revisamos um PR ou recebemos código produzido por IA é, acredito, o caminho mais seguro para desenvolver esse discernimento e essa sensibilidade.

Como mencionei no início, a IA permanecerá ao nosso lado por muito tempo. O tempo que dedicamos a examinar linha por linha continuará diminuindo. Mas, justamente por isso, a capacidade de responder a pequenas perguntas como “Onde este estado deveria ficar?” se tornará ainda mais valiosa. É fácil pedir à IA: “adicione mais um useState aqui”. Saber que novo fio essa linha acrescenta à teia da nossa aplicação, porém, depende exclusivamente do discernimento de quem lê o código.

Não existe uma resposta única. Ainda assim, há uma diferença evidente entre “criar estado sem saber o que é estado” e “criá-lo tendo consciência de seu tipo e de sua localização”. Espero que, da próxima vez que você estiver prestes a escrever uma linha de useState, pare por um instante e pergunte: “A qual categoria de estado isto pertence?”

Referências

Ao longo da minha experiência com desenvolvimento, encontrei a palavra "domínio (Domain)" com bastante frequência. Mas, quando alguém pergunta "afinal, o que exatamente é um domínio?", não é tão fácil dar uma resposta clara. (Sinceramente, quando comecei a programar, achava que domínio significava www.)

Ao procurar informações sobre domínio, naturalmente chegamos a conceitos como modelo de domínio, objeto de domínio e modelo de objetos de domínio. Sempre senti falta, porém, de textos que organizassem tanto as diferenças entre eles quanto o significado desses conceitos no frontend, e não no backend. Neste texto, começarei pelas definições de cada conceito e, com exemplos, mostrarei como separar e abstrair a lógica de domínio no frontend de forma adequada.

Ultimamente, tenho me interessado bastante pelo domínio tributário. Como a declaração do imposto de renda global se aproxima em maio, os exemplos deste texto tratarão de impostos.

Domínio (Domain)

Comecemos pela pergunta mais básica. O que é um domínio?

Eric Evans define domínio da seguinte forma em seu livro Domain-Driven Design: Tackling Complexity in the Heart of Software (2003).

Uma esfera de conhecimento, influência ou atividade.

"A sphere of knowledge, influence, or activity."

Em termos simples, domínio é a própria área do problema que se pretende resolver por meio da programação. Se estamos criando um serviço de declaração de impostos, "declaração de impostos" é o domínio; se estamos criando uma plataforma de sinistros de seguros, "sinistros de seguros" é o domínio. O domínio não é código. É uma área de problemas do mundo real que existe antes do software.

O que isso significa para quem desenvolve frontend? A UI que criamos é, no fim das contas, uma janela (window) que permite apresentar esse domínio ao usuário e possibilitar sua manipulação. Se desenvolvemos serviços de restituição de impostos como Toss Income ou 3o3, cujo domínio principal é tributário, estamos representando na UI conceitos do domínio como tipo de renda, coeficiente de despesas, dedução da renda, crédito tributário e valor da restituição. Portanto, quem desenvolve frontend também precisa compreender profundamente o domínio com que trabalha. Isso significa que entender "qual problema este serviço resolve" é tão importante quanto construir bons componentes de UI.

Mas até um único domínio como "impostos" contém inúmeros subdomínios quando examinado por dentro. Basta olhar para o pipeline de cálculo do imposto de renda global, que conheço apenas superficialmente.

Cada etapa desse pipeline é um subdomínio com regras e dados próprios. Dentro do grande domínio de "impostos", entrelaçam-se os subdomínios de renda (Income), deduções (Deduction), imposto (Tax) e declaração (Filing). Como dividi-los no código é justamente a questão central da modelagem de domínio.

Modelo de domínio (Domain Model)

Então, o que é um modelo de domínio? Qual é a diferença entre domínio e "modelo de domínio"?

Martin Fowler e Eric Evans definem modelo de domínio da seguinte maneira.

Um modelo de objetos do domínio que incorpora tanto comportamento quanto dados. — Martin Fowler

An object model of the domain that incorporates both behavior and data.

Um sistema de abstrações que descreve aspectos selecionados de um domínio e pode ser usado para resolver problemas relacionados a esse domínio. — Eric Evans

A system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain.

O ponto central é a "abstração seletiva". Um modelo de domínio não contém tudo o que existe no mundo real. Assim como um diretor de cinema não registra todas as cenas da realidade, mas escolhe apenas as necessárias para contar a história, o modelo de domínio também seleciona e estrutura apenas os aspectos necessários para resolver o problema.

Há um ponto importante aqui. Um modelo de domínio não precisa necessariamente ser código. Pode ser um diagrama desenhado em um quadro branco ou um modelo mental (Mental Model) compartilhado entre os integrantes da equipe. Em última análise, o próprio termo modelo de domínio pode designar um conceito independente do software.

Há uma parte que costuma confundir especialmente quem desenvolve frontend: olhar para a estrutura de uma resposta de API e pensar "este é o modelo de domínio". Mas isso é um modelo de dados (Data Model), não um modelo de domínio.

Podemos distinguir modelo de dados e modelo de domínio da seguinte forma.

O modelo de dados define "em que formato os dados circulam", enquanto o modelo de domínio define "o que esses dados significam para o negócio e quais regras seguem". Quando não distinguimos os dois, os componentes passam a depender diretamente da estrutura da resposta da API, e qualquer mudança no schema do backend acaba abalando todo o frontend.

Objeto de domínio (Domain Object)

Se o modelo de domínio é um sistema de conceitos, o objeto de domínio é a concretização desse conceito em código.

Em um texto de Jason Swett, responsável pelo Code with Jason, o objeto de domínio é definido assim.

Eu chamaria de objeto de domínio qualquer objeto do meu modelo de objetos que também exista como conceito no meu modelo de domínio.

Any object in my object model that also exist as a concept in my domain model I would call a domain object.

Ou seja, se existe o conceito de "renda global" no modelo de domínio e um tipo chamado Income no código, esse Income é um objeto de domínio. Mas nem todo objeto no código é um objeto de domínio. Elementos como HttpClient, LocalStorageAdapter e useDebounce são ferramentas técnicas, não conceitos do domínio.

Entity e Value Object

Evans classifica os objetos de domínio em três categorias: Entity, Value Object e Service. (Martin Fowler chama essa divisão de "Evans Classification".) Service é um conceito separado que representa "uma operação de domínio que não pertence naturalmente a um objeto específico". Como o foco deste texto é a forma de identificar os dados, examinaremos principalmente Entity e Value Object.

Uma Entity é um objeto com identidade própria que persiste ao longo do tempo e entre diferentes representações. Uma declaração de impostos (TaxFiling), um contribuinte (Taxpayer) e um registro de renda (IncomeRecord) são identificados por um ID próprio; mesmo que seus atributos mudem, continuam sendo a mesma Entity se o ID for o mesmo. Ainda que os itens de dedução de uma declaração sejam alterados, ela continua sendo a mesma declaração enquanto seu ID não mudar.

Um Value Object é um objeto cujo significado decorre apenas da combinação de seus atributos; quando todos os atributos têm os mesmos valores, os objetos são considerados iguais. Dinheiro (Money), alíquota (TaxRate) e faixa tributária (TaxBracket) são objetos em que o próprio valor carrega o significado. Uma "alíquota de 6%" é simplesmente uma "alíquota de 6%", onde quer que seja usada.

Por que essa distinção é importante no frontend? Vejamos o exemplo de código abaixo.

interface TaxFiling {
  id: string;
  taxpayerName: string;
  taxYear: number;
  status: FilingStatus;
}
 
const isSameFiling = (a: TaxFiling, b: TaxFiling) => a.id === b.id;
 
interface Money {
  amount: number;
  currency: "KRW" | "USD";
}
 
const isSameMoney = (a: Money, b: Money) =>
  a.amount === b.amount && a.currency === b.currency;

TaxFiling é uma Entity porque usa o id como critério de identidade. (O simples fato de ter um campo id não define uma Entity; o ponto central é que "esse id determina se é o mesmo objeto ou outro".) Money é identificado apenas pela combinação de amount e currency, sem id, e é considerado o mesmo valor quando todos os seus atributos são iguais.

Entity é comparada por ID; Value Object, por atributos. Quando essa distinção está clara, a lógica de gerenciamento de estado que decide "se estes dados são iguais ou diferentes" se organiza naturalmente. Ao atualizar um item de uma lista, por exemplo, localizamos e substituímos uma Entity pelo ID, enquanto um Value Object é substituído de forma imutável (immutable replace).

Modelo de objetos de domínio (Domain Object Model)

Já entendemos "modelo de domínio" e "objeto de domínio", mas o que é um modelo de objetos de domínio?

Ao pesquisar, descobri que, surpreendentemente, não há uma definição consensual. Grande parte da literatura trata "modelo de domínio", "modelo de objetos de domínio", "modelo conceitual (conceptual model)" e "modelo de objetos de análise (analysis object model)" como praticamente sinônimos. Segundo essa visão, são apenas nomes diferentes para o modelo conceitual elaborado durante a análise orientada a objetos.

Há, por outro lado, quem os veja como camadas um pouco mais separadas. Uma explicação representativa é que o modelo de objetos é justamente o ponto em que o modelo de domínio é transformado em código real.

Nessa segunda perspectiva, o modelo de objetos é a estrutura de todos os objetos de código do sistema. Isso inclui ferramentas técnicas como HttpClient e useDebounce. Dentro dele, o subconjunto dos objetos que representam conceitos do domínio e as relações entre eles constitui o modelo de objetos de domínio. Essa visão também se alinha à tradição da modelagem orientada a objetos, que define "Object Model" como a estrutura estática de um sistema (classes, atributos, operações e relações).

Considero essa perspectiva mais prática para quem desenvolve frontend. Afinal, no código que escrevemos, objetos de domínio e objetos técnicos estão sempre misturados.

No fim, domínio → modelo de domínio → modelo de objetos de domínio → objeto de domínio forma uma hierarquia que vai do abstrato ao concreto. O domínio é o mais amplo, e o objeto de domínio é o mais concreto. Por isso, ao escrever código frontend, a questão prática com que realmente lidamos é como estruturar o modelo de objetos de domínio — os tipos que representam conceitos do domínio e as relações entre eles.

Onde a lógica de domínio deve ficar no frontend?

Encerradas as definições, passemos à prática. Onde a lógica de domínio deve ficar no frontend?

Khalil Stemmler, que se interessa profundamente por design de software, primeiro defendeu que "a lógica de negócio não pertence ao frontend". Mais tarde, reviu sua posição e afirmou: "Podemos e devemos fazer no frontend quase tudo o que fazemos arquiteturalmente no backend."

Concordo com essa posição. É claro que o frontend não deve ser a fonte única da verdade (Single Source of Truth) da lógica de negócio. Esse é o papel do backend. Mas também existe, sem dúvida, lógica de domínio própria do frontend.

Pense no caso em que "é preciso mostrar em tempo real a restituição estimada com base nas informações inseridas pelo usuário". Se essa lógica de cálculo existir apenas no backend, será necessário chamar a API toda vez que o usuário corrigir um único caractere no valor da renda. A UI ficará parada durante o tempo de ida e volta pela rede e, se o usuário digitar rápido, o volume de solicitações desnecessárias crescerá de forma explosiva. Mesmo com debounce, um atraso de algumas centenas de milissegundos já é suficiente para comprometer a experiência de uma "prévia em tempo real". No fim, cálculos que exigem feedback imediato precisam ser executados diretamente pelo frontend, e passam a existir lógicas que só podem ser executadas nele.

Quando a lógica de domínio se mistura ao componente

Tomemos como exemplo uma tela de prévia do imposto de renda global. Nela, quando o usuário informa seus rendimentos, o imposto estimado é exibido em tempo real. Abaixo está um código comum em que a lógica de domínio e a lógica de UI estão misturadas.

function TaxPreviewPage() {
  const [총수입, set총수입] = useState(0);
  const [경비율, set경비율] = useState(0.641); 
  const [인적공제대상인원, set인적공제대상인원] = useState(1); 
 
  const 종합소득금액 = 총수입 - 총수입 * 경비율;
 
  const 소득공제합계 = 인적공제대상인원 * 1_500_000;
  const 과세표준 = Math.max(0, 종합소득금액 - 소득공제합계);
 
  let calculatedTax = 0;
  if (과세표준 <= 14_000_000) {
    calculatedTax = 과세표준 * 0.06;
  } else if (과세표준 <= 50_000_000) {
    calculatedTax = 과세표준 * 0.15 - 1_260_000;
  } else if (과세표준 <= 88_000_000) {
    calculatedTax = 과세표준 * 0.24 - 5_760_000;
  } else if (과세표준 <= 150_000_000) {
    calculatedTax = 과세표준 * 0.35 - 15_440_000;
  } else {
    calculatedTax = 과세표준 * 0.38 - 19_940_000;
  }
 
  const 기납부세액 = 총수입 * 0.033;
  const refundOrPayment = 기납부세액 - calculatedTax;
 
  return <div>...</div>;
}

Você consegue ver o problema desse código? Regras de negócio definidas pela legislação tributária, como "dedução pessoal de 1,5 milhão de won por pessoa", "alíquota progressiva em oito faixas" e "retenção na fonte de 3,3%", estão inseridas diretamente no componente React. A legislação tributária muda todos os anos; se essas regras estiverem espalhadas pelos componentes, será preciso caçar todos os lugares que devem ser corrigidos a cada revisão. E, se houver cenários E2E mantidos não só por quem desenvolve, mas também pela equipe de QA, o custo dos testes também não será pequeno.

Com isso, fica difícil distinguir lógica de View e lógica de negócio, e tudo acaba emaranhado em inúmeras condicionais e hooks customizados.

Vamos separar a lógica de domínio

Tomemos emprestado o princípio central da abordagem de Clean Architecture de Alex Bespoyasov: separar a lógica de domínio em funções puras que não dependem de framework.

O domínio é o núcleo que distingue uma aplicação de outra. Podemos pensar no domínio como algo que não mudaria se migrássemos do React para o Angular.

The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular.

Vamos refatorar o exemplo de cálculo de impostos acima.

Primeiro, definimos os tipos e as regras do domínio para manter as informações relacionadas coesas.

export interface Income {
  grossAmount: number;
  expenseRate: number;
}
 
export interface Deductions {
  personalCount: number;
  pensionPaid: number;
  additionalDeductions: number;
}
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
const TAX_BRACKETS = [
  { limit: 14_000_000, rate: 0.06, progressiveDeduction: 0 },
  /** ...구간들... **/
] as const;

Depois, separamos a lógica de domínio em funções puras.

Separamos na função computeFullTax as lógicas de cálculo de renda, deduções, base tributável, imposto e restituição mencionadas anteriormente. Cada etapa volta a ser dividida em pequenas funções puras. Se o tipo do resultado for inferido com ReturnType<typeof computeFullTax>, não será necessário declarar uma interface separada.

Depois disso, o componente apenas "usa" a lógica de domínio.

import { computeFullTax } from "../domain/tax";
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({
    grossAmount: 0,
    expenseRate: 0.641,
  });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1,
    pensionPaid: 0,
    additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

O que mudou?

• A tabela das oito faixas progressivas (TAX_BRACKETS) está reunida em um só lugar; quando a legislação mudar, basta alterar domain/tax.ts.
• O pipeline de cálculo está coeso em uma única função, computeFullTax, permitindo visualizar o fluxo completo de uma vez. (Agrupamos tudo para manter o exemplo simples, mas, em um projeto real, convém subdividir ainda mais por finalidade, como cálculo de renda, cálculo de deduções e apuração do imposto.)
• O componente se concentra apenas em "como exibir". Mesmo que a alíquota mude, não é preciso alterar o componente.
• Mesmo que haja uma migração do React para outro framework, domain/tax.ts não muda.

Quando a lógica de domínio é separada, os testes se tornam surpreendentemente simples. Isso é especialmente importante no domínio tributário, pois a precisão dos cálculos é o próprio dinheiro do usuário.

Funções puras que contêm cálculos tributários não precisam de React Testing Library, render nem screen.getByText. Basta fornecer a entrada e verificar a saída. Casos como "alíquota de 6% até 14 milhões de won", "imposto igual a zero quando a base tributável é zero" e "restituição sobre uma renda de 30 milhões de won de um profissional autônomo" podem ser expressos em um it de uma única linha. Os testes unitários do domínio estabelecem naturalmente os critérios de separação dos componentes, e o código de teste ainda funciona como documentação.

Modelo de domínio anêmico (Anemic Domain Model)

Na seção anterior, separamos a lógica de cálculo. Mas a lógica de domínio também inclui regras de transição de estado e decisões de permissão. Perguntas como "é possível editar esta declaração agora?", "ela pode ser enviada?" e "é possível mudar o tipo de solicitação?" fazem parte disso. Ao separar essas regras, é fácil cair em uma armadilha que Martin Fowler chamou de modelo de domínio anêmico (Anemic Domain Model).

Um modelo de domínio anêmico é uma situação em que os tipos estão bem definidos na linguagem do domínio, mas as regras que operam sobre eles ficam espalhadas para fora do domínio. Vejamos o domínio de declaração de impostos (Filing). Os tipos estão bem organizados.

// types/filing.ts
export interface TaxFiling {
  id: string;
  status: "draft" | "submitted" | "reviewing" | "completed" | "amended";
  taxYear: number;
  filingType: "regular" | "late" | "amendment";
  determinedTax: number;
}

Mas as regras de decisão e transição desse tipo estão inseridas em outros lugares.

// utils/filingHelpers.ts
export function canAmendFiling(filing: TaxFiling) {
  return filing.status === "completed" && filing.filingType !== "amendment";
}
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 같은 도메인 규칙을 컴포넌트 안에 다시 작성한다
  const canEdit = filing.status === "draft" || filing.status === "reviewing";
  // ...
}
 
// hooks/useSubmitFiling.ts
export function handleSubmitFiling(filing: TaxFiling) {
  if (filing.status !== "draft") return;
  // ...
}

A mesma regra de domínio existe em três lugares — utils, componente e hook —, cada um com uma forma diferente. Se surgir um requisito dizendo "as condições para solicitação serão alteradas", será necessário procurar todos os pontos que precisam mudar; qualquer um que for esquecido passará a tomar uma decisão incorreta em algum lugar do site. Fowler criticou esse tipo de código afirmando que "ele não difere de código procedural revestido apenas com uma aparência orientada a objetos".

A solução é a mesma aplicada à lógica de cálculo na seção anterior: colocar as regras ao lado do tipo.

export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus =
  | "draft"
  | "submitted"
  | "reviewing"
  | "completed"
  | "amended";
 
export type FilingType = "regular" | "late" | "amendment";
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === "draft";
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === "draft" && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === "completed" && filing.filingType !== "amendment";
}

Agora, as regras relacionadas às declarações são gerenciadas em um único lugar: domain/filing.ts. Qualquer componente pode chamar canAmend(filing), e, se a regra mudar, basta alterar esse arquivo. O ponto central é entender o tipo e as regras que operam sobre ele como um único conjunto. Uma separação parcial que coloca apenas o tipo na pasta de domínio e envia as regras para utils pode parecer organizada por fora, mas continua anêmica.

Camada de transformação entre a resposta da API e o modelo de domínio

Há mais um ponto a considerar no trabalho real: a estrutura da resposta da API do backend nem sempre coincide com o modelo de domínio do frontend. Isso é ainda mais verdadeiro em um serviço tributário integrado a órgãos governamentais. Os dados de integração do Hometax, o serviço da Receita Nacional da Coreia, estão cheios de abreviações e códigos; dificilmente chegarão no mesmo formato do modelo de domínio do frontend.

É aí que entra uma camada de transformação (Mapper). Em vez de deixar o tipo da resposta da API fluir diretamente até o componente, primeiro o refinamos para o tipo do domínio e só então o utilizamos. Uma única função pura é suficiente.

import type { Income } from "../domain/tax";
 
interface HometaxIncomeResponse {
  총수입금액: number;
  경비율: number;
  소득유형코드: string;
  // ... 나머지 약어 필드들
}
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    총수입_금액: response.총수입금액,
    경비_비율: response.경비율,
  };
}

Assim, abreviações como 총수입금액 e 경비율 e classificações baseadas em códigos da resposta da API são transformadas em um só lugar para se adequar ao domínio do frontend. Valores como o código do tipo de renda, que precisam ser convertidos para enum, podem ser tratados com uma pequena lookup table dentro do mapper. Mesmo que o nome de um campo da API do Hometax mude, basta alterar um único mapper.

Funções utilitárias e lógica de domínio

Ao separar a lógica de domínio, surge inevitavelmente uma pergunta: "isto não é uma função utilitária?"

Observe as duas funções abaixo.

function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find((bracket) => taxableBase <= bracket.limit);
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrency é uma lógica pura de apresentação (Presentation) que transforma um número em string. Acrescentar a unidade "won" e separar milhares por vírgulas não é uma regra de negócio, mas uma questão de como apresentar o valor ao usuário. Já calculateTax contém uma regra de negócio baseada na legislação tributária: a aplicação de oito faixas progressivas. É uma regra do domínio que precisa continuar igual mesmo sem UI.

Este é o critério que uso no trabalho:

Se essa lógica desaparecer, o negócio quebra ou apenas a tela quebra?

Se o negócio quebra, é lógica de domínio; se apenas a tela quebra, é lógica de apresentação. Essa única pergunta permite distinguir a maioria das fronteiras.

Mas a realidade não é tão bem delimitada. O caso mais difícil é quando algo parece lógica de domínio, mas na verdade é lógica de apresentação.

Observe o código abaixo. Como recebe o conceito de domínio FilingStatus como argumento, ele foi classificado como lógica de domínio. Mas será que realmente é?

// domain/filing.ts
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: "gray",
    submitted: "blue",
    reviewing: "yellow",
    completed: "green",
    amended: "purple",
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: "작성 중",
    submitted: "제출 완료",
    reviewing: "검토 중",
    completed: "신고 완료",
    amended: "경정청구",
  };
  return labels[status];
}

Embora getStatusBadgeColor e getStatusDisplayText usem o conceito de domínio FilingStatus, o que fazem é apresentação de tela. Se a cor do badge mudar, o negócio não quebra de forma alguma. Colocar essas funções em domain/filing.ts faz o módulo de domínio crescer cada vez mais e mistura a verdadeira lógica de domínio com a lógica de apresentação.

Separando o modelo de domínio e o ViewModel

Há uma maneira prática de resolver esse problema: separar o ViewModel em outro arquivo dentro da mesma pasta de domínio. Em vez de .ui.ts, usar o nome .viewModel.ts cria uma conexão natural com o conceito de ViewModel do padrão MVVM. O próprio nome deixa evidente o papel de "camada que transforma os dados do domínio para a tela".

domains/
└── filing/
    ├── filing.ts              # 순수 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

Movemos getStatusBadgeColor e getStatusDisplayText, vistos anteriormente, diretamente para filing.viewModel.ts. Outras transformações, como getFilingTypeLabel(type: FilingType): string, que convertem o tipo de declaração em um rótulo em coreano, também ficam reunidas ali. filing.ts fica responsável apenas pelas regras de negócio; filing.viewModel.ts, apenas pela apresentação na tela.

O ponto central é a direção das dependências. filing.viewModel.ts importa filing.ts, mas filing.ts jamais importa filing.viewModel.ts. O domínio não conhece a apresentação; a apresentação conhece o domínio. Isso pode ser visto como uma versão em miniatura da regra de dependência (Dependency Rule) de Robert C. Martin.

Coloquei esses arquivos na mesma pasta porque acredito que arquivos que mudam juntos devem ficar no mesmo diretório. Se o tipo FilingStatus receber um novo valor (por exemplo, 'rejected'), tanto filing.ts quanto filing.viewModel.ts precisarão ser alterados. Como estão na mesma pasta, o escopo da mudança fica visível de imediato.

Fronteiras e coesão

Tão importante quanto separar a lógica de domínio é decidir onde traçar as fronteiras. A seguir, organizo alguns problemas de delimitação que encontro com frequência no trabalho.

Os dados tratados no frontend vêm, aproximadamente, de quatro fontes.

• Dados do servidor: recebidos como resposta da API
• Dados derivados: calculados a partir dos dados do servidor
• Estado da UI: usado para controlar a tela e as interações do usuário
• Entrada do usuário: dados que estão sendo preenchidos em um formulário

Misturar esses quatro tipos em um único tipo contamina o modelo de domínio.

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

Nesse tipo, conceitos do domínio, estado da UI e dados temporários estão todos no mesmo recipiente. Sempre que activeStep muda, é como se o domínio da declaração fosse atualizado. (A mudança de etapa de um formulário não é um evento de negócio.)

A solução é separar os tipos de acordo com suas fronteiras. O modelo de domínio contém apenas conceitos de negócio, como id, status e determinedTax; o estado da UI (FilingFormViewState) contém apenas controles da tela, como isExpanded e activeStep; e o estado do formulário (DeductionEditForm) contém apenas os dados temporários que estão sendo preenchidos.

Assim, cada tipo passa a ter um único motivo para mudar. O tipo de domínio só muda quando a legislação tributária muda; o estado da UI, apenas quando o design da tela muda; e o estado do formulário, apenas quando a UX de entrada muda.

Mantenha junto o que muda junto

No DDD de Eric Evans, existe o conceito de Aggregate (agregado): "tratar um cluster de objetos relacionados como uma única unidade". Não é necessário aplicar esse conceito literalmente no frontend, mas vale tomar emprestado seu princípio central: dados e regras que mudam juntos devem ficar juntos.

Em um serviço tributário, por exemplo, Income (renda) e ExpenseRate (coeficiente de despesas) sempre mudam juntos. Quando o tipo de renda muda, o coeficiente de despesas aplicável também muda, o que afeta o cálculo da renda global. Portanto, eles devem ficar coesos em um único arquivo, domain/tax.ts.

Já TaxFiling (declaração) pode mudar independentemente do cálculo do imposto. Mesmo que as regras de transição de estado da declaração mudem, a lógica de cálculo das alíquotas não é afetada. Portanto, o correto é separá-la em domain/filing.ts.

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

Class vs estilo funcional

Depois de chegar até aqui, pode surgir uma pergunta fundamental. Todos os exemplos até agora usaram a combinação de interface com funções puras; a coesão não seria mais natural se representássemos o domínio com Class?

Sim. Quando representamos o domínio com Class, dados e comportamento ficam reunidos em um único objeto, e a coesão aparece diretamente na estrutura do código.

class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === "draft";
  }
 
  canAmend(): boolean {
    return this.status === "completed" && this.filingType !== "amendment";
  }
 
  canSubmit(): boolean {
    return this.status === "draft" && this.determinedTax >= 0;
  }
}
 
const filing = new TaxFilingModel(
  "F-001",
  "completed",
  2025,
  "regular",
  547200,
);
 
filing.canAmend();

Quando usamos Class, o comportamento pertence aos dados. E o sujeito fica claro no ponto de uso. filing.canAmend() é intuitivo como a leitura de uma frase em linguagem natural. O sujeito (filing) e o verbo (canAmend) estão claramente combinados. É como escrever jihoon.eat('감자탕'): dá para ler imediatamente que "Jihoon come gamjatang".

No estilo funcional, por outro lado, fica assim.

canAmend(filing);
eat("jihoon", "감자탕");

No estilo funcional, os dados existem do lado de fora. Os dois códigos acima recebem os dados filing como argumento e executam uma operação. A função eat recebe os dados jihoon e 감자탕 como argumentos e é executada.

Com isso, a ligação entre sujeito e verbo fica mais frouxa. Para saber que a função canAmend está relacionada a TaxFiling, é necessário abrir o arquivo ou conferir a assinatura do tipo. Se funções como canAmend(filing), canEdit(filing) e calculateTax(taxableBase) estiverem misturadas no mesmo arquivo, pode ficar difícil perceber de imediato a qual domínio cada função pertence.

Então devemos usar Class?

Sinceramente, a resposta é "depende da situação". Mas, segundo minha experiência, há motivos práticos para Class não ser uma solução universal em ambientes React + TypeScript.

1. Atrito com o gerenciamento de estado do React

O gerenciamento de estado do React combina de forma mais natural com Plain Object. Tecnicamente, useState e useReducer podem conter qualquer valor, e o Redux DevTools não remove por si só o protótipo de uma instância de Class. Porém, quando o middleware de persistência de Redux/Zustand salva e restaura o estado como JSON, uma instância de Class perde seus métodos e seu protótipo no ciclo de JSON.stringify → JSON.parse e se degrada em plain object. A fronteira de props entre React Server Component e Client Component tem outra restrição: aceita apenas valores serializáveis (serializable) compatíveis, portanto uma instância arbitrária de Class não pode atravessá-la.

Observe o código abaixo.

const [filing, setFiling] = useState(
  new TaxFilingModel("F-001", "draft", 2025, "regular", 0),
);

Atualizar o estado do React, por si só, não faz filing deixar de ser uma instância de TaxFilingModel. Porém, se a persistência de Redux/Zustand o salvar e restaurar como JSON, o valor recuperado pode ser um plain object sem métodos, e uma chamada desatenta a filing.canAmend() pode provocar um erro em runtime. Ao transmiti-lo de React Server Component para Client Component, a falha acontece antes, porque uma instância de Class não é um valor serializável de props compatível.

2. Dificuldade de garantir imutabilidade

O React detecta mudanças de estado com base em igualdade referencial (referential equality). Se um método de uma instância de Class fizer uma mutação interna como this.items.push(...), a referência permanecerá a mesma e o React não disparará uma nova renderização. Por isso, no fim, é preciso escrever addDeduction(item) de modo que retorne uma nova instância toda vez, como em return new DeductionList([...this.items, item]); isso esvazia a vantagem da Class de oferecer uma "mudança de estado encapsulada". O código deixa de ser muito diferente de uma atualização funcional.

Estratégias para obter coesão no estilo funcional

Então, como melhorar no estilo funcional o problema da coesão frouxa visto em eat('jihoon', '감자탕')? Apresento três métodos que considero eficazes.

1. Obter coesão com namespace de módulo

É o método mais intuitivo. Transformamos o próprio arquivo (módulo) em uma unidade de domínio e usamos um namespace na importação. Basta usar diretamente o domain/filing.ts que definimos anteriormente.

import * as FilingModel from "../domain/filing";
 
FilingModel.canEdit(filing);
FilingModel.canAmend(filing);
FilingModel.canSubmit(filing);

FilingModel.canAmend(filing) não é tão conciso quanto filing.canAmend(), mas ao menos torna evidente no próprio código que a função pertence ao domínio de Filing. Também elimina o risco de misturar funções de vários domínios.

2. Padronizar o primeiro argumento como sujeito do domínio

Há outra convenção para expressar coesão no estilo funcional: o primeiro argumento é sempre o "sujeito da ação". Ao padronizar as assinaturas como canAmend(filing) e calculateTotalIncome(income), canAmend(filing) passa a ser lido como "perguntar canAmend sobre filing". Isso também se alinha à mentalidade de pipeline do Unix (data |> transform). Na verdade, o receiver de método da linguagem Go segue exatamente esse padrão, e, em um bloco impl do Rust, receber self como primeiro argumento parte da mesma ideia.

3. Agrupar comportamentos em uma função de criação de objeto de domínio (Factory)

Esse padrão pode ser usado quando sentimos falta da coesão de uma Class. Uma função Factory retorna de uma só vez o objeto de domínio e seus comportamentos.

export function createFilingModel(data: TaxFiling) {
  return {
    ...data,
    canEdit: () => data.status === "draft",
    canSubmit: () => data.status === "draft" && data.determinedTax >= 0,
    canAmend: () =>
      data.status === "completed" && data.filingType !== "amendment",
  } as const;
}
 
const filing = createFilingModel(rawFiling);
filing.canAmend();
filing.canEdit();

Esse padrão reúne a expressividade da Class (filing.canAmend()) e a praticidade de compor comportamentos com um objeto literal. Como o objeto retornado contém propriedades que são funções, ele não é, por si só, um dado serializável em JSON. Também há o custo de criar novos objetos de função a cada vez, mas isso raramente se torna um problema de desempenho no volume de dados tratado pelo frontend.

Até que ponto devemos separar?

Ao ler sobre Clean Architecture, encontramos uma estrutura ideal que divide três ou quatro camadas e define Port/Adapter. Mas aplicar essa estrutura a todos os projetos pode se tornar engenharia excessiva (over-engineering).

Estes são os critérios práticos que considero adequados.

• Separe o tipo do domínio do tipo da resposta da API. Seja com interface ou type, defina em um arquivo separado os conceitos do domínio usados pelo frontend.
• Retire do componente toda lógica que contenha regras de negócio. Ela não precisa estar em uma pasta domain/. O importante é transformá-la em uma função pura que não dependa do React.
• Faça a transformação resposta da API → modelo de domínio em um único lugar. Pode ser uma função Mapper ou um schema Zod; crie uma estrutura em que a mudança não se propague, pois basta alterar esse único ponto.

Se o projeto se tornar mais complexo, também vale considerar as situações abaixo.

• Divida as pastas por Bounded Context. O capítulo de frontend da Toss também enfatiza o princípio de "colocar no mesmo diretório os arquivos que mudam juntos". Quando as pastas são divididas por domínio, os caminhos de import revelam naturalmente as fronteiras do domínio.
• Introduza uma camada de Use Case. Quando a composição da lógica de domínio se torna complexa, passa a ser necessária uma camada Application que reúna em uma única função um cenário como "consultar informações de renda → aplicar o coeficiente de despesas → calcular os itens de dedução → apurar o imposto → confirmar a restituição".

src/
├── domains/
│   ├── tax/
│   │   ├── tax.ts                  # 세액 계산 도메인 (세율, 공제, 계산 파이프라인)
│   │   ├── tax.viewModel.ts        # 세액 표현 (금액 포맷, 구간 라벨)
│   │   ├── tax.test.ts             # 세액 계산 테스트
│   │   └── incomeMapper.ts         # 홈택스 API ↔ 도메인 변환
│   ├── filing/
│   │   ├── filing.ts               # 신고 상태 도메인 (상태 전이, 권한)
│   │   ├── filing.viewModel.ts     # 신고 표현 (상태 배지, 라벨)
│   │   ├── filing.test.ts
│   │   └── filingMapper.ts
│   └── deduction/
│       ├── deduction.ts            # 공제 항목 도메인 (자격 조건, 한도)
│       └── deduction.viewModel.ts
├── hooks/                           # React 의존 로직
├── components/                      # UI 컴포넌트
└── api/                             # API 호출

Mesmo dentro de um único domínio tributário, cálculo de imposto (tax), gestão de declarações (filing) e itens de dedução (deduction) são separados como subdomínios independentes. Uma mudança nas alíquotas não afeta a lógica de transição de estado das declarações; a adição de um item de dedução não altera o fluxo de envio da declaração. Essa é uma aplicação prática de Bounded Context.

Conclusão

Em resumo, domínio é a área do problema que queremos resolver; modelo de domínio é o sistema conceitual que abstrai seletivamente esse problema; modelo de objetos de domínio é a implementação desse sistema conceitual em código; e objeto de domínio é cada objeto individual dentro dessa implementação.

Colocar esses conceitos em prática no frontend não significa simplesmente dividir pastas, mas avaliar conscientemente várias camadas de fronteiras. "Isto é regra de negócio ou lógica de apresentação?" "Estes dados são estado do domínio ou estado da UI?" "Esta função tem coesão suficiente?" Só o hábito de fazer essas perguntas já melhora naturalmente a estrutura do código.

É claro que nem todo projeto precisa de todas as camadas da Clean Architecture. Dividir um aplicativo CRUD simples em quatro camadas e aplicar o padrão Factory a todos os domínios pode criar mais estrutura do que valor. Entre a coesão elegante da Class e a flexibilidade prática do estilo funcional, a resposta correta depende da complexidade do projeto e do contexto da equipe.

Não existe uma resposta única. Mas há uma diferença clara entre "escrever código sem saber o que é o domínio" e "reconhecer o domínio, avaliar suas fronteiras e separá-lo de forma consciente". Espero que este texto também incentive você a perguntar, ao menos uma vez, em seu próprio projeto: "qual é o domínio aqui, e onde este código deveria ficar?"

Referências

Como sempre tive interesse por revisão de código e refatoração, decidi encarar esse desafio da Toss, que tinha um formato bem interessante. A tarefa consistia em refatorar um aplicativo de reserva de salas de reunião fornecido pela organização. Como o projeto também vinha acompanhado de testes, havia uma rede de segurança para verificar se alguma funcionalidade havia sido quebrada durante a refatoração.

No fim, trabalhei na refatoração durante dois dias e quero registrar aqui o que percebi ao longo desse processo.

Meu primeiro contato com o código

A primeira coisa que fiz ao abrir o código foi ler as especificações dos testes. Afinal, os testes são a documentação que mostra com mais honestidade o que a aplicação deve fazer. Passei por App.easy.spec.tsx e App.hard.spec.tsx para entender os requisitos gerais da aplicação.

Em seguida, examinei o código em si e dois componentes monolíticos chamaram minha atenção.

• ReservationStatusPage era um componente com cerca de 400 linhas que reunia, em um único arquivo, seleção de data, visualização da timeline, tooltip com os detalhes da reserva, lista das minhas reservas e funcionalidade de cancelamento.
• RoomBookingPage era um componente com cerca de 300 linhas no qual filtros, lista de salas, lógica de criação de reservas e sincronização dos parâmetros da URL estavam todos entrelaçados.

Enquanto lia o código, antes mesmo de concluir que ele "precisava melhorar", concentrei-me em classificar suas características. A ideia era distinguir o que continha informações de domínio, o que tinha natureza utilitária e o que pertencia puramente à camada de UI.

// 도메인 정보: 장비 라벨, 타임 슬롯 등 비즈니스 상수
const EQUIPMENT_LABELS: Record<string, string> = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
};
 
// 유틸리티: 날짜 포맷, 시간 변환
function formatDate(date: Date): string { ... }
function timeToMinutes(time: string): number { ... }
 
// 서버 상태: 인라인 useQuery, useMutation 호출
const { data: rooms = [] } = useQuery(['rooms'], getRooms);
const { data: reservations = [] } = useQuery(['reservations', date], () => getReservations(date));
 
// UI + 비즈니스 로직 혼재: 필터링, 정렬, 충돌 감지가 JSX 사이에 산재

Depois dessa classificação, começou a ficar claro por onde eu deveria começar. Deixei comentários breves em cada área do código para anotar possíveis direções de melhoria. (A sensação era parecida com a que tive ao entrar na empresa atual e migrar um projeto baseado em jquery.)

Mas, afinal, por onde começar?

Definição da estratégia de refatoração

Planejei executar a refatoração na seguinte ordem:

1. Tratamento do código de servidor: separar query e mutation
2. Separação da lógica de domínio: modelos Equipment, Room e Reservation
3. Declaração de tipos: organizar o sistema de tipos com base nos modelos de domínio
4. Separação das funções utilitárias: formatação de data, cálculos da timeline etc.
5. Separação da camada de UI: dividir os componentes em unidades coerentes por responsabilidade
6. Abstração e separação de responsabilidades: tratamento de erro/carregamento e gerenciamento de query keys

Escolhi essa ordem para avançar de fora para dentro na direção das dependências. Primeiro, organizei a infraestrutura — código de servidor e utilitários —, depois estabeleci os modelos de domínio e, por fim, refinei a UI. Se eu separasse os componentes de UI antes, poderia acabar tendo de mover entre vários componentes uma lógica de domínio e um código de query que ainda não estavam organizados.

Com a estratégia definida, era hora de colocá-la em prática, etapa por etapa.

Começando pelo código de servidor e pelos utilitários

Extração do utilitário de exibição de data

Comecei pela função formatDate, pois ela estava definida inline, de forma idêntica, nas duas páginas.

// utils/formatYYYYMMDD.ts
export function formatYYYYMMDD(date: Date): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const date = String(date.getDate()).padStart(2, '0');
  return `${year}-${month}-${date}`;
}

Embora fosse uma mudança pequena, ela teve um significado importante como primeiro commit da refatoração. Foi uma espécie de aquecimento: começar pela parte mais independente e com menos efeitos colaterais para confirmar que os testes continuavam passando.

Extração dos hooks do React Query

Depois, extraí para arquivos separados as chamadas a useQuery e useMutation que estavam escritas diretamente dentro dos componentes. Usei o padrão queryOptions para transformar as configurações das queries em unidades reutilizáveis.

Nesse processo, também defini explicitamente os tipos das respostas da API que estavam em remotes.ts. Tipos que antes se propagavam como any passaram a ficar claros, como GetRoomsResponse e GetReservationsResponse.

Com a camada de infraestrutura organizada, voltei minha atenção para os modelos de domínio.

Separação dos modelos de domínio

O ponto de virada mais importante da refatoração foi separar os modelos de domínio em um diretório models/ próprio.

No código original, constantes de negócio como EQUIPMENT_LABELS e TIME_SLOTS estavam declaradas no topo dos arquivos de componentes. Os tipos de Room e Reservation também existiam apenas no handler do servidor (_tosslib/server/types.ts), enquanto no código do cliente eram usados praticamente como any.

// models/equipment.ts
export const EQUIPMENT_LABELS = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
} as const;
 
export type Equipment = keyof typeof EQUIPMENT_LABELS;
export const ALL_EQUIPMENT = Object.keys(EQUIPMENT_LABELS) as Equipment[];

// models/reservation.ts
export interface Room {
  id: string;
  name: string;
  floor: number;
  capacity: number;
  equipment: Equipment[];
}
 
export interface Reservation {
  id: string;
  roomId: string;
  date: string;
  start: string;
  end: string;
  attendees: number;
  equipment: Equipment[];
}

Por que separar os modelos de domínio é tão importante? Quando a lógica de negócio depende de um componente de UI, qualquer alteração nessa lógica exige que se examine também a lógica de renderização do componente. Quando ela existe de forma independente no diretório models/, porém, as regras de negócio podem mudar separadamente da UI. É claro que, na prática, uma separação perfeita é difícil, mas o essencial é ao menos criar uma estrutura na qual seja possível prever que "essa lógica estará aqui".

Com os modelos de domínio separados, até que ponto a UI poderia ficar mais leve?

Decomposição dos componentes

ReservationStatusPage

Esse foi o commit que produziu a mudança mais drástica e também o que mais consumiu tempo. Dividi o componente monolítico de 385 linhas da seguinte forma:

ReservationStatusPage/
├── index.tsx                    # 페이지 레벨
└── components/
    ├── DateSelector.tsx         # 날짜 선택 UI
    ├── ReservationTimeline.tsx  # 타임라인
    └── MyReservation.tsx        # 내 예약 목록 + 취소

O critério para a separação foi: "este código tem significado por si só?" A visualização da timeline é uma responsabilidade independente, que recebe os dados das reservas de uma data e desenha uma grade. A lista das minhas reservas é outra responsabilidade independente, que consulta os dados de reserva do usuário e permite cancelá-las. Não havia motivo para que ambas ficassem no mesmo arquivo.

Depois da separação, index.tsx passou a exercer apenas o papel de orquestrador (orchestrator). Ele ficou responsável pelo gerenciamento de estado, pela exibição de mensagens e pela composição dos componentes filhos, enquanto o fetching de dados e os detalhes de renderização foram delegados a esses componentes.

RoomBookingPage

Separei a página de reservas seguindo o mesmo princípio.

RoomBookingPage/
├── index.tsx                    # 페이지 레벨
├── components/
│   ├── BookingFilter.tsx        # 날짜, 시간, 인원, 장비, 층 UI
│   └── AvailableRoomList.tsx    # 예약 가능 방 목록
└── hooks/
    └── useBookingParams.ts      # URL searchParams 기반 상태 관리

Durante esse processo, fiz uma escolha interessante. No início, tentei introduzir react-hook-form + zod para validar o formulário. No fim, porém, removi essa abordagem e a substituí pelo hook customizado useBookingParams. Falarei dessa decisão em mais detalhes adiante.

Neste ponto, surge naturalmente uma pergunta: até onde devemos abstrair?

O nível adequado de abstração

Esta foi a questão sobre a qual mais refleti durante o simulado.

Até onde devemos decompor condicionais aninhadas?

A lógica que determina se uma sala está disponível para reserva combina várias condições: se a capacidade é suficiente, se há os equipamentos necessários, se o andar preferido corresponde e se os horários não se sobrepõem. No código original, todas essas condições estavam escritas inline dentro de um único callback de filter.

Ao extrair essa lógica para models/roomFilter.ts, separei cada condição em uma função com nome próprio.

const isEnoughCapacity = (room: Room, attendees: number) => room.capacity >= attendees;
const hasRequiredEquipment = (room: Room, equipment: Equipment[]) =>
  equipment.every(eq => room.equipment.includes(eq));
const isOnPreferredFloor = (room: Room, floor: number | null) =>
  floor === null || room.floor === floor;
const hasNoTimeConflict = (room: Room, reservations: Reservation[], date: string, start: string, end: string) =>
  !reservations.some(reservation => reservation.roomId === room.id && reservation.date === date && reservation.start < end && reservation.end > start);
 
export function filterAvailableRooms(rooms: Room[], reservations: Reservation[], params: Params): Room[] {
  return rooms
    .filter(room =>
      isEnoughCapacity(room, params.attendees) &&
      hasRequiredEquipment(room, params.equipment) &&
      isOnPreferredFloor(room, params.floor) &&
      hasNoTimeConflict(room, reservations, params.date, params.startTime, params.endTime)
    )
    .sort((a, b) => {
      if (a.floor !== b.floor) return a.floor - b.floor;
      return a.name.localeCompare(b.name);
    });
}

O ponto central aqui é que só extraí uma função quando havia um nome claro para a abstração. Nomes como isEnoughCapacity e hasRequiredEquipment permitem prever o comportamento sem olhar a implementação. Se o nome inevitavelmente ficasse vago, como processRoomConditions, a abstração poderia, na verdade, aumentar a carga cognitiva de quem lê.

Isso não significa, é claro, que essa seja a única resposta correta. Meu critério foi: "é possível prever o comportamento apenas pelo nome da função?" Se sim, vale abstrair; caso contrário, manter inline pode até favorecer a legibilidade.

searchParams vs. estado do formulário

Também pensei bastante sobre onde manter o estado dos filtros da reserva. No código original, cada valor de filtro era gerenciado com useState e sincronizado com os searchParams da URL por meio de useEffect.

// 원본: useState + useEffect 동기화 방식
const [date, setDate] = useState(searchParams.get('date') || formatDate(new Date()));
const [startTime, setStartTime] = useState(searchParams.get('startTime') || '');
 
// ... 6개의 개별 상태
useEffect(() => {
  const params: Record<string, string> = {};
  if (date) params.date = date;
 
  // ... 모든 상태를 searchParams에 동기화
  setSearchParams(params, { replace: true });
}, [date, startTime, endTime, ...]);

Primeiro, tentei introduzir react-hook-form + zod para gerenciar os filtros como um formulário. No fim, porém, removi essa solução e a substituí pelo hook useBookingParams, que usa os searchParams como única fonte da verdade (Single Source of Truth).

// useBookingParams: searchParams가 곧 상태
export function useBookingParams() {
  const [searchParams, setSearchParams] = useSearchParams();
 
  const params = useMemo<BookingParams>(() => ({
    date: searchParams.get('date') || formatYYYYMMDD(new Date()),
    startTime: searchParams.get('startTime') || '',
    // ...
  }), [searchParams]);
 
  const updateParam = useCallback(<K extends keyof BookingParams>(key: K, value: BookingParams[K]) => {
    setSearchParams(prev => {
      // 기존 파라미터 병합 후 업데이트
      return result;
    }, { replace: true });
  }, [setSearchParams]);
 
  return { params, updateParam };
}

A principal razão para essa decisão foi a conclusão de que "não fazia sentido que os estados evoluíssem separadamente". Quando useState e searchParams mantêm estados próprios, podem surgir divergências dependendo do momento da sincronização. Quando apenas os searchParams são usados como estado, por outro lado, a URL passa a ser o próprio estado da aplicação e o problema de sincronização simplesmente desaparece. De quebra, se o usuário compartilhar a URL, o mesmo estado dos filtros será reproduzido.

Encontrei reflexões parecidas nos relatos de outros participantes: "unifiquei os searchParams da URL como única fonte da verdade" e "optei por reunir as props individuais dos filtros em um único objeto filter". As formas de expressar a solução variavam, mas a percepção do problema era a mesma: "estados dispersos precisam ser reunidos em um único conceito".

Estabilidade

Suspense e ErrorBoundary

Depois de definir a estrutura dos componentes, adicionei o tratamento de erro e carregamento. A ordem é importante porque só é possível decidir onde estabelecer cada boundary depois que a árvore de componentes está definida.

Usando a biblioteca react-error-boundary, envolvi cada unidade independente de fetching de dados com ErrorBoundary e Suspense. Isso porque, mesmo se a timeline falhar, a lista das minhas reservas deve continuar aparecendo normalmente — e vice-versa.

{/* 각 영역이 독립적으로 에러/로딩을 처리 */}
<ErrorBoundary FallbackComponent={ErrorFallback} resetKeys={[date]}>
  <Suspense fallback={<Loading message="예약 현황을 불러오는 중..." />}>
    <ReservationTimeline date={date} />
  </Suspense>
</ErrorBoundary>
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Suspense fallback={<Loading message="내 예약을 불러오는 중..." />}>
    <MyReservation onCancel={handleCancel} />
  </Suspense>
</ErrorBoundary>

Gerenciamento centralizado de Query Keys

À medida que os hooks de query eram separados durante a refatoração, surgiu o problema de as query keys ficarem espalhadas por vários arquivos. Com isso, ficou difícil rastrear qual key deveria ser usada para invalidation no onSuccess de uma mutation.

Introduzi @lukemorales/query-key-factory para centralizar o gerenciamento das query keys.

// queries/queryKeys.ts
export const roomKeys = createQueryKeys('rooms', {
  list: { queryKey: null, queryFn: () => remotes.getRooms() },
});
 
export const reservationKeys = createQueryKeys('reservations', {
  list: (date: string) => ({ queryKey: [date], queryFn: () => remotes.getReservations(date) }),
  my: { queryKey: null, queryFn: () => remotes.getMyReservations() },
});

Assim, é possível usar a forma useSuspenseQueries({ queries: [roomKeys.list, reservationKeys.list(date)] }), mantendo a query key e a função de fetching sempre juntas. Também extraí os caminhos das routes para a constante PATHS, eliminando strings hardcoded.

Qual era a intenção dos autores do desafio?

Depois de concluir a refatoração, dei um passo atrás e me perguntei: o que este simulado pretendia avaliar?

Ao ler os relatos de outros participantes, encontrei um ponto em comum interessante. Em quase todos aparecia a frase: "código não é lido, é previsto". Nosso cérebro não interpreta o código linha por linha; ele o lê fazendo previsões com base nos padrões acumulados pela experiência. Quando essas previsões falham, a carga cognitiva aumenta de forma abrupta.

Sob essa perspectiva, o simulado não avaliava apenas a capacidade de programar, mas uma competência de colaboração: "até que ponto você consegue tornar o código previsível para seus colegas?". (Talvez a verdadeira competência de um engenheiro de software seja justamente ler a mente dos autores do desafio e dos colegas.)

Ao examinar os relatos de outros participantes, identifiquei-me com observações como "não é fácil entender o código escrito por outra pessoa" e "projetar a interface primeiro é importante, mas essa abordagem pode vacilar diante de uma base de código extensa". Passei por algo parecido. Quando o código existente já funciona, surge a tentação de racionalizar sua estrutura: "se já está funcionando, para que mexer?". Mas o ponto central do simulado era justamente superar essa tentação e avaliar "com que rapidez outra pessoa, que não eu, conseguiria entender este código e se eu seria capaz de julgar o problema com meu próprio raciocínio e avançar até resolvê-lo".

O que aprendi com a refatoração

A ordem da refatoração determina o resultado. Avançar de fora — infraestrutura — para dentro — UI — foi um caminho seguro, que evitou emaranhados no meio do processo. Ao separar os componentes depois de organizar os utilitários e os modelos de domínio, ficou claro de que cada componente dependia.

O critério para uma abstração é seu "nome". Se, ao extrair algo para uma função ou variável, o nome consegue explicar o comportamento, vale a pena abstrair. Se o nome inevitavelmente for vago, manter inline pode ser uma escolha melhor.

A localização do estado é a própria arquitetura. Estados que precisam se mover juntos devem ficar no mesmo lugar. Em vez de sincronizar useState e searchParams, usar apenas os searchParams como fonte da verdade produz uma estrutura mais saudável.

Conclusão

Depois de terminar a tarefa, conversei com dois colegas. Coisas que eu não percebia ao examinar o código sozinho começaram a aparecer quando desenvolvemos nossas ideias em conjunto. No instante em que alguém pergunta "por que você fez assim?" sobre uma escolha estrutural que eu havia considerado óbvia, tornam-se visíveis as lacunas de raciocínio das quais eu nem sequer tinha me dado conta.

É verdade que a IA está reduzindo drasticamente o tempo necessário para escrever e revisar código. Ainda assim, experiências como essa explicam por que considero code reviews e reuniões diárias tão importantes. A IA pode verificar a consistência do código, mas apontar "esta é a perspectiva que você deixou passar" continua sendo papel de colegas que compartilham o mesmo contexto. Descobrir o que eu não consegui enxergar e, a partir dessa descoberta, estabilizar o produto: talvez essa seja a essência da colaboração.

Não existe uma resposta única para escrever código durante o processo de resolução de um problema. Outros participantes do mesmo simulado seguiram caminhos diferentes, cada um com suas próprias razões. O importante é conseguir explicar "por que foi feito assim". Recomendo que os leitores deste texto também tentem olhar para o próprio código pelos olhos de quem o vê pela primeira vez. Essa perspectiva pode ser o critério mais poderoso para determinar a qualidade do código.

Um dos textos que mais me marcaram no início da carreira foi “Plano de carreira para engenheiros frontend: três trilhas de especialização para profissionais juniores”, de Hwidong Bae. O artigo organiza a carreira de engenharia frontend em três trilhas — especialização em web (Software Engineer) / especialização em produto (Product Engineer) / especialização em operações (Full-Stack Engineer) — e ainda aborda as “cinco competências fundamentais de um engenheiro excepcional” e os “três pontos para se tornar sênior”. Naquela época, a grande questão era decidir quais competências desenvolver em cada trilha. Mas, menos de dois anos depois de eu ler o texto, a própria questão mudou por completo.

Hoje, quando converso com colegas de engenharia, percebo que as preocupações têm um tom um pouco diferente das que eu vinha ouvindo nos últimos anos.

• “A empresa adotou IA e, quando entregamos um layout, ela faz quase tudo. É prático, mas...”
• “O mercado de contratação está muito frio.”
• “Dá medo de simplesmente fazer merge do código escrito pela IA, mas revisar tudo um por um reduz a eficiência. Não sei bem como equilibrar isso.”

Passei — e ainda passo — por uma fase parecida. Há apenas um ou dois anos, eu via a IA como “uma boa ferramenta de apoio”; hoje, chegamos a um ambiente em que é difícil até imaginar desenvolver sem ela (inclusive pedi ao Claude que fizesse pesquisas enquanto escrevia este texto). Este artigo funciona como uma espécie de continuação do texto de Hwidong Bae: quero organizar, do meu ponto de vista, como o cenário mudou nesse intervalo e quais outras competências precisamos desenvolver como engenheiros frontend diante dessa nova realidade.

Mais uma vez, procurei consultar e verificar o máximo possível de fontes. Ainda assim, como esta é uma área que muda muito rápido, peço desde já a compreensão de vocês caso parte do conteúdo já esteja desatualizada quando este texto for publicado. Se houver contrapontos ou assuntos que mereçam debate, fiquem à vontade para deixar um comentário.

“Agora a IA não faz tudo?”

Antes de tudo, precisamos esclarecer uma coisa. A frase “a IA faz tudo” é verdadeira? Até que ponto ela é verdade e a partir de onde passa a ser fantasia?

Em fevereiro de 2025, Andrej Karpathy, cofundador da OpenAI e ex-diretor de IA da Tesla, publicou a seguinte frase no Twitter:

Existe um novo tipo de programação que chamo de “vibe coding”: você se entrega completamente à vibe, abraça o crescimento exponencial e esquece até que o código existe.

There's a new kind of coding I call 'vibe coding', where you fully give in to the vibes, embrace exponentials, and forget that the code even exists.

Em poucas palavras, vibe coding é “uma forma de programar em que você entrega o teclado à IA e apenas descreve, em linguagem natural, o que deseja”. Não há documentação de arquitetura, boilerplate nem busca por ponto e vírgula. O código simplesmente funciona na vibe. Em menos de um ano, o termo entrou no vocabulário corrente das comunidades de desenvolvimento de língua inglesa.

Exatamente um ano depois, em fevereiro de 2026, o mesmo Karpathy recuou um pouco. Ele propôs substituir o termo vibe coding por “agentic engineering”. A diferença entre os dois é clara.

• Vibe coding: descrever o que se deseja e aceitar o resultado
• Agentic engineering: projetar o sistema, especificar as restrições e usar a IA para acelerar uma implementação cujo raciocínio já foi concluído mentalmente

Se, um ano atrás, a premissa era “é só pedir que ela faz tudo”, agora “a capacidade de planejar o que pedir à IA e como pedir” se consolidou como uma competência de engenharia. E essa tendência não se resume ao tweet de uma única pessoa. Na mesma época, o engenheiro do Google Addy Osmani publicou o livro Beyond Vibe Coding: From Coder to AI-Era Developer, afirmando categoricamente: “A IA é apenas uma assistente, não uma programadora em quem se possa confiar de forma autônoma. Você é o desenvolvedor sênior, e o LLM existe para acelerar o seu julgamento.”

As ferramentas estão avançando sem freio

O ecossistema de ferramentas também evolui rapidamente para acompanhar essa tendência. Em maio de 2026, as ferramentas de programação mais mencionadas são Cursor, Claude Code, GitHub Copilot, Windsurf, v0 by Vercel, Bolt.new e Devin.

A transformação do v0 é especialmente emblemática. A Vercel usa a expressão “90% problem”, que significa que 90% do desenvolvimento no mundo real acontece dentro de bases de código e infraestruturas existentes. No início, bastava ao v0 criar bons protótipos greenfield; agora, ele importa diretamente repositórios do GitHub para trabalhar, impõe o uso do design system e obtém automaticamente as variáveis de ambiente de implantação. É a resposta direta do ecossistema de ferramentas ao contraponto dos profissionais seniores: “A IA não serve apenas para criar demos que parecem brinquedos?”

As bases de código das big techs são a melhor demonstração dessa mudança.

Sundar Pichai, do Google, anunciou na teleconferência de resultados do terceiro trimestre, em outubro de 2024, que “mais de 25% do código novo era gerado por IA e depois revisado e aprovado por engenheiros”; em abril de 2025, afirmou que a proporção havia superado 30%. Satya Nadella, da Microsoft, revelou na LlamaCon, em abril de 2025, que “até 30% do nosso código é escrito por IA”. Na Meta, a meta interna chegou ao ponto de “até o primeiro semestre de 2026, 65% dos engenheiros gerarem com IA pelo menos 75% dos próprios commits”.

Na Coreia do Sul, a tendência não é diferente. A Toss criou um sistema de documentação baseado em IA para melhorar a DX e eliminar a necessidade de desenvolvedores procurarem documentos, e foi além ao abordar temas como “O que aconteceu quando eliminamos os designers na era da IA”. A Danggeun compartilha experimentos de cada equipe toda terça-feira no AI Show & Tell e passou a usar o slogan de recrutamento “de engenheiro a builder”. Já a Woowa Brothers vem publicando textos como “Na era em que a IA escreve código, você ainda quer ser desenvolvedor?”, com a mensagem de que “a essência do trabalho de desenvolvimento não está no código, mas na capacidade de definir e resolver problemas”.

Mas os números contam uma história um pouco diferente

Vendo apenas isso, é fácil chegar à conclusão de que “agora basta pedir que tudo fica pronto”. Mas os dados reais contam uma história um pouco diferente.

Comecemos pelos números da 2025 Stack Overflow Developer Survey, uma análise abrangente do estado do desenvolvimento de software.

• 84% dos desenvolvedores disseram que usam ou pretendem usar ferramentas de IA. (Um aumento em relação aos 76% de 2024.)
• Entre os desenvolvedores profissionais, 51% usam ferramentas de IA todos os dias.
• No entanto, a percepção positiva sobre as ferramentas de IA caiu. Depois de superar 70% em 2023 e 2024, chegou a 60% em 2025.
• Desenvolvedores seniores com mais de dez anos de experiência são os que menos confiam nos resultados produzidos por IA.

Em resumo: “Todo mundo usa, mas confia cada vez menos.”

Um experimento realizado em 2025 pela organização sem fins lucrativos METR evidencia de forma ainda mais dramática a distância entre essa percepção e a realidade. Foi um experimento controlado com 16 desenvolvedores open source experientes — em média, cinco anos de experiência e 1.500 commits —, aos quais foram atribuídas 246 tarefas, com a permissão para usar IA definida aleatoriamente. Os resultados foram os seguintes.

• Antes de começar, os desenvolvedores previram que “seriam 24% mais rápidos usando IA”.
• Logo após concluir as tarefas, ainda avaliaram que “parecia ter sido cerca de 20% mais rápido”.
• Mas a medição real mostrou que eles ficaram 19% mais lentos.

As causas apontadas pelos pesquisadores são interessantes. A taxa de aceitação do código gerado pela IA ficou abaixo de 44%; mesmo o código rejeitado exigiu tempo de revisão e testes; e até o código aceito demandou um tempo considerável de revisão e ajustes. Essa ilusão de ter ficado mais rápido mesmo ficando mais lento — essa lacuna — é uma das razões pelas quais desenvolvedores seniores têm se tornado cada vez mais céticos em relação à IA.

Além disso, a própria “qualidade do código escrito pela IA” está longe de ser impecável. Vejamos o experimento da Veracode, que pediu a mais de cem modelos de IA que escrevessem código.

• 45% do código gerado por IA continha vulnerabilidades do OWASP Top 10.
• A taxa de falha na proteção contra XSS (cross-site scripting) foi de 86%.
• A taxa de falha na proteção contra injeção de logs (Log Injection) foi de 88%.
• Outro estudo relatou que a densidade de vulnerabilidades do código de IA era 2,7 vezes maior que a do código humano.

Em particular, a taxa de 86% de falha em XSS — um tema diretamente ligado ao frontend — merece ser levada ainda mais a sério. Esse número mostra bem o que significa fazer merge, sem alterações, de um form input escrito pela IA. (Quem tem experiência com auditoria de segurança de frontend já se sente desconfortável e preocupado até ao escrever dangerouslySetInnerHTML com as próprias mãos; quando a IA o insere discretamente, parece ainda mais assustador.)

Os sinais são semelhantes quanto à qualidade. A GitClear analisou 211 milhões de linhas alteradas entre 2020 e 2024 e chegou aos seguintes resultados.

• Proporção de código revertido em até duas semanas após ser escrito (Code Churn): 5,5% em 2020 → 7,9% em 2024
• Proporção correspondente a refatoração: 25% em 2021 → menos de 10% em 2024
• Proporção de copiar e colar (clones): 8,3% em 2021 → 12,3% em 2024 (em 2025, houve um aumento de nada menos que quatro vezes)

A interpretação não é tão difícil. A capacidade de produzir código rapidamente aumentou, mas a capacidade de escrever código que valha a pena aprimorar diminuiu. Os dados da Apiiro, baseados em empresas da Fortune 50, são ainda mais contundentes. Desenvolvedores que usam assistência de IA produzem de três a quatro vezes mais commits que seus colegas, mas também geram dez vezes mais findings de segurança. Os caminhos de escalada de privilégios (privilege escalation) dispararam 322%, e as falhas de projeto arquitetural, 153%.

O que a IA substituiu e o que não conseguiu substituir

As ferramentas avançam sem freio, mas os números são ambíguos. Então, o que exatamente a IA substituiu e o que ainda não conseguiu substituir? Só com essa distinção clara conseguimos enxergar onde devemos investir nosso tempo.

O que foi substituído foi parte do trabalho de digitação manual dos desenvolvedores. Há menos situações em que precisamos escrever boilerplate ou código repetitivo; com apenas um layout, uma tela que respeita as convenções pode ficar pronta em poucos minutos; e tanto o tempo gasto pesquisando sintaxe e APIs quanto a curva de aprendizado caíram drasticamente. Em suma, a IA nivelou a “velocidade de produção”.

Mas, no campo do “julgamento”, ela ainda não nos substituiu. (Para ser mais preciso, seria melhor dizer que “ainda não correspondeu às expectativas”. Embora a capacidade de usar IA varie de pessoa para pessoa, aqui parto da experiência média de uso.)

O primeiro obstáculo é traduzir requisitos em especificações. Transformar necessidades de negócio ambíguas em casos de borda precisos e máquinas de estado ainda exige uma intervenção humana mais profunda. O mesmo vale para compreender impactos no sistema como um todo: mesmo quando a IA oferece respostas plausíveis para perguntas como o impacto de um componente no bundle, se uma dependência permite tree shaking ou como um padrão de data fetching afeta, nos Core Web Vitals, a pontuação de INP (Interaction to Next Paint), só ficamos tranquilos depois que uma pessoa confere mais uma vez.

Também não podemos deixar de lado segurança e avaliação de riscos, como mostra o problema dos 45% de vulnerabilidades do OWASP visto acima. O mesmo se aplica à manutenção do design system e da consistência, que exige verificar se um novo componente está alinhado aos tokens, às regras de acessibilidade e aos padrões de interação do sistema existente, e à compreensão do contexto do cliente e do mercado, que demanda perguntar por que uma funcionalidade é necessária e em qual fluxo do usuário ela deve ser inserida.

Por fim, tomando emprestada a expressão usada no texto de yceffort, se chamarmos de “diferença entre a complexidade do sistema e o grau em que a equipe o compreende”, a gestão da dívida cognitiva (Cognitive Debt) é uma área em que essa distância se amplia ainda mais rapidamente após a adoção da IA. Portanto, reduzir essa lacuna continua sendo responsabilidade das pessoas.

Não são os desenvolvedores que desaparecem, mas a forma do trabalho que eles faziam. O gargalo passou da “velocidade de criação” para a “velocidade de decisão”.

No mesmo contexto, “Os desenvolvedores serão substituídos pela IA?”, da Toss, oferece um diagnóstico mais contundente. A ideia central é a seguinte: a IA não está substituindo toda a força de trabalho; está eliminando a escada de aprendizagem (apprenticeship ladder). Daqui a dez ou vinte anos, quando os atuais profissionais seniores se aposentarem, faltarão pessoas da próxima geração capazes de projetar sistemas complexos. Não é um problema da ordem de “o que faremos com as contratações da nossa empresa no ano que vem?”, mas uma espécie de bomba-relógio com efeito retardado para todo o setor. (Acho que é um texto realmente bem escrito para um período de tantas incertezas.)

A “primeira versão que funciona” criada pela IA corresponde a 70%. Os 30% necessários para chegar a uma “versão que pode ser entregue a usuários reais” são território humano. E a capacidade de preencher esses 30% não surge da noite para o dia. Essa é a essência do problema da escada de aprendizagem. Se desaparece o tempo de “pôr a mão na massa” escrevendo boilerplate e componentes simples, também desaparecem as pessoas capazes de completar esses 30%.

O texto original de Hwidong Bae apontava como “cinco competências fundamentais de um engenheiro excepcional” a escrita de bom código, a maximização do valor atual (equilibrando rapidez de lançamento e manutenção de longo prazo), a tomada de decisões baseada em dados, o apoio eficaz às decisões dos colegas e o aprendizado contínuo. Todas as cinco continuam válidas na era da IA, mas a última delas ocupa a posição mais vulnerável. O aprendizado em si não desapareceu; o objeto do aprendizado mudou. Antes, aprendíamos “como usar esta ferramenta”; agora, precisamos dedicar tempo a aprender “como este sistema inteiro funciona”. Mais assustador ainda é o problema apontado por Evan Moon: “no momento em que a IA assume a escrita do código, a carga cognitiva do cérebro cai drasticamente”. Reduzir a carga cognitiva parece bom, mas é perigoso porque essa carga era justamente a matéria-prima do aprendizado. Quanto mais cômodo, menos se cresce.

Daí surge naturalmente uma pergunta. Então as três trilhas do texto de Hwidong Bae — especialização em web, produto e operações — deixaram de fazer sentido?

Penso diferente. As trilhas continuam válidas. O mais correto é entender que cada uma evoluiu um estágio para se adaptar à era da IA. Vejamos como o cenário mudou em cada uma delas.

De produtor a “validador”

No texto original de Hwidong Bae, a trilha de especialização em web era agrupada sob o nome Software Engineer. Seus pontos centrais eram “uma compreensão profunda e o domínio da internet, dos navegadores e de HTML/CSS/JS”, o conhecimento dos pontos fortes e fracos das ferramentas do ecossistema web, a experiência com troubleshooting e uma postura atenta a novas tecnologias. Como caminhos para chegar a sênior, o texto sugeria engenheiro de empresas que desenvolvem ferramentas para o ecossistema web / educador de frontend / tech lead em organizações com produtos complexos. Em poucas palavras, são “pessoas que investigam a fundo os princípios de funcionamento dos navegadores e de HTML/CSS/JS”; até um ou dois anos atrás, sua principal arma era “ser capaz de escrever código com mais precisão que qualquer outra pessoa”.

Como o valor dessas pessoas mudou na era da IA? Em termos apenas de velocidade para escrever código, a IA já as alcançou. Porém, “a capacidade de avaliar com precisão o código escrito pela IA” é algo que elas praticamente monopolizam.

• Pessoa sem formação técnica que usa IA: a implementação atende aos meus requisitos e funciona normalmente.
• Desenvolvedor que usa IA: funciona, mas esta dependência pode causar certos problemas, e melhorar este padrão desta maneira está mais de acordo com as convenções. Vamos rever as partes relacionadas.

No estudo da Veracode abordado acima, vimos taxas de falha de 86% em XSS e 88% em injeção de logs. As pessoas capazes de identificar e corrigir esses problemas são justamente especialistas como nós. Elas evoluem naturalmente para uma função sênior de controle de qualidade (QA) dos resultados produzidos pela IA.

Além disso, surgiu um tema inteiramente novo no território desses especialistas: UI generativa (Generative UI) e design de interfaces de IA. Alguns exemplos são interfaces de chat que exibem respostas do LLM por streaming, controles de abort para interromper a geração, renderização progressiva de Markdown e blocos de código, UX que exibe inline os resultados de chamadas de ferramentas e integrações de assistentes por meio do Vercel AI SDK ou do MCP (Model Context Protocol). A demanda por “pessoas que conhecem com precisão os princípios de funcionamento da web e, ao mesmo tempo, entendem as características dos LLMs e sabem aplicá-las” está explodindo nessa área.

A evolução natural para Product Engineer

A trilha de especialização em produto foi a mais beneficiada. Quem conhece profundamente o mercado e os clientes e se comunica com frequência com stakeholders externos ganhou uma ferramenta muito mais poderosa ao incorporar a IA. Outra característica dessa trilha era a possibilidade de expandir a carreira para outras funções, com caminhos seniores como engenheiro de growth ou consultor / transição para PM, PO ou CPO.

Uma mudança interessante é que o nome dessa trilha começou a se consolidar como padrão global. O texto original já a chamava de “Product Engineer”, mas, quando o li, a expressão ainda me parecia pouco familiar. Um ano depois, ela se estabeleceu a ponto de a Vercel substituir “Fullstack Engineer” por “Product Engineer” em todas as descrições de cargo.

Lee Robinson aponta três qualidades essenciais de um Product Engineer.

• Foco em iteração (Iteration): percorre rapidamente o ciclo de implantação → feedback → ajuste.
• Centralidade no cliente: conversa diretamente com clientes para melhorar o produto.
• Pragmatismo: “toda escolha tecnológica é apenas um meio”. Ferramentas que não contribuem para o objetivo do produto são abandonadas sem hesitação.

Há uma armadilha aqui: é perigoso enxergar o engenheiro especializado em produto apenas como “quem faz rápido”. Com a chegada da IA, esse risco aumentou. Afinal, “implementar funcionalidades rapidamente” agora é algo que profissionais de qualquer área podem fazer com ferramentas de IA. O diferencial de um Product Engineer está na “capacidade de definir com precisão o problema do cliente e validá-lo rapidamente com a menor solução possível”, não em “ser rápido com as mãos”.

Nesse movimento, Design Engineer começou a ganhar status de cargo formal. A Vercel está contratando engenheiros de design em uma trilha oficial com salários acima de US$ 200 mil, e Linear e Stripe avançam em uma direção semelhante. É uma função que elimina o próprio handoff entre frontend e design. Como a IA desenha rapidamente, as competências necessárias para lidar ao mesmo tempo com “o que desenhar” e “se o resultado está de acordo com um design system consistente” ficaram ainda mais escassas.

Orquestrador de IA

A trilha de especialização em operações é a que passa pela transformação mais drástica. No texto original, Hwidong Bae a classificava como Full-Stack Engineer e a definia como “uma pessoa muito interessada em estrutura, integração, testes e implantação de projetos, capaz de lidar diretamente com APIs e infraestrutura simples, preencher lacunas na organização e melhorar processos”. Nos últimos um ou dois anos, a função de operar os próprios agentes de IA foi acrescentada a essa base, ampliando rapidamente o alcance da trilha.

Ao resumir as tendências de 2026, ele apontou o conceito de “orquestração de agentes de programação (Orchestrating Coding Agents)” como um dos pontos centrais. Isso significa ir além de dar ordens a uma única IA: trata-se de projetar e operar um sistema em que vários agentes de IA colaboram simultaneamente. No mesmo contexto, ele propôs um framework chamado “agent-skills”, e também vem ganhando espaço a ideia de codificar diretamente na lógica de funcionamento dos agentes os workflows profissionais, quality gates e melhores práticas do setor.

Depois de reunir materiais relacionados, estes são, na minha visão, os novos termos com que engenheiros da trilha de operações precisarão lidar.

• MCP (Model Context Protocol): padrão proposto pela Anthropic para conectar LLMs a ferramentas externas
• Governança de IA: gestão de quem pode usar IA, com qual contexto, e garantia de que secrets não sejam expostos
• Avaliação de agentes (Evaluation): pipeline que pontua automaticamente os resultados produzidos pelos agentes
• Gate de IA: validação automática de segurança e qualidade antes do merge de um PR e rotulagem de código de IA

O texto original indicava como caminhos seniores dessa trilha cargos como engenheiro de equipe de plataforma em grandes organizações / tech lead / agile coach / technical program manager (TPM) / CTO. Esses caminhos continuam válidos, mas agora podemos acrescentar novas posições, como “líder de infraestrutura de desenvolvimento com IA” e “engenheiro de produtividade de desenvolvimento (DevProd)”.

Enquanto as três trilhas evoluem cada uma à sua maneira, há competências que se tornaram mais importantes em todas elas. Eu queria pensar inicialmente em um horizonte de cinco anos, mas, diante do ritmo atual de avanço, até a unidade de um ano parece longa demais. Por isso, vou limitar o horizonte a algo como “o próximo ano” e destacar as competências que, na minha visão, ganharão mais importância.

Cinco competências

A primeira é a capacidade de escrever especificações (Specification). Na era da IA, o “ponto de partida da programação” não é o teclado, mas a especificação. A capacidade de registrar com precisão o que pedir à IA se tornou mais importante que o próprio código. Aqui, “especificação” não significa necessariamente um documento RFC grandioso. Pode ser um teste que expressa em código o comportamento esperado da lógica de negócio, uma história do Storybook que organiza os cenários e o contrato visual de um componente de UI ou uma definição de tipos que explicita o contrato do fluxo de dados. No fim, é o trabalho de estabelecer previamente critérios para validar de forma automática o resultado criado pela IA. Quando programamos com IA sem essa base, os problemas se acumulam.

A segunda é a capacidade de validação e discernimento. A IA produz com confiança código plausível, porém incorreto. Por isso, considero que “a capacidade de revisar código de IA com rapidez e precisão” se tornou essencial. É preciso identificar se foram esquecidos headers de segurança, sanitização de inputs ou tokens CSRF; se a acessibilidade continua funcionando — ARIA, navegação por teclado e focus trap —; e se há problemas nos impactos de desempenho, como custo de renderização, memória e tamanho do bundle. Jogar AI slop em um PR sem revisão é negligenciar a própria função como engenheiro. Quem aperta o botão de merge ainda é uma pessoa, e essa responsabilidade não pode ser transferida para a IA. O fato de os profissionais seniores apresentarem a menor confiança em IA na pesquisa do Stack Overflow provavelmente se deve, no fim das contas, a terem olhos treinados para encontrar justamente esses detalhes.

A terceira é a compreensão de sistemas e o pensamento arquitetural. A IA lida bem com um arquivo por vez e tem grande capacidade de perceber fluxos e relações. Ela corrige sintomas rapidamente, mas um desenvolvedor competente encontra a causa raiz. Uma forma de desenvolver essa competência é realizar atividades deliberadas, como Architecture Retrospectives. Como o código muda mais rápido, se não elevarmos conscientemente a compreensão que a equipe tem do sistema, a dívida cognitiva se acumulará depressa.

A quarta é a capacidade de orquestrar IA. A competência de lidar com a própria IA também está se separando em um conjunto específico de habilidades. Já não se trata simplesmente de “escrever bons prompts”, mas de uma área que exige tratar como um todo a capacidade de dividir o trabalho em tickets pequenos, escolher qual modelo usar para cada tarefa, projetar pipelines de avaliação e validação de agentes e definir estratégias de recuperação (rollback) em caso de falha. Steve Yegge organiza essa evolução em seis waves (traditional → completions → chat → coding agents → agent clusters → agent fleets).

A quinta é Context Engineering. É um conceito que Karpathy e Tobi Lütke, CEO da Shopify, começaram a promover juntos em meados de 2025. Em poucas palavras, trata-se da “capacidade de planejar qual contexto mostrar à IA, em que formato e em qual quantidade”. Na prática, aparece de formas como o trabalho com arquivos CLAUDE.md / rules, que registra convenções do projeto, princípios de arquitetura e proibições em locais acessíveis à IA; a redução intencional do contexto, que seleciona apenas os módulos relevantes em vez de inserir todos os arquivos no contexto; a separação explícita de etapas, que divide planejamento → implementação → validação em sessões distintas para evitar a contaminação do contexto; e o contexto externo via MCP, que conecta, por meio de interfaces padronizadas, fontes externas como design systems, schemas de API e dados de monitoramento. A documentação oficial da Anthropic chama isso de “the new prompt engineering” e afirma categoricamente que um único prompt jamais consegue conter o conhecimento arquitetural, os padrões e a tribal wisdom de um sistema. Em outras palavras, “projetar um ambiente em que a IA sempre receba um bom contexto” se tornou muito mais importante do que “escrever um bom prompt de uma só vez”.

Se você chegou até aqui, uma pergunta surge naturalmente: então, concretamente, como estudar? Os métodos que uso são, em linhas gerais, quatro.

Como estudar

O item “aprendizado contínuo” citado no texto original continua válido, mas precisamos mudar a distribuição do tempo de estudo.

Há áreas às quais dedicávamos muito tempo e que agora podem receber menos. Por outro lado, também há áreas complexas que antes evitávamos por serem difíceis ou demoradas. Entre estas últimas estão a escrita de especificações de testes, o uso de ferramentas de medição de desempenho — Lighthouse, WebPageTest e Chrome DevTools Performance —, acessibilidade (WCAG) e segurança, especialmente o OWASP Top 10. Também há áreas completamente novas a aprender, como Vercel AI SDK, LangChain.js, MCP, padrões de UI com streaming e pipelines de avaliação de agentes. É importante reconhecer quais competências eu preciso desenvolver e distribuir meu tempo de acordo com isso.

O código produzido por IA tende a crescer demais. Ela gera centenas de linhas por minuto. Por isso, se não gerenciarmos conscientemente o tamanho dos PRs e a frequência de merge, o próprio code review entra em colapso. Dentro das empresas, após a adoção da IA, o tamanho médio dos PRs aumentou 18%, os incidentes por PR subiram 24% e a taxa de falha de mudanças cresceu 30%. Considerando também os dados discutidos acima, quando escrevemos grandes blocos e fazemos merge de tudo de uma vez, fica difícil compreender o fluxo e refletir a intenção; por isso, é importante granularizar as unidades de trabalho.

Há uma prática diretamente ligada ao problema da redução da carga cognitiva apontado no texto de Evan Moon: é bom reservar uma ou duas horas por dia para escrever código sem IA. Desenhar a arquitetura à mão ou ler diretamente, linha por linha, código de uma área pouco familiar são alguns exemplos. (Eu também tento programar sem IA todos os dias naquele período sonolento depois do almoço. É um tempo que reservo para não me afastar de uma familiaridade antiga.)

Isso não serve apenas para “não esquecer o jeito antigo”. A sua própria profundidade deixa de crescer durante o tempo em que a IA faz o trabalho por você. Competências como validação e discernimento e compreensão do sistema são função do tempo que você passou enfrentando os problemas diretamente.

Portanto, nós

Depois de tudo isso, a verdade é que o perfil do engenheiro frontend que sobrevive na era da IA não é tão diferente da conclusão apresentada no texto original. Estes eram os três pontos que ele destacava sobre bons engenheiros seniores.

• Procura permanecer fiel aos fundamentos. (Mantém e fortalece continuamente as cinco competências fundamentais.)
• Mesmo sem ser o líder formal, exerce influência natural por meio de um comportamento exemplar.
• Não se satisfaz apenas em concluir bem o trabalho recebido; observa o contexto anterior e posterior e gera um impacto maior.

Aplicando isso à perspectiva da era da IA, temos o seguinte.

• Mantém-se fiel aos fundamentos que vão além do código produzido pela IA: web, sistemas e domínio.
• Define a direção por conta própria, não a IA. Mesmo sem ser a pessoa formalmente responsável, decide “para onde devemos ir”.
• Não usa a IA apenas como ferramenta de produtividade pessoal; usa-a para eliminar gargalos da equipe e do sistema.

Ao examinar os textos de Andrej Karpathy, autoridade em OpenAI, vemos que a essência do “agentic engineering” que ele enfatiza agora é, no fim, a mesma: projetar o sistema, especificar as restrições e usar a IA para acelerar uma implementação cujo raciocínio já foi concluído mentalmente. As ferramentas mudam, mas o controle da direção continua nas mãos das pessoas.

A mensagem final do texto original também era que se torna sênior “quem não se satisfaz apenas em concluir bem o trabalho recebido, mas observa o contexto anterior e posterior e gera um impacto maior”. Na era da IA, apenas a definição desse “impacto” mudou. Há quem faça merge de uma tela produzida pela IA em uma hora pensando “funciona, então está pronto”; e há quem passe mais trinta minutos verificando até que ponto essa tela é adequada em termos de acessibilidade, segurança, desempenho e coerência com o sistema. Daqui a um ano, quem será reconhecido como sênior é o segundo. Sobrevive quem se posiciona do lado dos 30% na fronteira entre 70% (funcionamento) e 30% (aplicação e uso).

Espero que os engenheiros frontend que lerem este texto também encontrem sua própria resposta para a pergunta “o que mais devo estudar agora?”. Ninguém sabe a resposta certa, mas tenho bastante convicção de que, quanto mais a IA escreve código, mais sobrevivem as pessoas capazes de enxergar “o que existe além do código”. Encerro na esperança de que, daqui a um ano, eu possa voltar a escrever sobre como esse cenário terá mudado mais uma vez.

(Se este texto parecer óbvio demais ou ultrapassado daqui a um ano, talvez isso signifique que reagimos bem.)

Referências

Ao trabalhar com desenvolvimento frontend, já me perguntei inúmeras vezes: "Até que ponto devo separar esta lógica?" e "Em que unidades devo dividir este componente?". No começo, eu achava que abstração era simplesmente extrair as partes em comum: transformar código repetido em uma função e reunir em um só lugar os pontos comuns de componentes semelhantes. Mas, depois de ver algumas vezes o código criado dessa forma se transformar, com o passar do tempo, em um monstro ainda mais difícil de modificar, comecei a repensar o que é abstração.

Neste texto, pretendo organizar as reflexões que venho fazendo sobre a essência da abstração e sobre como usá-la no desenvolvimento frontend para produzir um bom código.

Abstrato e abstração

Antes de entrar no assunto principal, vale esclarecer o que as palavras "abstrato" e "abstração" significam exatamente na programação. Elas parecem semelhantes, mas têm naturezas bem diferentes.

Abstrato (Abstract) é um estado e uma propriedade. Quando dizemos que "isto é abstrato", queremos dizer que os detalhes concretos foram omitidos e que restaram apenas os conceitos essenciais. Classes ou métodos marcados com a palavra-chave abstract em Java ou TypeScript têm justamente esse sentido. São projetos incompletos nos quais a implementação concreta ainda não foi preenchida e apenas a forma essencial está definida.

Abstração (Abstraction) é um processo e uma ação. É o próprio processo de simplificar algo complexo, mantendo apenas suas características essenciais e removendo detalhes desnecessários. O ponto importante é que abstrair não significa "agrupar as coisas de qualquer jeito", mas definir com precisão o papel de cada nível.

No cotidiano, a palavra "abstrato" costuma carregar a nuance de "vago". Na programação, porém, a abstração é exatamente o contrário. Seu objetivo não é criar ambiguidade, mas estabelecer um novo nível de significado que possa ser absolutamente preciso. Preservar as informações relevantes em determinado contexto e esquecer as irrelevantes é a essência da abstração.

No fim, podemos distinguir os dois conceitos assim: o abstrato é "o estado em que só resta o essencial", enquanto a abstração é "o processo de deixar apenas o essencial". Ao projetar código, é exatamente essa abstração que realizamos: o processo de conservar apenas a interface essencial de uma implementação complexa e esconder o restante.

Então, por que precisamos desse tipo de abstração na programação?

Por que a abstração é necessária

A razão fundamental para precisarmos de abstração na programação é surpreendentemente simples: para construir coisas mais complexas. Quando queremos criar algo mais complexo, torna-se difícil lembrar e lidar com todos os seus muitos elementos. Por isso, agrupamos esses elementos e os transformamos em conceitos abstratos simplificados.

O próprio React, usado diariamente por desenvolvedores frontend, é um exemplo. Para renderizar um único componente, ocorrem internamente processos complexos como a criação do Virtual DOM, a reconciliação (Reconciliation) e a manipulação do DOM real. Ainda assim, basta escrevermos JSX sem nos preocuparmos com nada disso, porque o React abstraiu esse processo complexo para nós.

Observe o código abaixo. Ao usar o componente UserProfile, conseguimos criar e manipular a UI sem conhecer processos complexos que ocorrem internamente, como a criação do VDOM e o diffing.

<UserProfile name="jihoon" />

Antigamente, configurar o Webpack manualmente fazia parte da rotina de um desenvolvedor frontend, mas hoje frameworks como Next.js e Vite abstraem as configurações de bundling. Graças a isso, podemos desenvolver aplicações sem conhecer o funcionamento interno do bundler e usar esse tempo para nos concentrar em problemas de nível mais alto, como a lógica de negócio e a experiência do usuário. (É por isso que considero o conceito de abstração extremamente importante para o papel do desenvolvedor frontend.)

No fim das contas, este é o valor central da abstração: esconder a complexidade para que algo pareça simples e permitir que cada pessoa se concentre apenas em sua própria área. Graças a ela, conseguimos construir softwares cada vez maiores e mais complexos sem que uma única pessoa precise compreender tudo.

Se a abstração é tão boa assim, será que quanto mais abstrairmos, melhor? Vamos pensar com que objetivo devemos abstrair.

Reduzir o contexto

Muitos desenvolvedores entendem abstração como "extrair as partes em comum". Isso não está errado, mas é apenas uma das técnicas usadas para abstrair, não uma explicação de sua essência.

Para mim, a essência da abstração é "reduzir, ao nível adequado, o contexto que uma pessoa precisa conhecer para ler o código".

Vejamos um exemplo simples.

interface Order {
  id: string;
  status: "pending" | "completed";
  amount: number;
}
 
let total = 0;
 
const orders: Order[] = [
  { id: "a", status: "pending", amount: 10000 },
  { id: "b", status: "completed", amount: 5000 },
  { id: "c", status: "completed", amount: 8000 },
];
 
for (let i = 0; i < orders.length; i++) {
  if (orders[i].status === "completed") {
    total += orders[i].amount;
  }
}

Para ler esse código, um desenvolvedor precisa compreender a inicialização, a condição e o incremento do loop, o acesso aos elementos por índice, a ramificação condicionada e até a forma como a variável acumuladora externa é atualizada. O que o código realmente pretende fazer cabe em uma única frase — "calcular a soma dos pedidos concluídos" —, mas, para entendê-la, é preciso manter quatro contextos diferentes na cabeça ao mesmo tempo.

const total = orders
  .filter((order) => order.status === "completed")
  .reduce((sum, order) => sum + order.amount, 0);

Graças às abstrações filter e reduce, o desenvolvedor só precisa acompanhar duas intenções: "selecionar apenas os pedidos concluídos" e "acumular os valores". O contexto do gerenciamento de índices e da declaração e atualização da variável acumuladora desapareceu da superfície do código.

Podemos avançar mais um passo.

const total = sumCompletedOrders(orders);

Agora, quem lê o código nem sequer precisa saber que esse cálculo percorre um vetor. Resta apenas a intenção de negócio de "calcular o valor total dos pedidos concluídos". Passamos a nos concentrar não em como (How) o cálculo é feito, mas em o que (What) é calculado.

Sob essa perspectiva, percebemos que o código React que escrevemos todos os dias também é uma combinação de inúmeras abstrações.

import { css } from "@emotion/css";
import { format } from "date-fns";
 
const TodayHeader = () => {
  const now = new Date(); // Date 객체 생성이라는 복잡한 과정을 추상화
  const formatted = format(now, "yyyy-MM-dd"); // 날짜 포맷팅 로직을 추상화
 
  return (
    <h1
      className={css`
        font-size: 1.8rem;
      `}
    >
      {/* CSS-in-JS 처리 과정을 추상화 */}
      Today is {formatted}
    </h1> // React.createElement를 추상화
  );
};
 
// 그리고 위 모든 것을 다시 추상화
<TodayHeader />;

E se todo o código interno de emotion, date-fns e react estivesse aberto dentro deste arquivo de componente? Seria difícil saber por onde começar a leitura e distinguir a lógica de negócio do código das bibliotecas. Como a abstração esconde adequadamente o contexto de cada área, podemos nos concentrar apenas na essência: "mostrar a data de hoje".

Então, ao projetar código na prática, em que direção devemos abordar a abstração?

O que significa um nível de abstração alto ou baixo

Quando falamos de abstração, não podemos deixar de abordar o conceito de nível de abstração (Level of Abstraction). Afinal, o que significa dizer que o nível de abstração de um código é "alto" ou "baixo"?

Um código com baixo nível de abstração está próximo dos procedimentos concretos executados pelo computador: fazer o parsing de uma string diretamente, percorrer um vetor por índices ou manipular bytes. Ele expõe claramente como (How) funciona.

// 추상화 수준이 낮은 코드
const response = await fetch('/api/users');
const users = await response.json();
const filteredUsers = users.filter(user => user.status === 'active');
 
filteredUsers.forEach(user => {
  const element = document.getElementById(`user-${user.id}`);
  if (element) element.style.display = 'block';
});

Um código com alto nível de abstração é expresso na linguagem do domínio de negócio ou da área do problema. Alguns exemplos são processPayment(order), sendNotification(user, message) e validateUserInput(formData). Um código com alto nível de abstração revela o que (What) faz e esconde como faz.

Em Clean Code, Robert C. Martin organizou esse conceito no princípio de "um nível de abstração por função (One Level of Abstraction per Function)". Quando uma mesma função mistura código de alto e baixo nível, quem a lê precisa decidir a cada linha: "Isto é a lógica principal ou um detalhe de implementação?".

O problema fica claro quando observado em código real.

// 추상화 수준이 뒤섞인 함수
async function registerUser(name: string, email: string, password: string) {
  // ✅ 높은 수준: 비즈니스 규칙 검증
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  // ❌ 낮은 수준: 비밀번호 해싱 직접 구현
  const encoder = new TextEncoder();
  const data = encoder.encode(password);
  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
  const hashedPassword = Array.from(new Uint8Array(hashBuffer))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
 
  // ✅ 높은 수준: 사용자 저장
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  // ❌ 낮은 수준: 이메일 전송 직접 구현
  const verifyToken = crypto.randomBytes(32).toString("hex");
  await db.execute(
    "INSERT INTO email_tokens (user_id, token, expires_at) VALUES (?, ?, ?)",
    [user.id, verifyToken, new Date(Date.now() + 86_400_000)]
  );
  await transporter.sendMail({
    from: "noreply@example.com",
    to: user.email,
    subject: "Welcome! Please verify your email",
    html: `<a href="/verify?token=${verifyToken}">Verify your account</a>`,
  });
 
  // ✅ 높은 수준: 환영 이메일 발송
  await sendWelcomeEmail(user);
}

Quem lê essa função começa acompanhando o contexto de alto nível das regras de negócio do "fluxo de cadastro do usuário", mas de repente é arrastado para o contexto de baixo nível da manipulação de buffers de hash, consultas SQL e strings de templates de e-mail. Em seguida, salta outra vez para o alto nível de sendWelcomeEmail. Quando o nível de abstração sobe e desce dessa forma, a mente de quem lê também precisa subir e descer junto.

Se reescrevermos a mesma função mantendo um nível de abstração uniforme, o resultado será este.

// 추상화 수준이 일관된 함수
async function registerUser(name: string, email: string, password: string) {
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  const hashedPassword = await hashPassword(password);
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  await sendVerificationEmail(user);
  await sendWelcomeEmail(user);
}

Todas as instruções falam no mesmo nível de abstração. Cada função de nível inferior fica responsável por como o envio de e-mails é implementado ou qual algoritmo é usado para gerar o hash da senha. Quem lê essa função só precisa se concentrar em um único contexto: "o fluxo completo de cadastro do usuário".

Martin também chama isso de "regra descendente (The Stepdown Rule)". Ao ler o código de cima para baixo, como em uma matéria de jornal, devemos ver o panorama geral no topo e encontrar cada vez mais detalhes conforme descemos.

Kent Beck apresentou o mesmo princípio em Smalltalk Best Practice Patterns por meio do padrão Composed Method. Um método deve ser composto apenas de operações no mesmo nível de abstração, e cada etapa deve ser expressa por uma chamada de método em uma única linha.

No fim, todas essas ideias chegam à mesma conclusão: uma função deve falar em apenas um nível de abstração. Só esse cuidado já muda visivelmente a legibilidade do código.

Mas em que direção devemos conduzir a abstração? Devemos partir do concreto ou do abstrato?

Pensar em composição de peças, não em extração de pontos comuns

Na OOP, é comum ouvir a diretriz "extraia os pontos comuns das coisas concretas para definir algo abstrato". Essa abordagem não está errada por si só, mas acredito que se prender demais a ela traz o risco de criar um design limitado aos requisitos atuais.

Vejamos um exemplo. Suponha que os requisitos incluam os botões A, B e C, todos azuis e arredondados, com diferença apenas no texto do rótulo. Se projetarmos extraindo apenas os pontos comuns, podemos representá-los assim.

const BlueRoundButton = ({ label }: { label: string }) => {
  return <button className="blue round">{label}</button>;
};

Os requisitos atuais são atendidos perfeitamente. Alguns dias depois, porém, a pessoa responsável pelo produto diz:

"Permita alterar a cor do botão B."

Nesse instante, o próprio nome BlueRoundButton se torna estranho. Até seria possível adicionar uma prop de cor, mas o design já era vulnerável a mudanças porque partira da característica concreta comum de ser "um botão azul e arredondado". (E este ainda é um caso simples. No mundo real, chegam inúmeros requisitos sobre o formato, o tamanho e muitos outros aspectos do botão.)

Quando situações como essa se repetem, percebemos naturalmente uma coisa: uma abordagem que extrai pontos comuns de requisitos concretos tende a fazer com que até o resultado abstraído reflita apenas os requisitos atuais.

Por isso, prefiro seguir na direção oposta. Em vez de extrair o abstrato a partir do concreto, gosto de pensar primeiro em peças abstratas e compô-las para criar algo concreto.

Imagine que estamos criando um componente de notificação toast. O requisito inicial é simples: "Quando o salvamento for concluído, mostre uma breve mensagem de orientação na parte inferior." Pela abordagem de extração de pontos comuns, teríamos isto.

// 현재 요구사항의 공통 특성에서 출발한 설계
type ToastProps = {
  message: string;
  hasAction?: boolean;
  actionLabel?: string;
  onAction?: () => void;
};
 
const Toast = ({ message, hasAction, actionLabel, onAction }: ToastProps) => (
  <div className="toast">
    <span>{message}</span>
    {hasAction && <button onClick={onAction}>{actionLabel}</button>}
  </div>
);

O requisito atual é atendido perfeitamente. Alguns dias depois, porém, a pessoa responsável pelo produto pede: "Adicione um ícone à esquerda de acordo com o estado de sucesso ou alerta". Surgem hasIcon e iconName. Logo chega outro pedido: "Também precisamos de um toast com uma barra de progresso de upload". Mais uma prop, progress, é adicionada. Depois de repetir esse processo algumas vezes, Toast passa a ter mais de dez props e ainda exige que se decorem regras ocultas sobre quais combinações são permitidas e quais não são. (E, na maioria das vezes, essas regras nem sequer ficam registradas em comentários.)

O design era vulnerável a mudanças porque havia partido da imagem concreta, no momento atual, de "como um toast deve ser".

Quando abordamos o problema pela composição de peças, a história muda.

// 부품을 조립하는 설계
const Toast = ({ children }: PropsWithChildren) => (
  <div className="toast">{children}</div>
);
 
Toast.Icon = ({ name }: { name: "check" | "warn" | "info" }) => {
  /* ... */
};
 
Toast.Message = ({ children }: PropsWithChildren) => <span>{children}</span>;
 
Toast.Action = ({
  children,
  onClick,
}: PropsWithChildren<{ onClick: () => void }>) => (
  <button onClick={onClick}>{children}</button>
);
 
Toast.Progress = ({ value }: { value: number }) => {
  /* ... */
};
 
// 필요한 부품만 골라 조립한다
<Toast>
  <Toast.Message>저장되었습니다</Toast.Message>
</Toast>;
 
<Toast>
  <Toast.Icon name="check" />
  <Toast.Message>업로드 완료</Toast.Message>
  <Toast.Action onClick={undo}>실행 취소</Toast.Action>
</Toast>;
 
<Toast>
  <Toast.Progress value={0.4} />
  <Toast.Message>파일 전송 중...</Toast.Message>
</Toast>;

A essência imutável — "um toast é um contêiner simples que apenas envolve conteúdo" — foi separada dos detalhes concretos mais sujeitos a mudanças — "o que ele abriga". Agora podemos adicionar quantas peças novas quisermos ou organizar as existentes em novas combinações sem tocar no interior de Toast. As regras de validade para combinações de props também desaparecem. Basta colocar ali o que queremos.

É claro que um desenvolvedor experiente poderia perguntar: "Não basta projetar desde o início com IoC (inversão de controle)?". É verdade. Mas esse julgamento só é possível porque, depois de incontáveis tentativas e erros no passado, foi desenvolvida uma intuição sobre "quais partes tendem a mudar".

Quando ainda não temos essa intuição, partir da pergunta "De quais peças esta funcionalidade é composta e como cada uma deve ser combinada?" facilita muito a criação de um design aberto a mudanças.

Depois de ler até aqui, surge naturalmente uma pergunta: com base em que critérios devemos separar as peças e como devemos expô-las externamente?

Três pontos para uma boa abstração

Pensar na expressividade

A virtude mais importante de um módulo abstraído é permitir que seu comportamento seja deduzido sem que seja necessário abrir o código-fonte. Kent Beck chamou isso de padrão "nome que revela intenção (Intention-Revealing Name)" e afirmou que, se não for possível encontrar um nome conciso, a própria abstração precisa ser repensada.

Temos duas grandes ferramentas para isso: nomes e tipos.

// 도대체 뭘 하는 건지 알 수 없는 함수
function calculate(price: number, rate: number): number;
 
// 이름과 타입만으로 동작을 유추할 수 있는 함수
function calculateDiscountedPrice(originalPrice: number, discountRate: number): number;

Só pelo nome de calculateDiscountedPrice, sabemos que a função recebe o preço original e a taxa de desconto para calcular o preço com desconto, enquanto a informação de tipo confirma que ela recebe number e retorna number. Não precisamos conhecer a lógica de cálculo aplicada internamente.

Já calculate(price: number, rate: number): number não informa o que está sendo calculado, portanto não nos permite prever o resultado. No fim, só conseguimos usá-la depois de abrir o código-fonte, perdendo a vantagem da abstração.

Nesse ponto, vale observar que a própria forma de nomear reflete o nível de abstração. Na programação, nomes de funções costumam ser compostos pela combinação verbo + substantivo, e o verbo escolhido revela em que nível de abstração a função opera.

No entanto, o verbo sozinho não determina o nível de abstração. O substantivo que o acompanha — isto é, o contexto do domínio — determina o nível final

Existem verbos frequentemente usados em níveis de abstração baixos, como parse, encode, decode, serialize, read, write, push, pop, convert e transform. Essas palavras sugerem uma transformação física dos dados ou uma manipulação direta da estrutura de dados.

No nível intermediário, aparecem verbos como get, save, load e validate. São operações técnicas, mas seu propósito já se revela até certo ponto.

Em níveis de abstração altos, são usados verbos como register, refund, confirm, cancel e submit. Essas palavras pertencem à linguagem do domínio de negócio. Elas não revelam nenhum dos procedimentos técnicos internos, expressando apenas as ações do usuário ou os processos de negócio.

// 낮은 수준: 기술적 동작이 드러남
function parseJSON(text: string): object;
function encodeBase64(data: Uint8Array): string;
 
// 중간 수준: 의도가 드러나되 기술적 맥락이 남아있음
function getUserById(id: string): Promise<User>;
function validateEmail(email: string): boolean;
 
// 높은 수준: 비즈니스 의도만 드러남
function registerUser(form: RegistrationForm): Promise<User>;
function refundPayment(orderId: OrderId, amount: Money): Promise<Refund>;

Em Clean Code, Robert C. Martin afirmou que "um nome longo e descritivo é melhor que um nome curto e enigmático". Ele também apresentou o princípio "use uma palavra por conceito", pois, se misturarmos fetch, retrieve e get para operações no mesmo contexto, quem lê ficará em dúvida: "Essas três operações são diferentes?".

O mesmo princípio se aplica diretamente à nomenclatura de componentes e hooks do React.

<Button />           
<SearchInput />      
<SubmitOrderButton />

A especificidade do nome de um componente varia de acordo com seu nível de abstração. Button é usado em um nível baixo como um primitivo genérico de UI, enquanto SubmitOrderButton revela claramente a intenção de negócio em um nível alto.

const handleSubmit = async(data: FormData) => { 
  await registerUser(data);
};
 
<Form onSubmit={handleSubmit} />           

on* é o nome da prop que o componente expõe externamente. Quem usa o componente declara "a qual evento reagir". handle* é o nome da função de implementação efetivamente passada para essa prop.

const user = useAuth();                  
const [items, setItems] = useCartItems();
const { isOpen, toggle } = useModal();   

Hooks customizados usam o prefixo use para seguir as regras do React e permitem que componentes utilizem o estado ou as operações fornecidas pelo hook.

Jeff Atwood, responsável pelo Coding Horror, já apontou o problema do sufixo Manager. O nome UrlManager não revela se sua função é manter um pool de URLs, validá-las ou criá-las. Nomes como UrlBuilder, UrlValidator e UrlPool, que revelam papéis específicos, são muito melhores. Um nome vago pode ser um sinal de que a própria responsabilidade do módulo é vaga.

No fim das contas, um bom nome é aquele que informa imediatamente a quem lê em que nível de abstração o código opera.

Projetar intencionalmente o grau de liberdade das entradas

Ao projetar um módulo abstraído, há uma dúvida recorrente: "Até que ponto devemos deixar a funcionalidade aberta?". Essa decisão muda bastante a experiência dos desenvolvedores que usam o módulo.

// 기능이 닫힌 컴포넌트
const Button = ({ children }: {children?: React.ReactNode}) => {
  return <button>{children}</button>;
};
 
// 기능이 완전히 열린 컴포넌트
const Button = (props: ComponentProps<"button">) => {
  return <button {...props} />;
};

O primeiro botão aceita apenas children. Não é possível configurar onClick, type nem disabled. Em compensação, quem o usa não precisa tomar nenhuma decisão.

O segundo botão aceita todos os atributos do elemento button. Ele oferece muita liberdade, mas quem o utiliza precisa decidir quais, entre dezenas de props, deve usar. Eu descrevo essa situação dizendo que "o componente obriga o desenvolvedor a pensar".

Não há uma resposta certa. Precisamos encontrar o nível adequado de acordo com o propósito e os usuários do módulo. Para o botão básico de um design system, pode ser melhor preservar a consistência com Props limitadas; para um componente utilitário genérico, pode ser melhor oferecer flexibilidade.

// 지나치게 닫힌 인터페이스 — 다양한 상황에 대응 불가
<Button onClick={handleSubmit}>제출</Button>
// onClick 외의 이벤트, className, disabled 등을 전달할 방법이 없다
 
// 지나치게 열린 인터페이스 — 의도가 사라짐
<Button {...anyProps} />
// 무엇을 전달해야 하는지 사용자가 직접 파악해야 한다

A amplitude da abstração deve ser determinada por quem é seu usuário. Para quem precisa compreender e controlar em detalhes a implementação interna, uma interface de baixo nível é adequada. Por outro lado, oferecer uma interface excessivamente aberta a quem não precisa conhecer os detalhes só aumenta a confusão. Da mesma forma, limitar demais as entradas de quem precisa lidar com diversas situações acaba inviabilizando os próprios casos de uso.

Manter a unidade de abstração no tamanho adequado

A unidade de abstração — isto é, "até onde agrupar em um único módulo" — também é uma questão importante.

Um antipadrão comum no frontend é a extração excessiva de Custom Hooks.

// 이 훅은 단 하나의 컴포넌트에서만 사용된다
const useUserProfileData = () => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    fetchUser()
      .then(setUser)
      .finally(() => setLoading(false));
  }, []);
 
  return { user, loading };
};

Quando separamos desnecessariamente em um hook uma lógica usada por um único componente, quem lê precisa alternar entre dois arquivos para compreender o contexto. Em vez de reduzi-lo, a abstração acabou aumentando-o.

O contrário — colocar coisas demais em um único hook — também é um problema.

// 관련 없는 관심사가 하나의 훅에 뒤섞여 있다
const useEverything = () => {
  const auth = useAuth();
  const theme = useTheme();
  const analytics = useAnalytics();
  const toast = useToast();
 
  return { auth, theme, analytics, toast };
};

Um "God Hook" como esse é difícil de testar, e a alteração de uma única coisa pode afetar partes sem relação com ela.

O critério para determinar a unidade adequada de abstração é "esta separação realmente reduz o contexto de quem lê o código?" Se o resultado da separação dispersar o contexto e dificultar sua compreensão, ainda não chegou a hora dessa abstração.

Cuidado com abstrações prematuras

Depois de ler até aqui, pode restar a pergunta: "Então, quando devo abstrair?". Minha opinião é esta: a premissa básica deve ser não abstrair prematuramente.

Enquanto não houver um sinal claro de abstração, deixar o código como está oferece um resultado mínimo melhor do que criar uma abstração errada e precisar desfazê-la mais tarde. O processo pelo qual uma abstração ruim costuma surgir é mais ou menos este.

1. Surge um padrão semelhante no código A e no código B.
2. Pensamos: "É o princípio DRY, então vou extrair uma função comum!" e criamos uma abstração.
3. Um padrão parecido aparece no código C; usamos a mesma função, mas adicionamos um parâmetro para obter um comportamento um pouco diferente.
4. Quando os códigos D e E também passam a usá-la, as condicionais e os parâmetros continuam aumentando.
5. Agora a função é usada em toda parte, mas todos têm medo de modificá-la.

// 처음에는 단순했던 함수가...
const formatUserName = (user: User) => `${user.firstName} ${user.lastName}`;
 
// 요구사항이 추가될 때마다 매개변수가 늘어나고...
const formatUserName = (
  user: User,
  includeMiddleName?: boolean,
  format?: "full" | "short" | "initials",
  locale?: string,
  honorific?: boolean,
) => {
  if (format === "initials") {
    /* ... */
  }
  if (includeMiddleName && user.middleName) {
    /* ... */
  }
  if (honorific && locale === "ko") {
    /* ... */
  }
  // ...끝없는 분기
};

Se chegamos a essa situação, a solução é clara: colocar o código abstraído novamente inline em cada caso de uso, remover de cada um o que for desnecessário e, quando o verdadeiro ponto em comum se revelar no código já limpo, abstrair outra vez. "O avanço mais rápido é voltar atrás."

Então, quando devemos abstrair? Os sinais de abstração que percebo são mais ou menos estes.

• A consistência está se perdendo. Embora a lógica seja a mesma, em alguns componentes ela fica inline e, em outros, é separada em uma função. A mesma lógica de cálculo está espalhada por toda parte.
• A estrutura interna está desnecessariamente exposta ao exterior. O chamador precisa lidar, um por um, com detalhes de implementação que não deveria conhecer.
• O procedimento interno continua exposto. O módulo não consegue ocultar seus próprios procedimentos, e quem o utiliza precisa segui-los diretamente.

O problema é que, embora detectar esses sinais costume ser simples, na prática é fácil ignorá-los e se concentrar em atender a requisitos mais "importantes". Quando estamos sob pressão de prazos ou concentrados em implementar funcionalidades, pensamos: "Por enquanto funciona; organizo depois" — e esse depois raramente chega.

Outro ponto importante é manter critérios de abstração consistentes. Se o mesmo tipo de lógica fica inline em um lugar da codebase, separado em uma função em outro e extraído para um hook customizado em outro, quem começa a ler o código se pergunta: "Existe alguma intenção nessa diferença?". Abstraindo ou não, a equipe precisa adotar critérios consistentes.

Também vale lembrar, nesse contexto, a "lei das abstrações com vazamento (The Law of Leaky Abstractions)", apresentada por Joel Spolsky em 2002. Essa lei diz que, embora uma abstração tente esconder uma implementação complexa, os detalhes dessa implementação acabam vazando (leak) para fora. Em outras palavras, uma abstração é projetada para que seus usuários não precisem conhecer a implementação interna, mas surgem situações em que só é possível usá-la corretamente conhecendo-a.

O TCP abstrai uma rede instável como se fosse uma conexão confiável, mas, quando um cabo é desconectado, essa abstração se rompe. O React abstrai as atualizações de UI de forma declarativa, mas, para otimizar novas renderizações, acabamos precisando compreender seu funcionamento interno. Como não existe abstração perfeita, ao criar uma também precisamos pensar: "O usuário conseguirá reagir quando esta abstração se romper?"

No fim, "a abstração economiza nosso tempo de trabalho, mas não economiza nosso tempo de aprendizado."

A abstração é algo que se internaliza

Certa vez, conversei com um colega sobre abstração, e uma observação feita naquele momento me marcou: detectar sinais de abstração e separar o código no nível adequado, na hora certa, é, no fim das contas, uma questão de intuição.

É claro que os princípios discutidos anteriormente — manter o mesmo nível de abstração, dar bons nomes e projetar o grau de liberdade das entradas — são importantes. Porém, tentar lembrar cada um deles enquanto escrevemos código e ponderar conscientemente "Devo separar isto ou não?" pode acabar interrompendo nosso fluxo. Assim como pensar no ângulo do cotovelo ao lançar um jab durante uma luta pode fazer alguém perder o momento certo, ao programar a abstração também deve surgir de uma intuição natural, não de um julgamento consciente.

Há momentos em que estamos escrevendo código e de repente sentimos certa rejeição: "Parece que esta lógica não deveria estar aqui" ou "Parece que este componente sabe coisas demais". Essa sensação é justamente um sinal de abstração, e internalização é a capacidade de detectá-lo e reagir a ele naturalmente.

Mas essa intuição não surge da noite para o dia. Só depois de estudar inúmeros padrões, ler códigos variados e passar pessoalmente por muitas tentativas e erros é que a sensação de "acho que isto precisa ser separado" começa a aparecer com naturalidade. Se, mais tarde, um colega perguntar "Por que você separou isto?" e conseguirmos explicar naturalmente "Eu separei porque se trata de X", significa que esse conhecimento foi internalizado.

Acho que o mesmo vale para qualquer área. Quando tentamos fazer algo bem apenas decorando regras, tomar decisões se torna ainda mais difícil. No fim, precisamos preservar o fluxo geral e deixar que os detalhes sejam preenchidos naturalmente. E essa naturalidade nasce da variedade de padrões e experiências que acumulamos no dia a dia.

Conclusão

Na programação, abstrair é esconder a complexidade para fazê-la parecer simples e permitir que quem lê o código se concentre apenas no contexto necessário.

Retomando os pontos que devemos lembrar para criar uma boa abstração:

• Como premissa básica, não devemos abstrair prematuramente; devemos separar apenas quando surgirem sinais claros.
• Uma função deve falar em apenas um nível de abstração.
• Devemos expressar o comportamento suficientemente por meio de nomes e tipos, para que o código possa ser usado sem que seja necessário abrir seu código-fonte.
• Devemos projetar intencionalmente o grau de liberdade das entradas de acordo com o propósito e os usuários do módulo.
• Em vez de acrescentar coisas sobre uma abstração errada, devemos ter a coragem de desfazê-la e recomeçar.
• E devemos internalizar padrões variados até que tudo isso surja naturalmente, sem esforço consciente.

É claro que o que apresentei neste texto não é a única resposta correta. O nível adequado de abstração pode variar de acordo com o contexto de negócio, a composição da equipe e a natureza do projeto. Ainda assim, se existe uma coisa que não muda, é que o objetivo final da abstração consiste em criar um código fácil para as pessoas compreenderem.

Espero que quem leu este texto também se pergunte, em sua própria codebase: "Esta abstração está realmente reduzindo o contexto?". Acredito que só essa pergunta já pode mudar um pouco a forma de enxergar o código.

Referências

Este texto recebeu muita inspiração de diversas documentações oficiais e artigos anteriores. Deixo abaixo as fontes dos trechos citados diretamente e os textos que me ajudaram a estruturar estas ideias.

Ao usar o TanStack Query em projetos reais, já precisei reformular várias vezes a maneira de gerenciar queryKey. No começo, eu simplesmente escrevia vetores como ['user', userId] diretamente dentro dos componentes. Depois, comecei a cometer erros de digitação porque precisava repetir a mesma chave em vários lugares sempre que invalidava uma consulta, então migrei tudo para um objeto de constantes como QUERY_KEYS. Mais tarde, após ler um artigo de TkDodo, adotei o padrão de fábrica de chaves de consulta; bastante tempo depois, passei a usar a biblioteca @lukemorales/query-key-factory; então chegou a v5, e reformulei tudo mais uma vez com queryOptions.

Comecei a me perguntar por que tantos padrões haviam surgido em torno de um pequeno vetor que não passava de um identificador de cache. Por que uma única queryKey carrega tantos vestígios dessa evolução? E qual problema específico cada etapa tentava resolver?

Neste artigo, vou percorrer a documentação oficial do TanStack Query, a série de artigos de TkDodo e até a implementação interna de queryOptions, introduzida na v5, para explicar como queryKey funciona e por que evoluiu até sua forma atual.

Antes de queryKey

Antes de entrar no assunto principal, vale esclarecer um ponto. Hoje usamos bibliotecas como TanStack Query e SWR com toda naturalidade, mas como os dados assíncronos eram tratados antes de elas existirem?

A abordagem mais comum provavelmente era combinar useState, useEffect, fetch, axios e ferramentas semelhantes.

function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
 
  useEffect(() => {
    let cancelled = false;
    setLoading(true);
 
    fetch(`/api/users/${userId}`)
      .then((res) => res.json())
      .then((data) => {
        if (!cancelled) setUser(data);
      })
      .catch((err) => {
        if (!cancelled) setError(err);
      })
      .finally(() => {
        if (!cancelled) setLoading(false);
      });
 
    return () => {
      cancelled = true;
    };
  }, [userId]);
 
  // ...
}

O problema desse código é evidente. Se houver apenas dois componentes na página consultando o mesmo userId, a mesma requisição será feita duas vezes. Isso acontece porque não há cache. E, se o usuário navegar para outra página e voltar, os dados serão buscados novamente do zero. Como não há como saber se eles foram obtidos há um segundo ou há uma hora, também é difícil reproduzir um comportamento como "mostrar o valor armazenado em cache enquanto ele é atualizado em segundo plano". (É possível criar um sistema próprio de cache para isso, mas considero seu gerenciamento bastante complicado.)

Para resolver esse problema, surgiu a combinação Redux + redux-thunk (ou redux-saga). Ao mover a lógica de busca de dados para uma função thunk e armazenar o resultado no repositório central, outros componentes podiam reutilizar os mesmos dados. No entanto, ainda era necessário definir tipos de ação, escrever redutores e gerenciar manualmente os estados de carregamento, sucesso e falha. A quantidade de código repetitivo para buscar um único dado era enorme. (Comecei a trabalhar profissionalmente nessa época e me perguntava: "Por que preciso criar vários arquivos só para buscar um dado?")

A essência desse fluxo é: "Só é possível evitar a repetição de uma requisição quando se consegue identificar que requisição é essa." E o identificador que diz "qual requisição" é justamente a queryKey.

SWR e React Query (hoje TanStack Query) enfrentaram esse problema diretamente. "Uma requisição assíncrona precisa de um identificador, e requisições com o mesmo identificador compartilham o cache." Esse único princípio simples eliminou todo o código repetitivo descrito acima.

A essência de queryKey

Então, o que é exatamente queryKey? A documentação oficial do TanStack Query a define assim.

Em essência, o TanStack Query gerencia o armazenamento de consultas em cache com base em chaves de consulta. No nível mais alto, as chaves de consulta precisam ser um vetor... Desde que a chave de consulta seja serializável e exclusiva para os dados da consulta, ela pode ser usada.

At its core, TanStack Query manages query caching for you based on query keys. Query keys have to be an Array at the top level... As long as the query key is serializable, and unique to the query's data, you can use it.

Há dois pontos essenciais. Ela precisa ser serializável e exclusiva para aqueles dados. A mesma chave deve representar os mesmos dados, e dados diferentes devem ter chaves diferentes. Essa regra simples determina todo o funcionamento do sistema de cache.

Há ainda outro aspecto importante. queryKey também exerce o papel de vetor de dependências. Assim como um efeito de useEffect do React é executado novamente quando suas dependências mudam, o TanStack Query busca automaticamente novos dados quando queryKey muda.

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

Quando userId é 'A' e quando é 'B', as chaves de consulta são diferentes. Se são diferentes, ocorre uma falha de cache; se há uma falha de cache, os dados são buscados. Tudo automaticamente. Graças a essa simplicidade, não precisamos escrever por conta própria uma lógica que diga: "userId mudou, então é preciso buscar os dados novamente".

Isso suscita uma pergunta: como o TanStack Query determina que uma queryKey é "a mesma chave"? Se a comparação fosse feita apenas com ===, as referências dos objetos seriam diferentes e haveria uma falha de cache a cada vez.

Por dentro de QueryCache

Segundo o artigo Por dentro do React Query, de TkDodo, QueryCache é, no fim das contas, apenas uma estrutura de dados mantida na memória. Mais precisamente, na implementação oficial da v5, essa estrutura não é um objeto simples, mas um Map<string, Query>. Ela é declarada dentro da classe como #queries = new Map<string, Query>(), e todas as operações de escrita e leitura ocorrem por meio de #queries.set(query.queryHash, query) e #queries.get(queryHash). A chave é a forma serializada de queryKey (queryHash), e o valor é uma instância da classe Query.

Versões antigas chegaram a usar objetos simples, mas, na v5, a implementação passou a adotar o Map nativo. (Map não apresenta risco de colisão de chaves nem de contaminação do protótipo, preserva a ordem de inserção e oferece, em média, consulta O(1) com chaves de texto, o que o torna uma escolha praticamente canônica para uma estrutura de cache.)

O que acontece a cada chamada de useQuery é simples. queryKey é convertida em um valor de hash, que é usado para fazer uma consulta no Map. Se houver um item, a instância de Query armazenada em cache é recuperada; se não houver, uma nova instância é criada e inserida com set.

Surge então outra pergunta natural. Por que serializar queryKey como texto? Por que não usar o próprio vetor como chave, como em Map<QueryKey, Query>?

A resposta está no modelo de igualdade do JavaScript. O Map nativo compara as chaves por igualdade referencial (reference equality). Mesmo que o conteúdo seja idêntico, objetos diferentes na memória são considerados chaves distintas.

const m = new Map();
m.set(['user', 1], 'alice');
m.get(['user', 1]); // undefined — 새로 만든 배열은 다른 참조다

Em um componente React, porém, useQuery({ queryKey: ['user', userId] }) cria uma nova instância do vetor a cada renderização. Embora o conteúdo dos vetores da primeira e da segunda renderização seja idêntico, eles são objetos distintos na memória. Se o cache dependesse da igualdade referencial, qualquer componente que consultasse os mesmos dados sofreria uma falha de cache a cada renderização.

A solução para o problema causado pela igualdade referencial é simples: converter a igualdade referencial em igualdade estrutural (structural equality). Basta produzir um texto determinístico com base apenas no conteúdo de queryKey e usar esse texto como chave do Map. Assim, recuperamos a semântica desejada: "conteúdo igual significa chave igual". JSON.stringify é apenas a ferramenta mais simples para realizar essa conversão. (É também por isso que, após testar diferentes estratégias de serialização na época da v3, o TanStack Query acabou adotando uma variação estável de JSON.stringify.)

O elemento central aqui é a função que produz esse valor de hash: hashKey. A implementação oficial, definida em packages/query-core/src/utils.ts, é exatamente esta.

export function hashKey(queryKey: QueryKey | MutationKey): string {
  return JSON.stringify(queryKey, (_, val) =>
    isPlainObject(val)
      ? Object.keys(val)
          .sort()
          .reduce((result, key) => {
            result[key] = val[key]
            return result
          }, {} as any)
      : val,
  )
}

Embora use JSON.stringify, não se trata de uma serialização comum: uma função substituidora é fornecida para ordenar alfabeticamente as chaves dos objetos simples antes da serialização.

Essa ordenação é essencial porque a serialização como texto exige uma condição ainda mais rigorosa: entradas com o mesmo significado devem sempre ser convertidas no mesmo texto. No entanto, JSON.stringify normalmente preserva a ordem das chaves. { a: 1, b: 2 } e { b: 2, a: 1 } são objetos semanticamente equivalentes, mas são serializados como textos diferentes e, por consequência, ocupam posições diferentes no cache. Isso faria com que os mesmos dados voltassem a ser solicitados duas vezes.

A técnica usada para evitar isso de forma consistente é a forma canônica (canonical form). Ela força toda entrada com o mesmo significado a corresponder a uma única representação. É exatamente por isso que a função substituidora de hashKey ordena as chaves dos objetos simples. Independentemente da ordem de entrada, a saída se torna igual, fazendo o resultado da serialização corresponder univocamente ao significado do objeto. Em termos matemáticos, trata-se de escolher a forma ordenada como elemento representante da classe de equivalência (equivalence class) formada por objetos cujas chaves estão em ordens diferentes.

O fato de os vetores não serem ordenados é o outro lado do mesmo princípio. Como a própria ordem carrega significado nesse tipo de estrutura de dados, ordená-los causaria perda de informação. A ordem das chaves de um objeto é acidental; a ordem dos elementos de um vetor é intencional. hashKey trata corretamente esses dois casos de maneira distinta. Por isso, o guia oficial recomenda organizar queryKey do "genérico para o específico". Enquanto a ordem do vetor carregar significado, cabe a quem escreve o código definir esse significado.

Há mais um detalhe importante: a ordenação das chaves só se aplica a objetos simples. No mesmo arquivo, isPlainObject não verifica apenas typeof === 'object'; ela também verifica Object.getPrototypeOf(o) === Object.prototype para distinguir literais de objeto puros de instâncias de classes. Assim, um literal como { foo: 1 } é ordenado, enquanto uma instância criada com class User { ... } segue adiante sem ordenação. (Daí surge uma armadilha: ao inserir diretamente uma instância de classe em queryKey, o comportamento de JSON.stringify, que só emite propriedades enumeráveis, pode produzir um hash diferente do esperado.)

Esse funcionamento produz duas consequências importantes.

1. A ordem das chaves de um objeto é irrelevante.

useQuery({ queryKey: ['todos', { status: 'done', page: 1 }], queryFn });
useQuery({ queryKey: ['todos', { page: 1, status: 'done' }], queryFn });
// 두 쿼리는 같은 캐시 슬롯을 공유한다

Isso ocorre porque as chaves são ordenadas antes da serialização. Sem esse comportamento, seria necessário lembrar a ordem das chaves toda vez que se usasse um literal de objeto.

2. A ordem dos elementos de um vetor é relevante.

useQuery({ queryKey: ['todos', status, page], queryFn });
useQuery({ queryKey: ['todos', page, status], queryFn });
// 두 쿼리는 다른 캐시이다

Isso acontece porque o vetor é uma estrutura de dados em que a própria ordem tem significado. JSON.stringify também preserva a ordem de seus elementos.

Também é útil saber que valores undefined desaparecem durante a serialização. { a: 1, b: undefined } e { a: 1 } produzem o mesmo valor de hash. (Eu mesmo já cometi o erro de pensar: "Como incluí undefined explicitamente, deve ser outro cache!")

Além disso, queryKey não pode conter referências circulares nem funções, pois JSON.stringify não consegue processá-las. Objetos Date, bem como Map/Set, BigInt e tipos semelhantes, tampouco são recomendados com o comportamento padrão. A estrutura precisa ser pura e serializável.

Um aspecto interessante é que essa restrição não é absoluta. Por meio da opção queryKeyHashFn, o TanStack Query oferece uma saída para substituir a própria função de hash. Internamente, hashQueryKeyByOptions(queryKey, options) verifica se queryKeyHashFn foi fornecida nas opções; em caso afirmativo, chama essa função, caso contrário, chama a hashKey padrão.

useQuery({
  queryKey: [{ id: userId, fetchedAt: new Date() }],
  queryFn,
  // Date를 ISO 문자열로 바꿔서 해싱
  queryKeyHashFn: (key) =>
    JSON.stringify(key, (_, v) => (v instanceof Date ? v.toISOString() : v)),
});

Contudo, essa opção precisa ser definida separadamente para cada consulta e não se aplica a APIs imperativas chamadas sem acesso às opções, como queryClient.setQueryData (Issue nº 1343). Por isso, em projetos reais, é muito mais seguro evitar essa saída e converter queryKey para uma forma serializável no momento em que ela é criada. (Certa vez, inseri diretamente um Date e passei muito tempo tentando entender: "Por que o cache não é atualizado se o instante é o mesmo?" A resposta era: "Esse Date representa o mesmo instante, mas é outra instância do objeto e, portanto, produz um hash diferente a cada vez.")

Regras para escrever queryKey

Depois de compreender o funcionamento interno descrito acima, as regras de escrita decorrem naturalmente. As recomendações da documentação oficial podem ser resumidas assim.

Regra 1. queryKey precisa ser um vetor.

Mesmo que uma cadeia de caracteres funcione (ela é convertida internamente em um vetor), é melhor usar um vetor desde o início para manter a consistência.

// 비권장
useQuery({ queryKey: 'todos', queryFn });
 
// 권장
useQuery({ queryKey: ['todos'], queryFn });

Regra 2. Inclua em queryKey todas as variáveis das quais queryFn depende.

// 잘못된 예: userId가 쿼리키에 없다
useQuery({
  queryKey: ['user'],
  queryFn: () => fetchUser(userId),
});
 
// 올바른 예
useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

O raciocínio é idêntico ao das dependências de useEffect. Todas as variáveis usadas dentro da função precisam estar na chave, isto é, no vetor de dependências. Se essa regra for violada, pode surgir um erro difícil de rastrear: o usuário muda, mas os dados do usuário anterior continuam aparecendo.

Regra 3. Organize os elementos do mais genérico para o mais específico.

// 좋다
['todos', 'list', { filter: 'done' }]
['todos', 'detail', todoId]
 
// 안 좋다 (순서가 뒤집혀 있음)
[{ filter: 'done' }, 'list', 'todos']

Essa ordem é importante por causa da invalidação (invalidation). Por padrão, invalidateQueries do TanStack Query usa correspondência por prefixo.

// 모든 todos 관련 쿼리 무효화
queryClient.invalidateQueries({ queryKey: ['todos'] });
// → ['todos', 'list', ...], ['todos', 'detail', ...] 모두 매치된다
 
// list 쿼리만 무효화
queryClient.invalidateQueries({ queryKey: ['todos', 'list'] });
// → ['todos', 'list', ...]만 매치된다

Ao projetar as chaves como uma árvore, torna-se possível expressar em uma única linha desde "busque novamente todos os dados deste domínio" até "busque novamente apenas este item específico". (À primeira vista, isso pode parecer pouco relevante; mas basta projetar mal uma vez e ver a invalidação atingir um escopo diferente do pretendido para perceber seu verdadeiro valor.)

Evolução do gerenciamento de queryKey

Até aqui, tratamos do funcionamento e do uso de queryKey. Agora podemos passar à pergunta principal: como o gerenciamento de queryKey mudou ao longo do tempo?

Vou organizar em ordem cronológica as etapas pelas quais passei em projetos reais.

1. Vetores declarados diretamente

Esta é a forma mais simples. Dentro do componente, combinam-se textos fixos com valores das propriedades.

function UserProfile({ userId }: { userId: string }) {
  const { data } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });
  // ...
}
 
function PostList({ filter }: { filter: PostFilter }) {
  const { data } = useQuery({
    queryKey: ['posts', filter],
    queryFn: () => fetchPosts(filter),
  });
  // ...
}

No início, isso pode ser suficiente.

O problema aparece à medida que a base de código cresce. Quando se precisa invalidar dados em uma mutação que altera informações de um usuário, é necessário pesquisar toda vez: "Qual era a chave das consultas de usuário?" Alguns lugares acabam usando ['user', userId], enquanto outros usam ['users', userId], no plural. Como essas chaves ocupam posições totalmente diferentes no cache, a invalidação afeta apenas uma delas.

2. Objeto de constantes

Para evitar erros de digitação, as chaves de consulta são reunidas em constantes.

// queryKeys.ts
export const QUERY_KEYS = {
  USER: 'user',
  POSTS: 'posts',
  COMMENTS: 'comments',
} as const;
 
// 사용처
useQuery({
  queryKey: [QUERY_KEYS.USER, userId],
  queryFn: () => fetchUser(userId),
});

Os erros de digitação desaparecem, mas a responsabilidade de montar as chaves continua nos locais de uso. Alguém escreve a combinação [QUERY_KEYS.USER, userId] como [QUERY_KEYS.USER, userId, 'detail'], enquanto outra pessoa usa ['user', 'detail', userId]. Chega um momento em que é necessário memorizar à parte qual convenção está correta.

3. Fábrica de chaves de consulta

Esse padrão foi concretizado no artigo Chaves eficazes no React Query, de TkDodo. Define-se um objeto que cria as chaves de cada domínio, expressando a hierarquia por meio de funções.

// features/todos/queries.ts
const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
};
 
// 사용
useQuery({ queryKey: todoKeys.detail(1), queryFn: ... });
useQuery({ queryKey: todoKeys.list('done'), queryFn: ... });
 
// 무효화
queryClient.invalidateQueries({ queryKey: todoKeys.all });        // 전체
queryClient.invalidateQueries({ queryKey: todoKeys.lists() });    // 모든 리스트
queryClient.invalidateQueries({ queryKey: todoKeys.detail(1) });  // 특정 항목

Esse padrão é poderoso porque torna a hierarquia explicitamente visível no código. todoKeys.all representa todas as consultas relacionadas a tarefas, todoKeys.lists() representa todas as consultas em formato de lista, e todoKeys.detail(1) representa um item específico. Assim, o escopo da invalidação pode ser expresso com precisão em uma única linha de código.

Outra vantagem é a colocalização (co-location). TkDodo não recomenda reunir as chaves em um arquivo global. Em vez disso, recomenda colocar queries.ts dentro do diretório do recurso e manter juntos, nesse arquivo, as chaves e os hooks.

src/
└── features/
    └── todos/
        ├── index.tsx
        └── queries.ts   # 키와 훅을 모두 여기에

Isso cria um modelo mental simples: "Para alterar algo em tarefas, basta olhar a pasta de tarefas". É uma aplicação fiel do princípio de manter juntas as partes que mudam juntas.

4. @lukemorales/query-key-factory

Ao escrever manualmente o terceiro padrão repetidas vezes, o código repetitivo se acumula. Além disso, quando surge a necessidade de combinar e gerenciar as chaves de vários domínios, faz falta uma interface padronizada. A biblioteca @lukemorales/query-key-factory é o resultado da transformação desse padrão em biblioteca.

import { createQueryKeys, mergeQueryKeys } from '@lukemorales/query-key-factory';
 
const users = createQueryKeys('users', {
  detail: (userId: string) => ({
    queryKey: [userId],
    queryFn: () => api.getUser(userId),
  }),
  list: (filters: UserFilters) => ({
    queryKey: [{ filters }],
    queryFn: () => api.getUsers(filters),
  }),
});
 
const todos = createQueryKeys('todos', {
  detail: (id: number) => ({
    queryKey: [id],
    queryFn: () => api.getTodo(id),
  }),
});
 
export const queries = mergeQueryKeys(users, todos);
 
// 사용
useQuery(queries.users.detail('abc'));
useQuery(queries.todos.detail(1));
 
// 무효화
queryClient.invalidateQueries(queries.users._def);            // 모든 user 쿼리
queryClient.invalidateQueries(queries.users.detail('abc'));   // 특정 항목

createQueryKeys adiciona automaticamente o prefixo, e mergeQueryKeys permite combinar domínios. Além disso, a propriedade convencionada _def dá acesso à chave de todo o domínio. Com isso, desaparece o trabalho de acrescentar as const a cada vez e restringir manualmente os tipos, como era necessário na fábrica artesanal.

Durante algum tempo, essa biblioteca foi usada praticamente como um padrão de mercado. (Eu também a usei bastante.) Mas a chegada de queryOptions mudou o cenário.

5. queryOptions (API oficial da v5)

Uma das mudanças mais importantes do TanStack Query v5 foi a introdução da API queryOptions. Na migração da v4 para a v5, os argumentos de todos os hooks foram unificados em um único objeto. O verdadeiro objetivo dessa mudança era permitir que esse objeto fosse extraído como uma unidade reutilizável.

import { queryOptions } from '@tanstack/react-query';
 
export const userDetailOptions = (userId: string) =>
  queryOptions({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 5 * 60 * 1000,
  });
 
// 어디서나 사용 가능
useQuery(userDetailOptions('abc'));
useSuspenseQuery(userDetailOptions('abc'));
queryClient.prefetchQuery(userDetailOptions('abc'));
queryClient.setQueryData(userDetailOptions('abc').queryKey, newUser);

À primeira vista, pode surgir a dúvida: "O que há de diferente? Parece apenas um objeto envolvido por uma função." TkDodo reconhece esse ponto no artigo A API Query Options. Em tempo de execução, ela realmente se limita a devolver o objeto recebido.

O trabalho realmente útil acontece dentro do sistema de tipos. Veremos isso a seguir.

DataTag de queryOptions

O motivo pelo qual queryOptions não é apenas uma função auxiliar é que ela incorpora informações sobre o tipo dos dados na queryKey retornada. Dentro do TanStack Query, esse mecanismo é chamado de DataTag.

Sua implementação aproximada é esta.

declare const dataTagSymbol: unique symbol;
declare const dataTagErrorSymbol: unique symbol;
 
export type DataTag<TType, TValue, TError = unknown> = TType & {
  [dataTagSymbol]: TValue;
  [dataTagErrorSymbol]: TError;
};

Trata-se de um tipo marcado (branded type) que usa unique symbol. Em tempo de execução, é apenas uma marca sem efeito algum; para o TypeScript, porém, ela carrega a informação de que "este vetor não é um vetor qualquer, mas um vetor associado a dados do tipo TValue".

Há um motivo específico para usar unique symbol. O artigo da Zenn Revelando o unique symbol por trás de DataTag compara esse recurso a "uma vaga exclusiva para informações de tipo". Uma chave de texto comum poderia colidir com chaves de outras bibliotecas ou do código do usuário; no entanto, cada declaração de unique symbol cria por si só um tipo exclusivo e, portanto, nunca tem o mesmo tipo de qualquer outra declaração. Ela se torna um identificador sem possibilidade de colisão.

A diferença produzida por esse único recurso é significativa.

const data = queryClient.getQueryData(['user', 'abc']); // unknown
const data = queryClient.getQueryData(userDetailOptions('abc').queryKey); // User | undefined

Embora getQueryData e setQueryData recebam apenas uma queryKey, a própria queryKey já contém o tipo dos dados; por isso, o tipo de retorno é inferido automaticamente. Não é necessário fornecer parâmetros genéricos manualmente, e o compilador aponta imediatamente uma tentativa de passar a setQueryData um valor de tipo incorreto.

É claro que existem limitações. Em métodos como getQueriesData, que recuperam várias consultas de uma vez, o resultado é um vetor heterogêneo de tuplas e a inferência de tipos não se aplica. Além disso, como a implementação usa unique symbol, a geração de arquivos .d.ts em um monorrepositório pode causar o erro TS4023; uma forma de contorná-lo é importar explicitamente dataTagSymbol.

Ao resumir o mecanismo até aqui, um fato fica claro. A inferência de tipos de queryOptions depende inteiramente de queryKey e queryFn serem declaradas juntas no mesmo lugar. Para incorporar em queryKey o tipo retornado por queryFn, ambas precisam ser declaradas lado a lado.

Esse ponto traz uma implicação importante para o rumo das fábricas de chaves de consulta. Os padrões das gerações anteriores davam prioridade a extrair a gestão de queryKey como uma unidade de abstração separada. A recomendação da v5 segue a direção oposta: reunir novamente queryKey e queryFn em uma única unidade. TkDodo chega a dizer que "separar queryKey de queryFn foi um erro". Afinal, a chave é o conjunto das dependências usadas pela função, e as duas têm uma relação inseparável.

Padrão de composição com queryOptions em projetos reais

O verdadeiro valor de queryOptions aparece quando ela é combinada a uma fábrica por domínio. A forma recomendada pela documentação oficial da v5 é esta.

import { queryOptions } from '@tanstack/react-query';
 
export const todoQueries = {
  all: () => ['todos'] as const,
  lists: () => [...todoQueries.all(), 'list'] as const,
  list: (filters: TodoFilters) =>
    queryOptions({
      queryKey: [...todoQueries.lists(), filters],
      queryFn: () => fetchTodos(filters),
      staleTime: 30 * 1000,
    }),
  details: () => [...todoQueries.all(), 'detail'] as const,
  detail: (id: number) =>
    queryOptions({
      queryKey: [...todoQueries.details(), id],
      queryFn: () => fetchTodo(id),
      staleTime: 5 * 60 * 1000,
    }),
};

Vejamos, um a um, os motivos pelos quais esse padrão funciona bem.

1. Ele oferece, ao mesmo tempo, uma hierarquia e inferência de tipos.

todoQueries.all() e todoQueries.lists() retornam apenas vetores, enquanto todoQueries.detail(1) retorna, por meio de queryOptions, um objeto com a marca de tipo dos dados. Usa-se o vetor para invalidar e o objeto de opções para executar a consulta.

useQuery(todoQueries.detail(1));                                // 옵션 객체
queryClient.invalidateQueries({ queryKey: todoQueries.all() }); // 배열

2. O componente pode sobrescrever parcialmente as opções.

Como o resultado de queryOptions é, no fim das contas, um objeto, algumas opções podem ser combinadas no momento da chamada.

const { data: title } = useQuery({
  ...todoQueries.detail(1),
  select: (todo) => todo.title,  // 컴포넌트별로 다른 select 적용
});

Esse padrão é especialmente poderoso porque o tipo retornado por select é inferido automaticamente e o tipo de data é restringido para string. Do ponto de vista do componente, é possível selecionar apenas a parte necessária, mantendo a definição do domínio intacta em um só lugar.

3. Hooks personalizados que envolvem useQuery tornam-se cada vez menos necessários.

Na época da v4, um padrão comum era criar um hook personalizado para cada domínio.

O problema dessa abordagem era que, assim que surgia a necessidade de fazer uma busca antecipada, era preciso escrever a mesma definição outra vez. Como useTodoDetail é um hook, ele não pode ser chamado fora de um componente; portanto, no carregador de uma rota ou em um manipulador de eventos, era necessário escrever novamente queryClient.prefetchQuery({ queryKey: [...], queryFn: ... }).

Com queryOptions, essa duplicação desaparece.

Uma única definição funciona em qualquer lugar. Por isso, TkDodo recomenda: "Na v5, defina queryOptions em vez de criar hooks." O hook passa a ser uma camada fina usada apenas quando necessário, e a definição do domínio existe de maneira autossuficiente, sem depender dele.

Invalidação após mutações

É na invalidação após uma mutação que a hierarquia de queryKey realmente se destaca. Segundo a documentação de Invalidação de consultas do TanStack Query, invalidateQueries usa correspondência por prefixo por padrão.

// 모든 todos 관련 쿼리 (list, detail, lists 모두)
queryClient.invalidateQueries({ queryKey: todoQueries.all() });
 
// 모든 list만 (detail은 건드리지 않음)
queryClient.invalidateQueries({ queryKey: todoQueries.lists() });
 
// 정확히 이 키만 (자식 키 매치 안 함)
queryClient.invalidateQueries({
  queryKey: todoQueries.detail(1).queryKey,
  exact: true,
});
 
// 더 복잡한 조건은 predicate으로
queryClient.invalidateQueries({
  predicate: (query) =>
    query.queryKey[0] === 'todos' &&
    (query.queryKey[2] as any)?.version >= 10,
});

Quando as chaves são projetadas hierarquicamente, o escopo da invalidação corresponde ao significado do código. "Atualize todas as tarefas" é expresso com all(), "atualize apenas as listas" com lists(), e "atualize somente este item" com detail(id).

Se as chaves estivessem espalhadas de forma plana, como ['todoList'] e ['todoDetail', 1], seria preciso fazer duas chamadas separadas para invalidar "todo o domínio de tarefas" ou criar e gerenciar uma constante de prefixo específica. (E, sempre que uma nova chave do domínio fosse adicionada sem que alguém se lembrasse de incluí-la nessa constante, surgiria um erro por omissão na invalidação.)

Recuperando queryKey dentro de queryFn

Por fim, há mais um padrão a considerar. queryFn recebe como argumento um objeto chamado QueryFunctionContext, que contém exatamente a queryKey usada no momento da chamada.

queryOptions({
  queryKey: ['user', userId, { include: 'profile' }] as const,
  queryFn: ({ queryKey }) => {
    const [, id, options] = queryKey;
    return fetchUser(id, options);
  },
});

Por que esse padrão é útil? Segundo o artigo de TkDodo Aproveitando o contexto da função de consulta, ele permite forçar a sincronização entre as dependências de queryKey e queryFn.

const sortBy = 'name';
 
queryOptions({
  queryKey: ['users'],
  queryFn: () => fetchUsers({ sortBy }),
});

Esse código é perigoso porque queryFn depende de uma variável externa. Além disso, mesmo que sortBy mude, o cache não será atualizado, pois essa dependência não foi incluída na chave. Enquanto queryFn capturar variáveis de um fechamento externo, esse tipo de erro poderá acontecer a qualquer momento.

A solução é simples: fazer com que queryFn não dependa de variáveis externas. Se todas as dependências forem extraídas de queryKey, uma variável ausente na chave simplesmente não poderá ser usada dentro da função.

queryOptions({
  queryKey: ['users', { sortBy }] as const,
  queryFn: ({ queryKey: [, { sortBy }] }) => fetchUsers({ sortBy }),
});

Com essa estrutura, quando surge uma nova dependência, não há como usá-la na função sem incluí-la em queryKey. O compilador avisa: "Essa chave não existe." Em vez de depender de uma convenção, a sincronização entre chave e função é delegada ao sistema de tipos.

Até que ponto separar

Depois de ler até aqui, pode surgir a pergunta: "Então todas as consultas devem ser extraídas para queryOptions?"

Como sempre, minha resposta é: "Depende da situação."

É importante lembrar que uma abstração nem sempre é benéfica. Se uma consulta é usada apenas uma vez, extraí-la à força para uma fábrica de domínio só obriga quem lê o código a alternar entre dois arquivos. A evolução dos padrões de gerenciamento de queryKey não significa que "a ferramenta mais sofisticada deve ser usada sempre", mas que "há a opção de subir um degrau de cada vez quando surgir a necessidade".

Conclusão

Em resumo, queryKey é a unidade mais fundamental usada pelo TanStack Query para identificar e armazenar dados assíncronos em cache. Nesse pequeno vetor estão condensados o identificador de uma posição no cache, o vetor de dependências, o escopo de invalidação e, desde a v5, até informações sobre o tipo dos dados. Como tantas responsabilidades convergem para esse único ponto, a maneira de escrever e gerenciar queryKey afeta diretamente a carga cognitiva de toda a base de código.

Cada etapa foi uma resposta a um problema real enfrentado por alguém naquele momento. Portanto, o caminho correto não é simplesmente pensar: "Agora estamos na v5, então sempre devemos usar apenas queryOptions", mas "Que tipo de problema minha base de código enfrenta neste momento?" Introduzir uma fábrica de domínio em um projeto para o qual vetores declarados diretamente já são suficientes pode, por si só, ser um excesso de engenharia.

Espero que quem leu este artigo também examine seu próprio projeto: como queryKey está espalhada pela base de código, como as invalidações são realizadas e se essa estrutura é adequada ao tamanho atual da equipe e à complexidade do domínio.

Referências

Ao escrever código de tratamento de erros no trabalho, muitas vezes fiquei com uma incômoda sensação de que algo não estava certo. Alguns erros eram capturados com try/catch, outros por ErrorBoundary, e outros ainda pelo onError do TanStack Query. Além disso, os limites de atuação de cada recurso se sobrepunham ou deixavam pequenas lacunas. Em certos dias, um erro escapava; em outros, propagava-se até onde eu não queria.

O problema é que raramente paramos para organizar, de uma só vez, como todas essas ferramentas funcionam. Sabemos que “Error Boundary só captura erros durante a renderização”, mas, se alguém pedir para explicar exatamente o que isso significa na prática, o que acontece internamente ao chamar reset ou em que momento o TanStack Query relança um erro quando throwOnError está habilitado, a resposta já não vem com tanta facilidade.

Com base no guia oficial do React, na biblioteca react-error-boundary e na documentação oficial do TanStack Query v5, este artigo organiza até onde vai a responsabilidade de cada ferramenta de tratamento de erros no frontend e como combiná-las.

Erros que o React consegue e não consegue capturar

Vamos começar pela pergunta mais básica: quais erros o React captura?

A documentação oficial do React distingue com clareza os erros que uma Error Boundary consegue capturar daqueles que ficam fora de seu alcance.

O que uma Error Boundary captura

• Erros ocorridos durante a renderização de componentes filhos
• Erros ocorridos em métodos do ciclo de vida
• Erros ocorridos no construtor

O que uma Error Boundary não captura

• Erros dentro de manipuladores de eventos
• Erros em código assíncrono, como setTimeout, requestAnimationFrame e Promise
• Erros durante a renderização no servidor (SSR)
• Erros ocorridos na própria Error Boundary

Por que essa distinção é importante? Porque a maioria dos erros com que lidamos no dia a dia pertence, na verdade, à segunda categoria. O servidor pode responder com 500 após um clique disparar uma mutação; uma busca de dados pode falhar dentro de useEffect; ou a lógica de validação pode lançar um erro durante o envio de um formulário. O React não captura esses erros automaticamente. Precisamos capturá-los e tratá-los de forma explícita.

Por isso, o tratamento de erros no frontend se divide em dois caminhos: erros de renderização ficam a cargo da Error Boundary; os demais, de try/catch ou das funções de retorno fornecidas pelas bibliotecas. No ponto em que esses caminhos se cruzam, bibliotecas de gerenciamento de estado assíncrono, como o TanStack Query, funcionam como uma ponte.

O que é uma Error Boundary

No fim das contas, uma Error Boundary é um componente de classe com dois métodos de ciclo de vida. Segundo a documentação oficial do React, para que um componente seja uma Error Boundary, ele precisa implementar um dos dois métodos abaixo — normalmente, ambos.

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }
 
  // 에러 발생 시 state를 업데이트해 다음 렌더에서 fallback UI를 보여준다
  static getDerivedStateFromError(error) {
    return { hasError: true };
  }
 
  // 에러가 발생한 직후에 호출. 로깅 같은 사이드이펙트는 여기서 처리한다
  componentDidCatch(error, info) {
    logErrorToMyService(error, info.componentStack);
  }
 
  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

getDerivedStateFromError deve ser uma função pura. Sua única função é retornar o novo estado, sem efeitos colaterais. Já componentDidCatch é o lugar destinado aos efeitos colaterais. É ali que enviamos o erro ao Sentry ou registramos a pilha de componentes no console.

Há um ponto importante: esses dois métodos só existem em componentes de classe. Ainda não há uma forma oficial de criar uma Error Boundary como componente funcional. A documentação oficial do React deixa isso explícito.

Atualmente, não há como escrever uma Error Boundary como componente funcional.

There is currently no way to write an Error Boundary as a function component.

Como é trabalhoso escrever um componente de classe do zero toda vez, normalmente recorremos à biblioteca react-error-boundary. Ela foi criada por Brian Vaughn, ex-membro da equipe principal do React, e é usada praticamente como um padrão.

As três formas de definir a interface de contingência em react-error-boundary

Em react-error-boundary, o componente ErrorBoundary oferece três formas de definir a propriedade da interface de contingência. Vejamos rapidamente como cada uma é usada.

fallback

É a forma mais simples: basta passar um JSX estático.

<ErrorBoundary fallback={<div>문제가 발생했습니다.</div>}>
  <Page />
</ErrorBoundary>

É útil quando não precisamos acessar o objeto de erro nem a função de reinicialização. Como normalmente precisamos exibir uma mensagem ou oferecer uma ação de nova tentativa, ainda não tive ocasião de usar essa opção em produção.

FallbackComponent

Separamos a interface de contingência em outro componente e passamos a referência desse componente.

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>오류가 발생했습니다.</p>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  );
}
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Page />
</ErrorBoundary>

O objeto de erro e a função resetErrorBoundary são injetados automaticamente por meio de propriedades. Essa opção é adequada quando existe a possibilidade de reutilizar a interface de contingência em outros lugares.

fallbackRender

É a opção usada quando queremos escrever a interface de contingência diretamente no local de uso.

<ErrorBoundary
  fallbackRender={({ error, resetErrorBoundary }) => (
    <div role="alert">
      <p>오류가 발생했습니다: {error.message}</p>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  )}
>
  <Page />
</ErrorBoundary>

Na essência, faz o mesmo que FallbackComponent, mas permite tratar tudo diretamente no local de uso, sem criar um componente separado. É útil quando precisamos acessar o escopo léxico externo, como o estado ou um manipulador do componente pai.

Não existe uma única resposta correta entre as três opções. O padrão que mais uso em produção é criar um componente ErrorFallback comum e injetá-lo por meio de FallbackComponent, porque o sistema de design e o tom da interface precisam ser consistentes. Só escrevo a interface de contingência diretamente no local de uso com fallbackRender quando uma página exige um tratamento diferente.

O que a reinicialização realmente faz?

Ao usar react-error-boundary, inevitavelmente encontramos a função resetErrorBoundary: aquela chamada quando o usuário clica no botão “Tentar novamente” da interface de contingência. Vejamos o que ela realmente faz.

Em resumo, resetErrorBoundary apenas sinaliza ao componente ErrorBoundary que ele deve reinicializar o próprio estado e renderizar novamente os componentes filhos. Ela não altera automaticamente nenhum estado externo, como o cache do TanStack Query.

Internamente, a sequência é a seguinte.

1. resetErrorBoundary() é chamada.
2. O estado hasError interno da ErrorBoundary volta a false.
3. Opcionalmente, a função de retorno onReset é executada. É aqui que ocorrem os efeitos colaterais definidos pela aplicação.
4. Os componentes filhos são renderizados novamente. Se a causa do erro — estado, cache ou outra condição — continuar presente, o mesmo erro será lançado outra vez.

O quarto item é o ponto central. Reinicializar significa apenas “vamos esquecer o erro e tentar renderizar de novo”; não significa “vamos corrigir a causa do erro”. Por isso, apenas reinicializar pode repetir o mesmo erro indefinidamente.

Há mais duas ferramentas para resolver esse problema.

onReset

Funciona como um hook chamado imediatamente antes da reinicialização. Nele, limpamos o estado externo que causou o erro.

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  onReset={() => {
    queryClient.invalidateQueries({ queryKey: ['user'] });
  }}
>
  <Page />
</ErrorBoundary>

resetKeys

A ErrorBoundary é reinicializada automaticamente quando os valores da lista mudam. Podemos passar parâmetros da URL, termos de busca, a aba selecionada ou qualquer outra chave cuja mudança indique que vale a pena tentar novamente.

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  resetKeys={[userId]}
>
  <UserProfile userId={userId} />
</ErrorBoundary>

Quando userId muda, a reinicialização ocorre automaticamente e os componentes filhos são renderizados de novo. Ao navegar para outro perfil, o erro anterior desaparece de forma natural.

Como capturar erros de manipuladores de eventos e de código assíncrono?

Como vimos, uma Error Boundary não captura erros em manipuladores de eventos nem em código assíncrono. Mas é justamente aí que ocorre a maioria dos erros com que lidamos. O que fazer, então?

Para esse caso, react-error-boundary oferece o hook useErrorBoundary. Ele retorna uma função chamada showBoundary; ao chamá-la, podemos encaminhar o erro à ErrorBoundary mais próxima.

import { useErrorBoundary } from 'react-error-boundary';
 
function MyComponent() {
  const { showBoundary } = useErrorBoundary();
 
  const handleClick = async () => {
    try {
      await someAsyncOperation();
    } catch (error) {
      showBoundary(error);
    }
  };
 
  return <button onClick={handleClick}>실행</button>;
}

O ponto central é que o desenvolvedor precisa elevar o erro explicitamente. O React não faz isso por conta própria. Para levar um erro assíncrono até o domínio de uma ErrorBoundary, é preciso capturá-lo com try/catch e passá-lo a showBoundary.

Entender esse padrão esclarece por que uma ErrorBoundary captura alguns erros e não outros. A resposta é simples: “o erro foi elevado até a fase de renderização ou não?”

Como o TanStack Query trata erros?

Depois de organizar tudo até aqui, surge naturalmente outra pergunta. O useQuery que usamos todos os dias lida com requisições assíncronas; como são tratados os erros que ocorrem dentro dele?

Por padrão, o TanStack Query expõe o erro no campo error.

const { data, error, isError } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
});
 
if (isError) {
  return <div>에러: {error.message}</div>;
}

Essa é a forma mais simples. Mesmo quando ocorre um erro, o componente continua renderizando normalmente; apenas o campo error recebe um valor. A ErrorBoundary não participa desse fluxo.

Vale destacar um fato importante: o comportamento padrão do TanStack Query é “não lançar o erro”. Não importa se a queryFn lança uma exceção ou rejeita uma Promise: o erro é armazenado no campo error sem interromper o fluxo de renderização do React. Portanto, sem nenhuma configuração adicional, a ErrorBoundary nunca será acionada.

Além disso, por padrão, o TanStack Query repete automaticamente uma consulta com erro três vezes.

O retryDelay padrão usa intervalos exponenciais, chegando a no máximo 30 segundos. Isso significa que o erro não aparece para o usuário assim que ocorre a primeira falha. A consulta é repetida após intervalos de 1, 2 e 4 segundos; somente se todas as tentativas falharem o campo error é preenchido. Se você já se perguntou durante o desenvolvimento “por que o erro demora para aparecer?”, é quase certo que esse seja o motivo.

Conectando à ErrorBoundary com throwOnError

Como encaminhar, então, os erros do TanStack Query para uma ErrorBoundary? A resposta é a opção throwOnError. Até a v4, ela se chamava useErrorBoundary; na v5, passou a se chamar throwOnError.

const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  throwOnError: true,
});

Quando essa opção está habilitada, o TanStack Query relança o erro no próximo ciclo de renderização. O lançamento passa, então, a ser um erro da fase de renderização, que finalmente pode ser capturado pela ErrorBoundary.

throwOnError também pode receber uma função. Assim, podemos encaminhar alguns erros à ErrorBoundary e deixar que o próprio componente trate os demais.

useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  // 5xx 서버 에러만 ErrorBoundary로 보낸다
  throwOnError: (error) => error.response?.status >= 500,
});

Esse padrão é prático porque erros de cliente 4xx, como falha de validação ou falta de permissão, normalmente devem ser exibidos no próprio contexto em que ocorreram, enquanto erros de servidor 5xx justificam cobrir a página inteira e mostrar uma mensagem como “Tente novamente em alguns instantes”.

useSuspenseQuery

Se você usa useSuspenseQuery, não precisa se preocupar com throwOnError. No modo Suspense, lançar o erro sempre é o comportamento padrão.

Em outras palavras, usar useSuspenseQuery significa delegar o carregamento ao Suspense e os erros à ErrorBoundary. Deixamos de precisar de ramificações como if (isError) ou if (isLoading) dentro do componente e passamos a envolvê-lo externamente com esses dois limites.

QueryErrorResetBoundary

Neste ponto, surge mais uma pergunta: o que acontece quando o usuário clica em “Tentar novamente” na interface de contingência?

Como vimos, resetErrorBoundary apenas reinicializa o estado hasError da ErrorBoundary. Porém, no cache do TanStack Query, continua existindo uma consulta presa no estado de erro. Quando os componentes filhos são renderizados novamente, o TanStack Query consulta o cache, conclui que a consulta já falhou e lança o mesmo erro imediatamente. É um ciclo infinito infernal.

Para resolver esse problema, o TanStack Query oferece o hook useQueryErrorResetBoundary e o componente QueryErrorResetBoundary. Apesar dos nomes longos, a função é simples: emitir o comando “reinicialize o estado de erro das consultas dentro deste escopo”.

import { useQueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
 
function App() {
  const { reset } = useQueryErrorResetBoundary();
 
  return (
    <ErrorBoundary
      onReset={reset}
      fallbackRender={({ resetErrorBoundary }) => (
        <div>
          <p>에러가 발생했습니다.</p>
          <button onClick={resetErrorBoundary}>다시 시도</button>
        </div>
      )}
    >
      <Page />
    </ErrorBoundary>
  );
}

Vejamos em ordem cronológica o que acontece aqui.

1. O usuário clica em “Tentar novamente” → resetErrorBoundary() é chamada
2. A ErrorBoundary executa a função de retorno onReset → reset() é chamada, reinicializando o estado de erro do TanStack Query
3. A ErrorBoundary reinicializa o próprio estado e renderiza os componentes filhos novamente
4. O useQuery dentro dos componentes filhos é executado → como o estado de erro foi removido, uma nova busca de dados é iniciada

O ponto central é a conexão feita em onReset com reset. Graças a essa única linha, a ErrorBoundary e o TanStack Query sincronizam seus estados.

Usando a forma de componente

É possível fazer a mesma coisa com um componente em vez do hook. Basta escolher uma das duas formas.

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
 
function App() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={({ error, resetErrorBoundary }) => (
            <div role="alert">
              <p>에러가 발생했습니다: {error.message}</p>
              <button onClick={resetErrorBoundary}>다시 시도</button>
            </div>
          )}
        >
          <Page />
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

A maior diferença em relação à versão em hook é que a função reset é passada aos filhos por meio do padrão de propriedade de renderização. QueryErrorResetBoundary recebe uma função como conteúdo filho, passa { reset } como argumento e renderiza o valor retornado por essa função. Assim, podemos conectá-la imediatamente com onReset={reset} dentro do componente.

Quando não há uma QueryErrorResetBoundary próxima, a versão em hook reinicializa os erros do cache global. A versão em componente restringe o escopo da reinicialização à própria subárvore. Para controlar esse alcance de forma mais granular, a versão em componente é mais segura.

Vale ressaltar um ponto: a reinicialização não limpa o cache. Em vez de apagar todos os dados, ela apenas libera o estado das consultas marcadas com erro. Para invalidar os dados de fato, é preciso chamar queryClient.invalidateQueries() separadamente.

Erros de mutações

Quase todos os padrões apresentados até aqui partiram de useQuery. Com useMutation, porém, a situação é um pouco diferente.

A principal diferença é que uma mutação normalmente começa com uma ação explícita do usuário, como um clique ou envio de formulário. Por isso, é natural tratar o erro perto dessa ação. Em vez de cobrir a página inteira com uma interface de contingência, faz mais sentido mostrar uma notificação ou um texto de erro ao lado do formulário, como “Falha no pagamento: confira novamente os dados do cartão”.

Em Dominando mutações no React Query, TkDodo resume a essência dessa diferença em uma frase: uma consulta é declarativa, enquanto uma mutação é imperativa. Uma consulta é executada automaticamente quando o componente é montado, pode ser observada por outros componentes com a mesma chave e é armazenada em cache para reutilização. Já uma mutação só é executada quando o usuário aciona uma operação, não é armazenada em cache e fica vinculada individualmente à instância do componente que a chamou. Essa diferença fundamental separa também as estratégias de tratamento de erros.

No useQuery, o retry padrão é 3, mas no useMutation o retry padrão é 0. O motivo é simples: uma mutação produz efeitos colaterais. Se uma requisição de pagamento falhar por esgotamento do tempo de espera da rede e a biblioteca repetir a chamada automaticamente mais duas vezes, o cartão do usuário poderá ser cobrado três vezes.

Por isso, a regra é habilitar novas tentativas para mutações de forma explícita apenas quando for possível garantir que a operação é idempotente. Isso vale para leituras seguras semelhantes a GET, nas quais repetir a requisição produz comprovadamente o mesmo resultado, ou para casos em que o servidor impede duplicações por meio de uma chave de idempotência.

Os erros de useQuery ficam registrados no cache. Assim, propagam-se imediatamente para outros componentes que observam a mesma queryKey, exigindo um mecanismo como QueryErrorResetBoundary para reinicializá-los em conjunto.

Com mutações é diferente. Um erro em uma instância de mutação permanece apenas no estado daquela instância. Ele não afeta a mutação de outro componente que use a mesma mutationFn. Por isso, o TanStack Query não tem algo como MutationErrorResetBoundary: não há necessidade.

Essa diferença tem uma consequência prática. Quando dois componentes chamam o mesmo useMutation, o erro ocorrido em um deles não aparece no outro. Para observar “os erros dessa mutação em toda a aplicação”, o onError no nível do componente não basta; é preciso elevá-los por meio de MutationCache.onError.

mutate vs mutateAsync

useMutation retorna duas funções de execução. A diferença entre elas determina a forma de tratar erros.

O tipo de retorno de mutate é void. Ela não retorna uma Promise. Portanto, não podemos aguardar o resultado com await, e ele só pode ser recebido por funções de retorno como onSuccess/onError.

const mutation = useMutation({
  mutationFn: createPost,
  onError: (error) => {
    toast.error(`등록 실패: ${error.message}`);
  },
});
 
mutation.mutate(newPost);

Já mutateAsync retorna uma Promise. Isso permite tratar o erro com try/catch.

const mutation = useMutation({ mutationFn: createPost });
 
const handleSubmit = async () => {
  try {
    const result = await mutation.mutateAsync(newPost);
    router.push(`/posts/${result.id}`);
  } catch (error) {
    // 여기서 처리
  }
};

Quando usar cada uma? Adoto os seguintes critérios.

• Há uma ação subsequente após o fim da mutação, como navegar em caso de sucesso ou usar o valor retornado → mutateAsync
• Basta disparar a chamada e delegar os efeitos colaterais às funções de retorno, como alternar uma curtida ou apenas exibir uma notificação → mutate + onError

Há um erro comum nesse ponto: usar mutateAsync sem try/catch causa uma rejeição de promessa não tratada. A função mutate, baseada em funções de retorno, absorve o erro internamente; mutateAsync, por sua vez, lança o erro para o chamador por padrão. Misturar as duas abordagens sem conhecer essa diferença enche o console de alertas vermelhos.

onError

Outro detalhe frequentemente ignorado é que, em useMutation, onError pode ser definido em dois lugares: no hook e em mutate.

const mutation = useMutation({
  mutationFn: createPost,
  onError: (error) => {
    Sentry.captureException(error);
  },
});

No nível do hook, ele sempre é executado; no nível de mutate, é executado apenas no momento da chamada.

mutation.mutate(newPost, {
  onError: (error) => {
    setFormError(error.message);
  },
});

A ordem de execução indicada pela documentação oficial é: nível do hook → nível de mutate. Quando as duas funções de retorno estão definidas, a do hook é executada primeiro e, depois, a de mutate.

Tratamento global de erros

Até aqui, todos os padrões atuavam no nível do componente. Mas podemos ter requisitos como “registrar todos os erros de consultas em um único lugar” ou “sempre encerrar a sessão ao receber um erro 401”. Para interesses transversais como esses, podemos registrar funções de retorno em QueryCache/MutationCache ao criar o QueryClient.

import { QueryClient, QueryCache, MutationCache } from '@tanstack/react-query';
 
const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      if (query.state.data !== undefined) {
        toast.error(`데이터 갱신 실패: ${error.message}`);
      }
    },
  }),
  mutationCache: new MutationCache({
    onError: (error) => {
      if (error.status === 401) {
        redirectToLogin();
      }
    },
  }),
});

O ponto central é que QueryCache.onError é chamado apenas uma vez por consulta. Mesmo que vários componentes observem a mesma consulta, a função de retorno é executada uma única vez, evitando problemas como notificações duplicadas.

Também podemos verificar query.state.data !== undefined, como no exemplo acima. Quando ocorre uma falha ao buscar novamente enquanto já existem dados em cache, o usuário ainda está vendo os dados na tela. Cobrir a página com uma ErrorBoundary seria excessivo; basta informar que a atualização falhou. Por outro lado, se o primeiro carregamento falhar sem que existam dados em cache, faz sentido a ErrorBoundary capturar o erro e exibir a interface de contingência.

Ao combinar esses dois fluxos, podemos definir uma política clara: “falhas no carregamento inicial vão para a ErrorBoundary; falhas ao buscar novamente em segundo plano geram uma notificação”.

Componente compartilhado

Depois de chegar até aqui, é natural querer evitar envolver cada trecho, toda vez, em três camadas de QueryErrorResetBoundary, ErrorBoundary e Suspense. Que tal reuni-las em um único componente reutilizável?

É uma ideia natural. Eu mesmo já criei e usei um componente AsyncBoundary como o seguinte.

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { Suspense, type ComponentType, type ReactNode } from 'react';
import { ErrorBoundary, type FallbackProps } from 'react-error-boundary';
import { ErrorFallback } from './ErrorFallback';
import { Spinner } from './Spinner';
 
interface Props {
  children: ReactNode;
  pendingFallback?: ReactNode;
  rejectedFallback?: ComponentType<FallbackProps>;
}
 
export function AsyncBoundary({
  children,
  pendingFallback = <Spinner />,
  rejectedFallback = ErrorFallback,
}: Props) {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary onReset={reset} FallbackComponent={rejectedFallback}>
          <Suspense fallback={pendingFallback}>{children}</Suspense>
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}