Introdução (3 min)

Imagine uma loja online. Você quer ver os produtos, mas são milhares! Para facilitar a navegação, a loja divide os produtos em páginas. Para acessar uma página específica, você adiciona ?page=2 ao final da URL. Isso é uma query string. Central para APIs modernas, elas permitem filtrar, ordenar e paginar dados de forma eficiente. Nesta aula, você dominará a arte das query strings em Node.js/Express, desde o conceito até a prática.

Conceito Fundamental (7 min)

Uma query string é a parte de uma URL que vem após o caractere ?. Ela consiste em pares chave=valor, separados por &. Por exemplo, em ?page=1&limit=10, page e limit são as chaves, e 1 e 10 são os respectivos valores. Em APIs RESTful, elas são essenciais para consultas dinâmicas, permitindo que o cliente especifique os dados que deseja receber. Integra-se com diversas tecnologias web, desde front-end (JavaScript, React) até bancos de dados. A principal vantagem é a flexibilidade na requisição de dados. A desvantagem é a potencial exposição de dados sensíveis se mal utilizada.

Casos de uso em produção incluem paginação de resultados, filtragem por categoria, ordenação por preço, etc. Imagine a API do Spotify: você pode buscar músicas por artista (?artist=Queen) ou gênero (?genre=Rock).

Implementação Prática (10 min)

Vamos criar uma rota em Express que recebe parâmetros via query string.

const express = require('express');
const app = express();
const port = 3000;

// Middleware para logs (boa prática em produção)
app.use((req, res, next) => {
  console.log([${new Date().toISOString()}] ${req.method} ${req.url});
  next();
});
app.get('/produtos', (req, res) => {
  // Objeto simulado de produtos (em um cenário real, viria do banco de dados)
  const produtos = [
    { id: 1, nome: 'Camiseta', preco: 25 },
    { id: 2, nome: 'Calça', preco: 50 },
    { id: 3, nome: 'Tênis', preco: 100 },
  ];
  // Acessando os parâmetros da query string
  const pagina = parseInt(req.query.page) || 1; // Valor padrão 1 se não fornecido
  const limite = parseInt(req.query.limit) || 10; // Valor padrão 10 se não fornecido
  // Validação básica dos parâmetros (essencial para segurança)
  if (isNaN(pagina) || isNaN(limite) || pagina < 1 || limite < 1) {
    return res.status(400).json({ erro: 'Parâmetros inválidos' }); // Error handling robusto
  }
  // Simulando paginação (em um cenário real, a lógica seria mais complexa)
  const inicio = (pagina - 1) * limite;
  const fim = inicio + limite;
  const produtosPaginados = produtos.slice(inicio, fim);
  res.json(produtosPaginados);
});
// Inicia o servidor
app.listen(port, () => {
  console.log(Servidor rodando em http://localhost:${port});
});

Exercício Hands-On (5 min)

Modifique a rota /produtos para adicionar um filtro por categoria. A query string deve ser algo como ?categoria=Roupa&page=1. A solução envolve adicionar a leitura do parâmetro categoria com req.query.categoria e filtrar o array produtos com base nesse valor antes da paginação.

// ... dentro da rota /produtos

const categoria = req.query.categoria;
// Filtra por categoria se fornecida
const produtosFiltrados = categoria
  ? produtos.filter(p => p.categoria === categoria)
  : produtos;
// ... continua a lógica de paginação com produtosFiltrados ...

Para testar, acesse http://localhost:3000/produtos?categoria=Roupa no seu navegador ou utilize uma ferramenta como Postman. Para validar o resultado, verifique se apenas os produtos da categoria especificada são retornados. Caso encontre erros, revise o código e utilize o console.log() para debugar.

Próximos passos: explorar bibliotecas de paginação e filtros para cenários mais complexos, e integrar com um banco de dados real.