Node.js e Express

JavaScript fora do navegador: criar um projeto Node, montar uma API com Express, rotas, middlewares, status e tratamento de erros.

Cerca de 16 min · Revisado em

Ao final, você vai conseguir

  • Explicar o que muda ao rodar JavaScript no Node em vez do navegador
  • Criar um projeto com npm init, módulos e Express e ligar o servidor
  • Escrever rotas com parâmetros e corpo que respondem com o status certo
  • Usar middlewares em ordem, incluindo express.json e um tratador de erros
  • Testar as rotas de uma API com curl e ler status e cabeçalhos

Até aqui, todo o seu JavaScript rodou dentro do navegador, numa aba que some quando a pessoa fecha. Mas a lista de despesas, o login e o carrinho precisam morar em algum lugar que fique ligado o tempo todo e atenda muita gente ao mesmo tempo. Com Node.js e Express você usa a mesma linguagem para escrever esse outro lado: o servidor que recebe pedidos e devolve respostas. É o primeiro passo para dizer em uma entrevista “eu fiz o front e a API”.

JavaScript fora do navegador

Node.js é um programa que roda JavaScript direto no computador, sem navegador. Ele usa o mesmo motor de JavaScript do Chrome, chamado V8, mas troca as ferramentas em volta. Esse conjunto de motor e ferramentas se chama ambiente de execução (em inglês, runtime).

No navegador existem document, window e localStorage, porque lá há uma página para mexer. No Node não há página: no lugar, ele oferece acesso a arquivos (fs), à rede (http) e às variáveis do sistema (process.env). A linguagem é a mesma; o que muda é o que está disponível.

Onde cada recurso existe?

Só no navegador · Só no Node.js · Nos dois

  • document.querySelector
  • localStorage
  • fs.readFile para ler um arquivo do disco
  • process.env.PORT
  • console.log
  • JSON.parse
  • setTimeout

Seu primeiro JavaScript no terminal

Confira se o Node está instalado e rode uma linha de JavaScript sem abrir navegador nenhum.

  1. Veja qual versão do Node está instalada.

    node -v
    v22.11.0
  2. Rode uma conta direto no terminal com a opção -e (de “execute”): node -e "console.log(230 + 4.4)".

    node -e "console.log(230 + 4.4)"
    234.4
  3. Agora tente usar document, que só existe no navegador: node -e "document.title".

    node -e "document.title"
    [eval]:1
    document.title
    ^
    
    ReferenceError: document is not defined
        at [eval]:1:1
    
    Node.js v22.11.0

Um projeto Node e seus módulos

Na aula de npm e Vite você conheceu o package.json, a ficha do projeto. Um servidor Node usa a mesma ficha. A diferença é que agora você vai instalar o Express, uma biblioteca que cuida do trabalho chato de receber pedidos HTTP, para você só escrever o que cada endereço responde.

Comece a API de despesas

Crie a pasta do projeto, gere o package.json, instale o Express e ligue o servidor.

  1. Crie a pasta api-despesas e entre nela, numa linha só, com && entre os comandos.

    mkdir api-despesas && cd api-despesas
  2. Gere o package.json aceitando as respostas padrão.

    npm init -y
    Wrote to /home/voce/api-despesas/package.json:
    
    {
      "name": "api-despesas",
      "version": "1.0.0",
      "main": "index.js",
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
      },
      "license": "ISC"
    }
  3. Instale o Express como dependência do projeto.

    npm install express
    added 66 packages, and audited 67 packages in 3s
    
    14 packages are looking for funding
      run `npm fund` for details
    
    found 0 vulnerabilities
  4. Você já criou o server.js (o código está logo abaixo). Ligue o servidor com o Node.

    node server.js
    API ouvindo em http://localhost:3000

Um módulo é um arquivo que exporta coisas para outros arquivos usarem. Para usar import e export no Node, como você faz no Vite, adicione "type": "module" no package.json. Sem isso, o Node usa o formato antigo, com require.

Separar os dados do servidor em módulos

package.json

{
  "name": "api-despesas",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "node --watch server.js"
  },
  "dependencies": {
    "express": "^5.1.0"
  }
}

despesas.js

export const despesas = [
  { id: 1, descricao: 'Mercado', valor: 230 },
  { id: 2, descricao: 'Ônibus', valor: 4.4 },
];

export function buscarPorId(id) {
  return despesas.find((despesa) => despesa.id === id);
}

server.js

import express from 'express';
import { despesas, buscarPorId } from './despesas.js';

// ...rotas usam despesas e buscarPorId

Você rodou node server.js e apareceu SyntaxError: Cannot use import statement outside a module. O que está faltando?

  • A linha "type": "module" no package.json
  • Rodar npm install express de novo
  • Abrir o server.js no navegador, que entende import
  • Trocar a extensão do arquivo para .html

A anatomia de um servidor Express

O menor servidor útil da API de despesas. Explore cada parte.

import express from 'express';

const app = express();
app.use(express.json());

const despesas = [
  { id: 1, descricao: 'Mercado', valor: 230 },
  { id: 2, descricao: 'Ônibus', valor: 4.4 },
];

app.get('/despesas', (req, res) => {
  res.json(despesas);
});

app.listen(3000, () => {
  console.log('API ouvindo em http://localhost:3000');
});
  • Importar: Traz a biblioteca instalada em node_modules. O express importado é uma função que cria aplicações.
  • Criar a aplicação: app é o seu servidor. Nele você registra o que fazer com cada pedido.
  • Middleware de JSON: Lê o corpo dos pedidos que chegam em JSON e coloca o resultado em req.body. Sem ele, req.body fica undefined.
  • Rota: Uma rota junta um método HTTP (get) e um caminho (/despesas). Só pedidos GET /despesas caem aqui.
  • Handler: A função que trata o pedido. req (requisição) traz o que chegou: caminho, parâmetros, corpo. res (resposta) tem os métodos para responder.
  • Responder: Transforma o array em texto JSON, coloca o cabeçalho Content-Type: application/json e envia com status 200. Cada pedido precisa de exatamente uma resposta.
  • Escutar a porta: Liga o servidor na porta 3000. Porta é como o número do guichê: o mesmo computador pode ter vários programas, cada um escutando a sua.

O que acontece quando alguém pede a lista de despesas

  1. Cliente → Express: GET /despesas. O cliente pode ser o navegador, o curl ou o seu app React. Para o servidor, tanto faz: chega um pedido HTTP na porta 3000.
  2. Express → Express: procura a rota. O Express compara método e caminho com as rotas registradas, na ordem em que foram escritas, e passa pelos middlewares no caminho.
  3. Express → Handler: chama (req, res). Achou app.get('/despesas'). O Express chama o handler entregando os objetos req e res.
  4. Handler → Cliente: 200 + JSON. res.json(despesas) envia o status 200, o cabeçalho de JSON e a lista. A conversa termina.

Um handler faz console.log(despesas) mas esquece o res.json(...). O que acontece com quem pediu?

  • O pedido fica esperando, sem resposta, até desistir por tempo
  • O cliente recebe a lista, porque ela foi impressa
  • O Express responde 404 automaticamente

Parâmetros, corpo e status

Uma API de verdade precisa de mais do que a lista. Na aula de API REST você viu recursos, métodos e status. Agora você escreve isso em código. Três lugares guardam informação do pedido: req.params (pedaços variáveis do caminho, como o 2 em /despesas/2), req.query (o que vem depois do ?) e req.body (o corpo, num POST).

Buscar uma despesa e criar uma nova

app.get('/despesas/:id', (req, res) => {
  const id = Number(req.params.id); // params sempre chegam como texto
  const despesa = despesas.find((d) => d.id === id);
  if (!despesa) {
    return res.status(404).json({ erro: 'Despesa não encontrada' });
  }
  res.json(despesa);
});

app.post('/despesas', (req, res) => {
  const { descricao, valor } = req.body;
  if (typeof descricao !== 'string' || descricao.trim() === '') {
    return res.status(400).json({ erro: 'Informe a descrição' });
  }
  if (typeof valor !== 'number' || valor <= 0) {
    return res.status(400).json({ erro: 'O valor deve ser maior que zero' });
  }
  const nova = { id: despesas.length + 1, descricao: descricao.trim(), valor };
  despesas.push(nova);
  res.status(201).json(nova);
});

Repare no return antes de res.status(...). Ele encerra a função ali. Sem ele, o código continuaria e tentaria responder duas vezes ao mesmo pedido.

Converse com a API pelo curl

O servidor está rodando em outro terminal. Use o curl, um cliente HTTP de linha de comando, para testar cada rota.

  1. Peça a lista de despesas.

    curl http://localhost:3000/despesas
    [{"id":1,"descricao":"Mercado","valor":230},{"id":2,"descricao":"Ônibus","valor":4.4}]
  2. Peça uma despesa que não existe, a de id 99, e use -i para ver também o status e os cabeçalhos.

    curl -i http://localhost:3000/despesas/99
    HTTP/1.1 404 Not Found
    X-Powered-By: Express
    Content-Type: application/json; charset=utf-8
    Content-Length: 32
    Date: Wed, 14 Oct 2026 15:10:02 GMT
    
    {"erro":"Despesa não encontrada"}
  3. Crie uma despesa com POST. Envie o cabeçalho de JSON e o corpo: curl -i -X POST http://localhost:3000/despesas -H "Content-Type: application/json" -d '{"descricao":"Farmácia","valor":37.9}'.

    curl -i -X POST http://localhost:3000/despesas -H "Content-Type: application/json" -d '{"descricao":"Farmácia","valor":37.9}'
    HTTP/1.1 201 Created
    X-Powered-By: Express
    Content-Type: application/json; charset=utf-8
    Content-Length: 47
    
    {"id":3,"descricao":"Farmácia","valor":37.9}
  4. Agora envie um valor negativo para ver a validação do servidor em ação: troque o corpo por '{"descricao":"Pix","valor":-5}'.

    curl -i -X POST http://localhost:3000/despesas -H "Content-Type: application/json" -d '{"descricao":"Pix","valor":-5}'
    HTTP/1.1 400 Bad Request
    X-Powered-By: Express
    Content-Type: application/json; charset=utf-8
    Content-Length: 43
    
    {"erro":"O valor deve ser maior que zero"}

Alguém escreveu despesas.find((d) => d.id === req.params.id) e a rota /despesas/2 sempre responde 404, mesmo com a despesa 2 existindo. Por quê?

  • req.params.id é o texto "2", e 2 === "2" é falso
  • O certo seria req.body.id, porque o id vem no corpo
  • A rota deveria ser /despesas/id, sem os dois-pontos

Complete a rota que apaga uma despesa: ela lê o id do caminho, responde 404 se não achar e 204 (sem corpo) se apagar.

app.____('/despesas/____', (req, res) => {
  const id = Number(req.____.id);
  const posicao = despesas.findIndex((d) => d.id === id);
  if (posicao === -1) {
    return res.____(404).json({ erro: 'Despesa não encontrada' });
  }
  despesas.splice(posicao, 1);
  res.status(____).end();
});

Middleware e tratamento de erros

Um middleware é uma etapa dessas. É uma função (req, res, next) que roda antes da rota. Ela pode olhar o pedido, mudar algo e chamar next() para passar adiante, ou responder e encerrar ali. O express.json() que você já usou é um middleware.

Um middleware de registro, a resposta para rota desconhecida e o tratador de erros

function registrar(req, res, next) {
  console.log(new Date().toISOString(), req.method, req.url);
  next(); // sem isso, o pedido para aqui
}

app.use(registrar);
app.use(express.json());

// ...todas as rotas...

app.use((req, res) => {
  res.status(404).json({ erro: 'Rota não encontrada' });
});

app.use((erro, req, res, next) => {
  console.error(erro);
  res.status(500).json({ erro: 'Erro interno. Tente de novo mais tarde.' });
});

O último bloco é especial: um middleware de erro tem quatro parâmetros, com o erro primeiro. Quando uma rota lança uma exceção, o Express pula direto para ele. No Express 5, isso vale também para handlers async que falham. Assim a pessoa recebe uma mensagem genérica, e o detalhe técnico fica só no terminal do servidor.

Coloque as partes do server.js na ordem em que precisam aparecer.

  • import express from 'express'
  • const app = express()
  • app.use(express.json())
  • app.get('/despesas', ...) e as outras rotas
  • app.use((req, res) => ...) para rota não encontrada
  • app.use((erro, req, res, next) => ...) para erros
  • app.listen(3000, ...)

O POST de despesas quebra com TypeError: Cannot destructure property 'descricao' of 'req.body' as it is undefined. O curl envia o cabeçalho de JSON corretamente. Qual a causa mais provável?

  • Falta app.use(express.json()), ou ele foi registrado depois das rotas
  • O cliente deveria mandar os dados na URL, e não no corpo
  • A despesa ainda não existe, então req.body é vazio

Monte o coração de uma rota

O Express não roda dentro do navegador, porque o navegador não abre portas. Mas o coração de uma rota é só uma função: recebe um objeto de pedido e devolve uma resposta. É isso que você vai escrever agora, em JavaScript puro, com a mesma lógica que usaria num handler.

O tratador da API de despesas

Complete a função tratar(req). Ela recebe { method, path, body } e devolve { status, body }. Faça GET /despesas/2 devolver a despesa (ou 404 com { erro: 'Despesa não encontrada' } se não existir) e POST /despesas validar descricao e valor, respondendo 400 com erro quando algo estiver errado e 201 com a despesa criada quando estiver certo. Veja os resultados no console.

<p>Abra o console para ver as respostas da função <code>tratar</code>.</p>
body { font-family: system-ui, sans-serif; padding: 16px; color: #334155; }
// O "banco" em memória, como na API de verdade
const despesas = [
  { id: 1, descricao: 'Mercado', valor: 230 },
  { id: 2, descricao: 'Ônibus', valor: 4.4 },
];

// req: { method, path, body }  ->  devolve { status, body }
function tratar(req) {
  if (req.method === 'GET' && req.path === '/despesas') {
    return { status: 200, body: despesas };
  }

  // 1. GET /despesas/:id
  //    dica: req.path.startsWith('/despesas/') e Number(req.path.split('/')[2])
  //    achou: 200 com a despesa | não achou: 404 { erro: 'Despesa não encontrada' }

  // 2. POST /despesas
  //    descricao precisa ser texto não vazio; valor, número maior que zero
  //    inválido: 400 { erro: '...' } | válido: 201 com a nova despesa (id novo)

  return { status: 404, body: { erro: 'Rota não encontrada' } };
}

console.log(tratar({ method: 'GET', path: '/despesas' }));
console.log(tratar({ method: 'GET', path: '/despesas/2' }));
console.log(tratar({ method: 'POST', path: '/despesas', body: { descricao: 'Pix', valor: -5 } }));
  • GET /despesas/2 devolve 200 com a despesa do Ônibus
  • GET /despesas/99 devolve 404 avisando que a despesa não foi encontrada
  • POST com valor negativo ou sem descrição devolve 400 com erro
  • POST válido devolve 201 com a despesa nova, que passa a aparecer na lista
Sua função já decide a resposta de cada pedido. O que o Express faz que ela ainda não faz?

Ele abre a porta e escuta a rede, transforma o texto HTTP que chega no objeto req, lê o corpo JSON, compara padrões como /despesas/:id sem você precisar cortar o caminho na mão, roda os middlewares em ordem e transforma o seu { status, body } em uma resposta HTTP de verdade. A regra de negócio, que é a parte que você escreveu, continua sendo sua.

Na sua API, quem precisa validar que o valor é maior que zero, se o formulário React já tem min="0.01" no campo?

  • O servidor, sempre. A validação do formulário é só conforto para a pessoa
  • Só o formulário, porque é por ele que as pessoas cadastram
  • Ninguém: o banco de dados recusa números negativos sozinho

Fechamento

  • Node.js roda JavaScript fora do navegador: não tem document, mas tem arquivos, rede e process.env.
  • Um projeto Node começa com npm init -y; com "type": "module" você usa import e export como no Vite.
  • No Express, uma rota junta método e caminho; o handler recebe req (params, query, body) e responde uma vez com res.status(...).json(...).
  • Middlewares rodam em ordem e chamam next(); o de quatro parâmetros trata erros e devolve uma mensagem genérica com status 500.
  • O servidor sempre valida a entrada e responde com o status certo, porque qualquer cliente pode chamar a API.

Sua API de despesas rodando de verdade

Construa no seu computador a API que o seu app React vai consumir na próxima aula e explique, com o terminal aberto, o caminho de uma requisição.

  1. Crie o projeto com npm init -y, adicione "type": "module" e um script dev com node --watch
  2. Implemente GET /despesas, GET /despesas/:id e POST /despesas com validação e status 200, 201, 400 e 404
  3. Adicione um middleware que registra método e caminho de cada pedido e um middleware de erro com resposta 500 genérica
  4. Teste cada rota com curl -i, incluindo um id inexistente e um corpo inválido, e guarde as saídas
  5. Explique em voz alta, ou por escrito no README, o caminho de um POST desde o curl até a resposta

Referências

Cursos relacionados