React: gerenciamento de débitos técnicos e refatoração sustentável

Mapeando dívidas técnicas - Apresentação

Apresentando o instrutor e o curso

Olá, estudante da Alura! Meu nome é Pedro. Sou um homem branco, tenho cabelo e barba escuros, estou usando roupas de cor escura e estou em um ambiente iluminado pelos tons rosa e azul. Seja bem-vindo a mais um curso de React na nossa plataforma da Alura.

Audiodescrição: Pedro é um homem branco, com cabelo e barba escuros. Ele veste roupas de cor escura e está em um ambiente iluminado por cores rosa e azul.

Introduzindo o foco do curso

Este curso tem um enfoque bastante diferente, pois vamos discutir sobre dívidas técnicas e atualizações críticas, além de correções importantes dentro de aplicações React. É um curso muito interessante, no qual vamos explorar como detectar partes do nosso código que podem se tornar uma dívida técnica que precisamos resolver. Vamos aprender a diferenciar uma dívida técnica de um bug ou de uma nova funcionalidade na aplicação, já que muitas vezes podemos confundir uma coisa com a outra.

Vamos abordar como lidar com essa dívida técnica e, principalmente, como fazer um acompanhamento em tempo real para verificar e validar como estamos trabalhando com dívidas técnicas. Isso é importante porque, em 90% das vezes, as mudanças não são visuais e geralmente são melhorias para nós como pessoas desenvolvedoras.

Explorando ferramentas e práticas de desenvolvimento

Durante o curso, falaremos bastante sobre TypeScript, o uso de testes no nosso dia a dia de desenvolvimento e o uso de IA para automatizar algumas tarefas. Utilizaremos algumas ferramentas que nos ajudarão tanto na criação de tickets e cartões, para que possamos manter o controle do que está sendo feito, quanto na questão das dependências da nossa aplicação que estão desatualizadas.

Apresentando o projeto Pulse Metrics

Nosso projeto é o Pulse Metrics, uma plataforma voltada para a gestão de métricas para equipes de marketing. Trata-se de uma aplicação completa, com back-end e um front-end bastante grande e robusto, contendo muitos componentes para que possamos trabalhar e validar.

Não faremos uma revisão do código agora, pois teremos tempo para isso com mais calma. Basicamente, ao executar o projeto junto com nossa API, podemos validar todas as informações no localhost, navegar entre as páginas e verificar o funcionamento do projeto.

Focando em técnicas avançadas e priorização

Este é um projeto que exigirá mais conhecimento, pois todos os recursos do React, principalmente questões como Redux, React Router e o funcionamento de Hooks, não serão ensinados aqui. Vamos discutir como identificar problemas no código, mais voltados para dívidas técnicas e atualizações que podem provocar mudanças incompatíveis na aplicação. O foco será mais em técnicas e como priorizá-las, em vez de ensinar como passar de UseContext para Redux, como fazer uma migração de um React Router para uma navegação normal, ou como mudar um paradigma de CSS. Espera-se que já tenhamos esse conhecimento neste ponto do curso.

Se ainda houver dúvidas ou se quisermos aprender mais sobre isso, na Alura temos várias trilhas que vão desde o módulo inicial até o mais avançado, cobrindo todos os temas que estamos tratando aqui.

Convidando para a jornada de aprendizado

Preparem-se, estudantes, pois vamos iniciar nossa jornada falando sobre dívidas técnicas. Nos vemos a seguir para continuarmos neste mundo do desenvolvimento com React.

Mapeando dívidas técnicas - Conhecendo o Pulse Metrics

Introduzindo o conceito de dívida técnica

Antes de começarmos a discutir propriamente sobre as dívidas técnicas, como detectá-las e qual a ordem de prioridade para abordá-las, é importante destacar que as dívidas técnicas não são necessariamente funcionalidades do projeto. Quando precisamos corrigir algo no projeto ou melhorar uma funcionalidade que não está funcionando bem, tratamos isso como um erro. Já a dívida técnica não está diretamente ligada a uma funcionalidade específica, nem é necessariamente um problema ou melhoria de uma funcionalidade. A dívida técnica envolve muito mais nossa experiência como pessoas desenvolvedoras de software, lidando com o código, a arquitetura e outras dependências.

Antes de avançarmos para esses pontos, vamos entender como está funcionando nosso projeto Pulse Metrics. Estamos compartilhando a tela com o editor de texto aberto, na raiz do projeto React Pulse Metrics. Na raiz do projeto, podemos visualizar uma pasta de API, onde temos uma API desenvolvida em Golang especialmente para este projeto. Essa API foi criada para testar algumas funcionalidades, mas não vamos mexer em nada relacionado à API ou aos serviços de back-end que montamos. Aproveitamos a oportunidade para praticar outros idiomas e exercitar a parte de Full Stack.

Explorando a estrutura do projeto

Temos a pasta "dist", gerada pelo nosso gerador Vite no projeto, e a pasta de end-to-end, onde realizamos algumas provas de integração end-to-end para o projeto. A pasta "node_modules" contém todas as dependências do projeto após a instalação. A pasta "public" é utilizada pelo Vite para gerar o build, usando, por exemplo, um favicon e o index.html para gerar nosso script dentro da tag div, na linha 10 do index.html. Isso é o funcionamento normal de projetos React e JavaScript que utilizam bibliotecas como o React para renderização no DOM.

Aqui está o conteúdo do arquivo index.html que é utilizado para iniciar a aplicação:

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="icon" type="image/png" href="/favicon.png" />
    <title>PulseMetrics</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/index.tsx"></script>
  </body>
</html>

Analisando componentes e melhorias

Dentro da pasta "src", temos uma pasta de mocks para nossos testes, uma pasta de testes com uma subpasta específica de snapshots e outra com os testes já escritos para a aplicação. A pasta "assets" contém, por exemplo, o logo do Pulse Metrics. Na pasta "components", há vários componentes, incluindo parte do layout. Observamos que há diferentes formas de criação dos componentes: alguns estão dentro de pastas, outros fora, e há variações na grafia dos nomes das pastas, com letras maiúsculas ou minúsculas. Isso nos leva a identificar questões que são melhorias para o projeto, mas que não necessariamente implicam em mudanças na forma como o projeto funciona. São diferenças visuais que teremos no projeto.

A dívida técnica trata mais de melhorias a nível de arquitetura, estrutura, tipagem e configuração de testes. As dívidas técnicas e as melhorias progressivas que desejamos ver em nossos projetos e na experiência das pessoas desenvolvedoras estão mais orientadas a essas questões, como estamos vendo neste exemplo ao vivo, de estruturas, arquivos e pastas. Não entraremos em tantos detalhes dentro de cada pasta, mas vemos que há diversos componentes, alguns repetidos. Criamos um projeto extenso com a intenção de nos aproximarmos o máximo possível de um projeto real, como um carro em movimento no qual precisamos trocar uma roda sem parar o carro. Suponhamos que seja um projeto grande, já em produção; não podemos deixá-lo fora de serviço e precisamos fazer melhorias — nesse caso, trocar a roda do carro — mas o carro não pode parar. Precisamos fazer esses ajustes com o veículo em movimento, algo utópico em um cenário real, mas possível no desenvolvimento de software.

Objetivo das melhorias contínuas

Nosso objetivo como pessoas desenvolvedoras de software é fazer melhorias no projeto sem causar tempo de inatividade, evitando que o projeto caia ou deixe de funcionar. As dívidas técnicas servem precisamente para isso: para que possamos fazer pequenos ajustes e melhorias sem a necessidade de uma modificação gigantesca, permitindo mudanças nas peças do carro enquanto ele está em movimento. Podemos fazer essas alterações na aplicação em produção sem o risco de deixá-la fora do ar.

Na pasta "components", temos uma pasta "context" e uma pasta "hooks" com alguns hooks usados na aplicação. Os mocks estão repetidos, mas são um pouco distintos para os testes, campanhas e outros.

Estrutura do projeto e análise técnica

Utilizamos alguns dados para construir o projeto, que acabaram permanecendo na nossa estrutura, às vezes sem necessidade. Vamos descobrir isso ao longo do processo. Temos nossas páginas, inclusive algumas a mais, que usamos no projeto para garantir redundância e visualizar o conteúdo necessário para buscas especiais. Deixarei algumas dicas para identificarmos problemas e como podemos solucioná-los. Será uma espécie de mentoria técnica, onde discutiremos juntos a melhor forma de organização.

Contexto e redutores

Temos o context, mas também os reducers, que estão acompanhados de actions e types. Essa estrutura é antiga, e pode ser interessante analisarmos a possibilidade de usar o toolkit, uma ferramenta nova que reduz a quantidade de arquivos de reducers e a redundância.

Serviços e consumo de API

Na parte de serviços, consumimos a API que construímos. Utilizamos CSS, mas hoje existem ferramentas como o Tailwind, que facilitam o uso de CSS de forma mais concisa e legível, permitindo a criação e reutilização de variáveis no projeto.

Aqui está um exemplo de como as variáveis CSS são definidas no projeto:

:root {
  --color-primary: #2563eb;
  --color-secondary: #7c3aed;
  --color-surface: #ffffff;
  --color-background: #f3f4f6;
  --color-text-primary: #111827;
  --color-text-secondary: #6b7280;
  --color-border: #e5e7eb;
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --border-radius: 8px;
  --shadow-sm: 0 1px 3px rgba(0,0,0,0.1);
  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
  --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);
}

Tipagem e utilitários

A tipagem apresenta problemas, com o uso de vários any dentro do arquivo api.ts e index.ts. Temos uma pasta de utilidades com diversos utilitários usados durante a construção do projeto, que também analisaremos.

Aqui está um exemplo de como a tipagem fraca foi identificada como uma dívida técnica:

// AVISO: Tipos intencionalmente fracos - Débito técnico identificado
// Ticket #234 "tipar as respostas de API corretamente"

export type ApiResponse = Record<string, any>;
export type Campaign = any;
export type User = any;
export type Metrics = any;
export type AudienceSegment = any;
export type Report = any;

Execução do projeto

Antes de prosseguir, verificamos no package.json o comando para rodar o projeto. Na linha 5, temos o run dev, que executa o Vite, e o dev full, que executa tanto a API quanto a aplicação em modo concurrently do npm. No terminal integrado, executamos npm run dev:full, abrindo o projeto no navegador.

Aqui estão os scripts relevantes do package.json:

"dev": "vite",
"dev:full": "concurrently \"npm run dev\" \"npm run api\"",

E o comando para executar ambos simultaneamente:

npm run dev:full

Navegação e funcionalidades

No navegador, acessamos o Pulse Metrics — uma plataforma de análise para equipes de marketing. Temos a parte de login com dados pré-carregados. No arquivo main.go da API, estão todas as rotas, incluindo a de login, que é pública e não requer bearer token. No alph.go, dentro da pasta "handlers", temos usuários seed que podem ser acessados com a senha admin123.

Aqui está um trecho do código que define a rota de login na API:

api.POST("/auth/login", handlers.Login)

E a implementação da função de login:

func Login(c *gin.Context) {
	var req loginRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "email and password are required"})
		return
	}

	user, ok := store.Global.GetUserByEmail(req.Email)
	if !ok {
		c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid credentials"})
		return
	}

	// Accepted passwords for dev: admin123 for all seed users.
	if req.Password != "admin123" {
		c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid credentials"})
		return
	}

	c.JSON(http.StatusOK, gin.H{
		"token": "pulse-dev-token",
		"user":  user,
	})
}

Dashboard e campanhas

No dashboard, visualizamos informações como último uso, data e hora, além de filtros por períodos (7, 30, 90 dias). Podemos criar novas campanhas, como "Black Friday Alura 2026", definindo objetivos, canais, orçamento e datas. A campanha aparece no final do nosso listado, mesmo sem orçamento ou período definidos.

Métricas e objetivo da plataforma

A seção de métricas mostra impressões e é orientada para separação por canais e funil. O objetivo da plataforma é fornecer informações para equipes de marketing, ilustrando projetos que cresceram e receberam novas funcionalidades ao longo do tempo, às vezes com prazos apertados.

Conclusão

O projeto Pulse Metrics apresenta detalhes que investigaremos mais adiante. Vamos continuar explorando as dívidas técnicas em aplicações com React.

Mapeando dívidas técnicas - Preparando o terreno para mapear os débitos técnicos

Introduzindo o conceito de dívidas técnicas

Continuamos com nosso editor de texto aberto e vamos entrar no universo das dívidas técnicas. Vamos começar a entender quais são os problemas técnicos que temos dentro da aplicação Pulse Metrics, como priorizamos esses problemas na ordem correta de abordagem. Utilizamos "correta" entre aspas, pois essa parte depende muito da disponibilidade da equipe e de quantas pessoas temos trabalhando que possam abordar essas dívidas técnicas.

Precisamos entender como fazemos o acompanhamento desses itens e como conseguimos colocá-los em algum lugar. Isso é algo que ocorre muito no dia a dia de empresas grandes, mas na verdade em qualquer empresa que siga um fluxo parecido com Kanban ou uma forma de Scrum para trabalhar. Normalmente, os itens de dívida técnica têm um acompanhamento separado dos demais itens, das demais funcionalidades e correções de bugs, que são o trabalho diário de uma pessoa desenvolvedora. Segundo nossa experiência, os itens de dívida técnica são tratados de forma separada e são alocados, por exemplo, ao final do sprint ou quando há uma carga menor de trabalho em tickets normais.

Criando e organizando tickets de dívida técnica

A forma que vamos usar para saber quais são os itens de dívida técnica, como priorizá-los e como trabalhamos com eles, é criando tickets, como fazemos no Trello, no Jira ou em qualquer outra ferramenta de acompanhamento de tickets. Dessa forma, podemos trabalhar de maneira organizada.

A ferramenta que sugerimos para uso é o Trello, acessível pelo site trello.com. Gostamos muito do Trello, primeiramente porque é gratuito. Ele possui um modo pago, com algumas funcionalidades avançadas, mas o modo gratuito já será mais que suficiente. Basicamente, precisamos de um quadro onde teremos duas colunas: nossa coluna de backlog, a coluna de desenvolvimento e a coluna de concluído.

Considerando o impacto das dívidas técnicas nos testes

As dívidas técnicas, em 90% dos casos, não vão requerer que a equipe de QA ou de testes, caso o time tenha pessoas separadas para isso, dedique tempo para testá-las. Isso ocorre porque, geralmente, essas mudanças não têm impacto visual ou não incluem modificações que exijam uma regressão na aplicação. No entanto, em casos específicos, como quando migramos de context para Redux ou substituímos Redux por Redux Toolkit, pode ser interessante comunicar à equipe sobre as alterações. Assim, durante uma regressão, alguém pode verificar se houve alguma alteração inesperada no funcionamento.

As provas de integração, end-to-end e até algumas unitárias, são fundamentais para que, durante essas refatorações de dívida técnica, não precisemos alocar tempo dos testers, que poderiam estar testando outras funcionalidades. Temos ferramentas que otimizam o tempo que seria gasto em testes de dívida técnica, permitindo que confiemos em nossas provas de integração.

Configurando o Trello para gerenciar dívidas técnicas

Agora, vamos ao Trello. Se ainda não tiver uma conta, é possível vinculá-la com a conta do Google. Diversas ferramentas têm integração com o Trello. Caso ainda não tenha uma conta, recomendamos pausar o vídeo e criar uma para que possamos seguir juntos.

Estamos adotando um formato diferente neste curso, semelhante a uma mentoria técnica, onde avançamos passo a passo. Após criar a conta, na página inicial do Trello, há uma seção de modelos, incluindo modelos Kanban, de organização de equipe e produtividade. No entanto, queremos algo simples, sem complexidade. Na página inicial, ao descer, encontramos a área de trabalho e a opção de criar um novo quadro. Se a área estiver vazia, será apenas um quadro; caso contrário, a opção estará à direita.

Criando e configurando o quadro no Trello

Ao clicar em criar novo quadro, nomeamos como "Dívidas Técnicas - Pulse Metrics". A visibilidade é importante: pode ser privada, visível apenas para membros do quadro, ou pública, acessível a qualquer pessoa na internet, mas apenas membros podem editar. Neste caso, deixaremos na área de trabalho. Recomendamos discutir a ferramenta e a visibilidade ao criar um quadro na empresa.

Após criar, o Trello nos apresenta várias funcionalidades, incluindo integrações com Jira. Com o quadro criado, vamos criar listas: a primeira será "backlog", onde listaremos todos os itens a serem trabalhados. Em seguida, criamos uma lista "em progresso" e outra "completado". Essas três colunas permitirão acompanhar o progresso dos itens de dívida técnica.

Com o Trello configurado, vamos entender como identificar e priorizar os pontos para preenchê-los no quadro. Nos vemos na próxima etapa.

Sobre o curso React: gerenciamento de débitos técnicos e refatoração sustentável

O curso React: gerenciamento de débitos técnicos e refatoração sustentável possui 338 minutos de vídeos, em um total de 45 atividades. Gostou? Conheça nossos outros cursos de React em Front-end, ou leia nossos artigos de Front-end.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Mapeando dívidas técnicas
• Refatorando componentes monolíticos
• Migrando dependências críticas
• Criando um ciclo contínuo de qualidade