Cenários de Exemplo de Refatoração

Vinte solicitações de refatoração do mundo real como elas chegam - algumas como comentários de revisão de PR, outras como reclamações de stakeholders que acabam sendo problemas de forma de código, outras como tarefas de limpeza de um tech lead. Cada entrada mostra a solicitação como escrita, o diagnóstico do que está realmente errado, uma refatoração concisa e por que a nova forma é melhor.

Como Usar Esta Lista

• Trate isso como uma lista de verificação: examine os 20 títulos primeiro e marque quais descrevem o código que você mantém no momento.
• A linha "Por que isso funciona" é a parte a memorizar - ela diz quando a mesma refatoração se aplica a um arquivo diferente.
• A maioria das refatorações aqui são do tamanho de um PR. Se um único item se transformar em um projeto de vários dias, o diagnóstico provavelmente está errado.
• Envie uma refatoração por PR. Agrupar uma conversão de Server Component com uma passagem de tipagem torna a revisão hostil.

1. "Este componente tem 800 linhas e ninguém quer mexer nele"

"O arquivo <Dashboard /> continua crescendo a cada sprint. Os revisores gastam 40 minutos em cada PR e ainda perdem coisas. Podemos limpá-lo?"

Diagnóstico: Um componente renderiza o layout, busca três recursos, os formata, rastreia análises e possui quatro pedaços de estado de UI. Viola a responsabilidade única em todos os eixos.

Refatoração:

// app/dashboard/page.tsx (Server Component)
export default async function Page() {
  const [user, metrics, alerts] = await Promise.all([
    getUser(), getMetrics(), getAlerts(),
  ]);
  return <DashboardShell user={user} metrics={metrics} alerts={alerts} />;
}
 
// DashboardShell.tsx
export function DashboardShell({ user, metrics, alerts }: Props) {
  return (
    <Layout>
      <Header user={user} />
      <MetricsPanel metrics={metrics} />
      <AlertsPanel alerts={alerts} />
    </Layout>
  );
}

Por que isso funciona: Cada filho tem um motivo para mudar. Os revisores comparam um painel de cada vez, e o Server Component pode buscar em paralelo sem um useEffect.

2. "Estamos passando user por cinco componentes apenas para lê-lo em um botão"

"A prop currentUser é passada por Layout, Sidebar, Nav, NavItem e, finalmente, LogoutButton. Adicionar um campo ao objeto user significa editar cinco arquivos."

Diagnóstico: Prop drilling. Os componentes intermediários não usam user - eles apenas o encaminham.

Refatoração:

// lib/user-context.tsx
"use client";
const UserContext = createContext<User | null>(null);
export const useUser = () => useContext(UserContext)!;
export function UserProvider({ user, children }: { user: User; children: ReactNode }) {
  return <UserContext.Provider value={user}>{children}</UserContext.Provider>;
}
 
// LogoutButton.tsx
const user = useUser();

Por que isso funciona: O Contexto achata a dependência. Adicionar um novo campo afeta o provider e o consumidor, não os quatro componentes no meio.

3. "A página do produto busca dados dentro do useEffect e exibe um spinner a cada navegação"

"Os usuários reclamam que a página do produto mostra um esqueleto de carregamento por meio segundo, mesmo quando já a visitaram. Podemos torná-la instantânea?"

Diagnóstico: Um Client Component busca em useEffect. O servidor não retorna dados, o cliente monta e, em seguida, busca. O flash é inevitável nesta forma.

Refatoração:

// app/products/[id]/page.tsx
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await getProduct(id);
  return <ProductView product={product} />;
}

Por que isso funciona: Mover a busca para um Server Component incorpora os dados na primeira resposta HTML. Sem spinner, sem cascata do cliente, sem useEffect.

4. "Todo o nosso painel está marcado como \"use client\" e o bundle JS tem 600 KB"

"Lighthouse diz que enviamos 600 KB de JS para uma página que é em sua maioria conteúdo estático. O tech lead sinalizou que tudo é um Client Component."

Diagnóstico: "use client" está no topo do wrapper da rota. Cada título estático, barra lateral e rodapé viaja para o navegador como JS.

Refatoração:

// app/dashboard/page.tsx - sem diretiva
export default function Page() {
  return (
    <Layout>
      <Header /><Sidebar />
      <InteractiveChart />{/* este é "use client" */}
    </Layout>
  );
}

Por que isso funciona: A fronteira vive na menor folha interativa. O markup estático permanece no servidor e é enviado como HTML, não JS.

5. "Existem strings codificadas 'admin' e 'editor' em todos os lugares e a renomeação quebrou a produção"

"Mudamos 'editor' para 'author' no schema e três verificações ainda referenciam a string antiga. O QA pegou uma delas por acidente."

Diagnóstico: Literais de string espalhados pelos componentes. Nenhuma definição central, nenhuma segurança de tipo.

Refatoração:

// lib/roles.ts
export const ROLES = { admin: "admin", author: "author", viewer: "viewer" } as const;
export type Role = (typeof ROLES)[keyof typeof ROLES];
 
// uso
if (user.role === ROLES.author) { /* ... */ }

Por que isso funciona: as const torna os valores tipos literais. Renomear a constante falha na compilação em todos os consumidores em vez de se comportar silenciosamente mal.

6. "TypeScript está cheio de any e continuamos enviando undefined is not a function"

"Erros no Sentry mencionam Cannot read properties of undefined. O resultado do fetch é tipado como any e acessamos data.user.profile.name."

Diagnóstico: any encurta todos os checks. A forma da resposta da API é desconhecida para o compilador.

Refatoração:

import { z } from "zod";
const User = z.object({ profile: z.object({ name: z.string() }) });
 
const res = await fetch("/api/user");
const user = User.parse(await res.json());

Por que isso funciona: Analisar na fronteira transforma "any" em um tipo conhecido. Respostas ruins lançam na borda em vez de falhar quatro componentes mais adiante.

7. "O <Button /> tem 11 props booleanas e as chamadas são ilegíveis"

"Cada chamada de botão tem isPrimary isLarge isLoading isDisabled isGhost isIcon ... e é impossível dizer o que está sendo renderizado."

Diagnóstico: Sopa de props booleanas. Estados mutuamente exclusivos não são modelados como exclusivos.

Refatoração:

type Variant = "primary" | "secondary" | "ghost" | "danger";
type Size = "sm" | "md" | "lg";
type Props = { variant?: Variant; size?: Size; loading?: boolean; icon?: ReactNode };
 
<Button variant="primary" size="lg" loading={isSaving}>Save</Button>

Por que isso funciona: Uniões codificam a regra "apenas uma variante por vez" no sistema de tipos. Combinações inválidas param de compilar.

8. "A função createInvoice aceita 9 argumentos posicionais"

"Cada local de chamada se parece com createInvoice(id, '', null, true, false, 0, null, 'usd', undefined) e continuamos passando o null errado."

Diagnóstico: Argumentos posicionais degradam rapidamente após três. O leitor não consegue dizer o que cada um significa sem abrir a definição.

Refatoração:

type CreateInvoiceInput = {
  customerId: string;
  note?: string;
  draft?: boolean;
  currency?: "usd" | "eur";
};
export function createInvoice(input: CreateInvoiceInput) { /* ... */ }
 
createInvoice({ customerId: id, draft: true, currency: "usd" });

Por que isso funciona: Chaves nomeadas se documentam no local da chamada. Adicionar uma nova opção não causa quebra; os padrões vivem em um só lugar.

9. "Cinco componentes têm blocos useEffect quase idênticos buscando o mesmo endpoint"

"Pesquisa, a barra lateral, o badge da caixa de entrada e o cabeçalho chamam /api/notifications. Eles divergem constantemente e um sempre tem um cache desatualizado."

Diagnóstico: Lógica de carregamento de dados duplicada. Cada componente tem seu próprio useEffect, seu próprio estado de carregamento e seu próprio comportamento de retentativa.

Refatoração:

// hooks/use-notifications.ts
"use client";
import { useQuery } from "@tanstack/react-query";
 
export function useNotifications() {
  return useQuery({
    queryKey: ["notifications"],
    queryFn: () => fetch("/api/notifications").then(r => r.json()),
  });
}

Por que isso funciona: Uma chave de cache, um fetcher, uma única fonte de verdade. As invalidações se propagam para todos os assinantes automaticamente.

10. "Nosso formulário de inscrição tem 200 linhas de lógica de estado e validação no componente"

"O formulário de inscrição continua crescendo à medida que adicionamos campos. As regras de validação vivem em uma escada if gigante e enviamos bugs de validação a cada lançamento."

Diagnóstico: Gerenciamento de estado imperativo para um formulário que deveria ser declarativo.

Refatoração:

"use client";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
 
const Schema = z.object({
  email: z.string().email(),
  password: z.string().min(12),
});
 
const { register, handleSubmit, formState: { errors } } = useForm({
  resolver: zodResolver(Schema),
});

Por que isso funciona: O schema é a especificação. Validação, exibição de erros e tipos vêm da mesma fonte - adicionar um campo é uma mudança de uma linha.

11. "Ainda existe um componente de classe e ele usa componentWillReceiveProps"

"ESLint avisa sobre UNSAFE_componentWillReceiveProps em <NotificationBell />. O tech lead diz para convertê-lo antes da atualização do React 19."

Diagnóstico: Ciclo de vida de classe legado que não tem equivalente direto em hooks e falha sob a invocação dupla do Strict Mode.

Refatoração:

"use client";
export function NotificationBell({ count }: { count: number }) {
  const [seen, setSeen] = useState(count);
  useEffect(() => {
    if (count > seen) playSound();
    setSeen(count);
  }, [count, seen]);
  return <Badge value={count} />;
}

Por que isso funciona: useEffect mais estado capturam a mesma intenção - "fazer algo quando a contagem muda" - sem armadilhas de ciclo de vida ou vinculação de this.

12. "Após excluir uma linha, o item errado é destacado"

"Exclua a linha 2 na tabela e a linha 3 fica 'selecionada'. Às vezes, o item errado é excluído completamente."

Diagnóstico: key={i} no mapeamento da linha. O React reutiliza nós DOM por posição, então o estado se anexa à linha errada após uma exclusão.

Refatoração:

{rows.map((row) => (
  <Row key={row.id} {...row} />
))}

Por que isso funciona: Identidade estável. O React rastreia cada linha por seu ID real, então remover um item não desloca o estado interno para o próximo.

13. "Temos um switch de 70 casos mapeando tipos de evento para manipuladores"

"Adicionar um novo tipo de evento significa rolar 400 linhas de case. As pessoas copiam o bloco errado e quebram dois eventos ao mesmo tempo."

Diagnóstico: Despacho codificado abertamente. O fluxo de controle codifica dados.

Refatoração:

const handlers = {
  "order.created": handleOrderCreated,
  "order.refunded": handleOrderRefunded,
  // ...
} satisfies Record<EventType, EventHandler>;
 
handlers[event.type](event);

Por que isso funciona: O despacho se torna dados. satisfies garante a exaustividade contra a união, então um manipulador ausente falha na compilação.

14. "JSX tem ternários triplamente aninhados e os revisores se recusam a aprovar"

"Este card tem loading ? skeleton : error ? errorView : empty ? emptyState : data ? <Card /> : null e ninguém consegue ler."

Diagnóstico: Renderização condicional comprimida em uma única expressão.

Refatoração:

function CardView({ state }: { state: ViewState }) {
  if (state.kind === "loading") return <Skeleton />;
  if (state.kind === "error") return <ErrorView error={state.error} />;
  if (state.kind === "empty") return <EmptyState />;
  return <Card data={state.data} />;
}

Por que isso funciona: Uma união discriminada + retornos antecipados leem de cima para baixo. Cada ramo é editável independentemente e a união força você a lidar com cada caso.

15. "Um tooltip personalizado usa document.querySelector para se posicionar"

"O tooltip pula ao rolar e falha em testes onde document é mockado."

Diagnóstico: Acesso imperativo ao DOM em uma árvore React. O tooltip lê o layout fora do ciclo de commit do React.

Refatoração:

"use client";
import { useFloating, autoUpdate } from "@floating-ui/react";
 
const { refs, floatingStyles } = useFloating({ whileElementsMounted: autoUpdate });
 
<button ref={refs.setReference}>Help</button>
<div ref={refs.setFloating} style={floatingStyles}>Tooltip</div>;

Por que isso funciona: Refs permitem que a biblioteca se inscreva no mesmo ciclo de vida que o React já gerencia. Sem querySelector, sem nós desmontados, sem falhas em testes.

16. "Um efeito imprime valores desatualizados - a contagem continua registrando '0'"

"Registramos count dentro de useEffect(() => { setInterval(() => console.log(count), 1000) }, []) e ele sempre imprime 0, mesmo quando a UI mostra 7."

Diagnóstico: Dependências vazias capturam o closure inicial. O intervalo nunca vê o estado posterior.

Refatoração:

const countRef = useRef(count);
useEffect(() => { countRef.current = count; }, [count]);
useEffect(() => {
  const id = setInterval(() => console.log(countRef.current), 1000);
  return () => clearInterval(id);
}, []);

Por que isso funciona: A ref compartilha uma identidade entre renderizações, então o intervalo lê o valor mais recente sem se inscrever novamente a cada mudança de estado.

17. "Armazenamos fullName no estado e ele sai de sincronia com firstName/lastName"

"Edite o campo de primeiro nome e o banner de nome completo acima mostra o valor antigo até você sair do campo."

Diagnóstico: Estado derivado armazenado em useState. Duas fontes de verdade que devem ser mantidas em sincronia manualmente.

Refatoração:

const [firstName, setFirstName] = useState("");
const [lastName, setLastName] = useState("");
const fullName = `${firstName} ${lastName}`.trim();

Por que isso funciona: Valores derivados computados durante a renderização estão sempre atualizados. Não há nada para manter em sincronia porque há apenas uma fonte.

18. "Nossa lista memorizada re-renderiza a cada pressionamento de tecla na caixa de pesquisa"

"Envolvemos <RowList /> em memo, mas digitar no pai ainda re-renderiza cada linha."

Diagnóstico: O callback onRowClick é recriado a cada renderização pai. Uma nova referência derrota memo.

Refatoração:

const handleRowClick = useCallback((id: string) => navigate(`/rows/${id}`), [navigate]);
 
<RowList rows={rows} onRowClick={handleRowClick} />;

Por que isso funciona: useCallback preserva a identidade da função entre renderizações. A comparação rasa de memo agora vê a mesma prop e pula a subárvore.

19. "Cada componente formata preços e datas de maneira ligeiramente diferente"

"Três páginas mostram preços como $12.5, $12.50 e USD 12.50. O marketing quer um formato."

Diagnóstico: Lógica de formatação duplicada. Cada arquivo inventou a sua própria.

Refatoração:

// lib/format.ts
export const money = (cents: number, currency = "USD") =>
  new Intl.NumberFormat("en-US", { style: "currency", currency }).format(cents / 100);
 
export const shortDate = (iso: string) =>
  new Intl.DateTimeFormat("en-US", { dateStyle: "medium" }).format(new Date(iso));

Por que isso funciona: Um módulo, uma regra. Mudar o formato é uma edição, e cada página o adota no próximo deploy.

20. "Metade dos componentes usa style={{}} inline e o bundle tem 30 KB de CSS duplicado"

"O designer diz que o espaçamento é inconsistente. Alguns cards têm style={{ padding: 16 }}, alguns usam uma classe CSS, e eles divergem."

Diagnóstico: Dois sistemas de estilo competindo. Objetos de estilo inline enviam CSS-in-JS por componente que nunca pode ser dedupicado.

Refatoração:

// antes
<div style={{ padding: 16, borderRadius: 8, background: "white" }}>...</div>
 
// depois
<div className="rounded-lg bg-white p-4">...</div>

Por que isso funciona: Classes Tailwind são resolvidas em tempo de compilação e dedupicadas em todo o bundle. Tokens de espaçamento se tornam aplicáveis em vez de artesanais.

Relacionados

• Checklist de Refatoração de UI - a análise sistemática que complementa esses exemplos concisos.
• Decisões de Refatoração - as 30 decisões de refatoração de alto impacto das quais esta lista se baseia.
• Cenários de Bugs de Estado e Re-renderização - contrapartes do lado do bug para os itens de refatoração 16-18.