HTTP no Node.js: requisições, rotas e status

HTTP é o protocolo usado para trocar mensagens entre um cliente e um servidor. A mensagem de entrada é a requisição; a de volta é a resposta. Node.js oferece o módulo nativo node:http, capaz de escutar uma porta, receber dados da requisição e escrever uma resposta sem framework.

Imagine a recepção de um prédio. A pessoa diz o que quer e para qual sala vai; a recepção verifica a solicitação e responde se ela foi atendida. No HTTP, o método descreve a intenção e o caminho identifica o recurso. O limite da analogia: o protocolo possui regras exatas de cabeçalhos, corpo e status; não é uma conversa aberta à interpretação.

Crie um servidor mínimo

Em um projeto com type: module, salve este código em src/servidor.js:

import { createServer } from 'node:http';

const servidor = createServer((requisicao, resposta) => {
  resposta.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
  resposta.end(JSON.stringify({ mensagem: 'Servidor disponível' }));
});

servidor.listen(3000, () => {
  console.log('Servidor em http://localhost:3000');
});

Execute node src/servidor.js. Diferente dos primeiros scripts, o processo não termina: existe um servidor escutando trabalho na porta 3000. Em outro terminal, rode:

curl -i http://localhost:3000

O -i mostra os cabeçalhos. Confira o status HTTP/1.1 200 OK, o tipo de conteúdo JSON e o corpo. Para encerrar o servidor, volte ao primeiro terminal e pressione Ctrl+C.

Uma rota combina método e caminho

Uma rota é a combinação que direciona a requisição para um comportamento. Não compare apenas a URL, pois GET /tarefas consulta a coleção enquanto POST /tarefas pede a criação de um item.

const servidor = createServer((req, res) => {
  res.setHeader('content-type', 'application/json; charset=utf-8');

  if (req.method === 'GET' && req.url === '/tarefas') {
    res.statusCode = 200;
    return res.end(JSON.stringify([{ id: 1, titulo: 'Estudar HTTP' }]));
  }

  if (req.method === 'POST' && req.url === '/tarefas') {
    res.statusCode = 201;
    return res.end(JSON.stringify({ id: 2, titulo: 'Nova tarefa' }));
  }

  res.statusCode = 404;
  return res.end(JSON.stringify({ erro: 'Rota não encontrada' }));
});

O status faz parte do contrato. 200 OK sinaliza uma consulta atendida; 201 Created, uma criação concluída; 400 Bad Request, entrada inválida; 404 Not Found, recurso ou rota não localizado; 500 Internal Server Error, falha não prevista no servidor. Status não substitui um corpo claro, e a mensagem não substitui o status.

Cabeçalhos descrevem como interpretar a mensagem. Ao responder JSON, declare application/json; charset=utf-8; não confie em adivinhação do cliente. O corpo carrega a representação, enquanto status e cabeçalhos carregam metadados sobre a troca. Na requisição, content-type também informa o formato enviado. Mais adiante você vai ler esse corpo em partes, validar o JSON e limitar seu tamanho.

Teste cada rota como uma pequena tabela: método, caminho, status esperado e corpo esperado. Essa tabela impede que GET /tarefas funcionar esconda o fato de que POST /tarefas ainda devolve um status incorreto.

O caminho pode vir acompanhado de parâmetros de consulta. Em vez de cortar a string manualmente, a aplicação real pode construir um objeto URL e ler seus campos. Assim, a rota continua sendo identificada pelo caminho, enquanto filtros e paginação ficam nos parâmetros. Nesta aula mantenha caminhos fixos; a decisão consciente é mais segura do que uma comparação que funciona por acaso apenas sem consulta.

Separe transporte de regra

O callback do servidor deve traduzir HTTP para dados da aplicação e traduzir o resultado de volta. A regra de decidir uma rota pode ser uma função pura. É exatamente isso que o laboratório exercita no navegador: ele não chama createServer, não escuta porta e não finge receber rede. Altere para DELETE e confirme 404; depois teste POST /tarefas e confirme 201.

Erro comum: responder duas vezes

Depois de res.end(), a resposta terminou. Se o código continuar e tentar escrever de novo, surgem erros de cabeçalhos ou escrita após o fim. Por isso os ramos do exemplo usam return res.end(...). Outro erro é sempre devolver 200, inclusive quando nada foi encontrado; o cliente perde uma informação essencial.

Na missão, implemente /saude, verifique com curl -i e teste também uma rota inexistente. Você concluiu quando os corpos são JSON e os status observados são respectivamente 200 e 404. A seguir, vamos persistir dados em arquivo sem bloquear o atendimento.