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”.
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.
Crie a pasta
api-despesase entre nela, numa linha só, com&&entre os comandos.mkdir api-despesas && cd api-despesasGere o
package.jsonaceitando as respostas padrão.npm init -yWrote 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" }Instale o Express como dependência do projeto.
npm install expressadded 66 packages, and audited 67 packages in 3s 14 packages are looking for funding run `npm fund` for details found 0 vulnerabilitiesVocê já criou o
server.js(o código está logo abaixo). Ligue o servidor com o Node.node server.jsAPI 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 buscarPorIdVocê rodou node server.js e apareceu SyntaxError: Cannot use import statement outside a module. O que está faltando?
- A linha
"type": "module"nopackage.json - Rodar
npm install expressde novo - Abrir o
server.jsno navegador, que entendeimport - 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. Oexpressimportado é 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.bodyficaundefined. - Rota: Uma rota junta um método HTTP (
get) e um caminho (/despesas). Só pedidosGET /despesascaem 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/jsone 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
- Cliente → Express: GET /despesas. O cliente pode ser o navegador, o
curlou o seu app React. Para o servidor, tanto faz: chega um pedido HTTP na porta 3000. - 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.
- Express → Handler: chama (req, res). Achou
app.get('/despesas'). O Express chama o handler entregando os objetosreqeres. - 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.
Peça a lista de despesas.
curl http://localhost:3000/despesas[{"id":1,"descricao":"Mercado","valor":230},{"id":2,"descricao":"Ônibus","valor":4.4}]Peça uma despesa que não existe, a de id 99, e use
-ipara ver também o status e os cabeçalhos.curl -i http://localhost:3000/despesas/99HTTP/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"}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}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", e2 === "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/2devolve 200 com a despesa do ÔnibusGET /despesas/99devolve 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 eprocess.env. - Um projeto Node começa com
npm init -y; com"type": "module"você usaimporteexportcomo no Vite. - No Express, uma rota junta método e caminho; o handler recebe
req(params, query, body) e responde uma vez comres.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.
- Crie o projeto com
npm init -y, adicione"type": "module"e um scriptdevcomnode --watch - Implemente
GET /despesas,GET /despesas/:idePOST /despesascom validação e status 200, 201, 400 e 404 - Adicione um middleware que registra método e caminho de cada pedido e um middleware de erro com resposta 500 genérica
- Teste cada rota com
curl -i, incluindo um id inexistente e um corpo inválido, e guarde as saídas - Explique em voz alta, ou por escrito no README, o caminho de um POST desde o
curlaté a resposta