Servidor Web Simples com Node.js + Express (com tutorial completo e API em JSON)

Criando um servidor web simples com Node.js e Express

Neste tutorial você vai criar e executar um servidor web funcional usando Node.js e Express, entendendo na prática a diferença entre rotas para pessoas (HTML) e rotas para sistemas (API em JSON).

Ao final, você terá:

• Uma página web acessível em / (HTML)
• Uma mini API acessível em /api/hello (JSON)
• Checklist de instalação no Windows
• Soluções para erros comuns de iniciantes

1) O que vamos construir

Vamos criar um servidor HTTP usando Express, escutando na porta 3000, com duas rotas principais:

Rota 1 — GET /

• Retorna HTML
• Pensada para abrir no navegador
• Contém um link para a rota da API

Rota 2 — GET /api/hello

• Retorna JSON
• Pensada para ser consumida por aplicações, front-ends e integrações

Essa separação é fundamental em aplicações modernas: HTML para humanos, JSON para sistemas.

2) Pré-requisitos

• Node.js (versão LTS) instalado
• Um terminal (PowerShell, CMD ou terminal do IDE)

Para verificar se está tudo certo, execute:

node --version
npm --version

Se aparecer que o comando não é reconhecido, pule para a seção de troubleshooting.

3) Estrutura do projeto

01-TesteWindsurf/
  package.json
  server.js
  README.md

(Opcional) Para servir arquivos estáticos:

01-TesteWindsurf/
  public/
    index.html
    style.css

4) Conteúdo do package.json

{
  "name": "servidor-web-simples",
  "version": "1.0.0",
  "description": "Exemplo simples de servidor web",
  "main": "server.js",
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

Explicação rápida:

• dependencies: o que o servidor precisa para rodar
• devDependencies: ferramentas de apoio ao desenvolvimento
• npm start: roda o servidor
• npm run dev: reinicia automaticamente ao salvar

5) Conteúdo do server.js

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

// Middleware para servir arquivos estáticos
app.use(express.static('public'));

// Rota principal
app.get('/', (req, res) => {
  res.send(
    '<h1>Olá! Servidor web funcionando!</h1>' +
    '<p>Visite <a href="/api/hello">/api/hello</a> para ver a API.</p>'
  );
});

// API endpoint
app.get('/api/hello', (req, res) => {
  res.json({
    message: 'Olá do servidor!',
    timestamp: new Date()
  });
});

// Iniciar servidor
app.listen(port, () => {
  console.log(`Servidor rodando em http://localhost:${port}`);
});

O link para /api/hello serve apenas para visualizar o JSON no navegador. Em aplicações reais, essa rota é consumida por código.

6) Instalação e execução

Instalar dependências

npm install

Rodar o servidor

npm start

Ou em modo desenvolvimento:

npm run dev

Acessar no navegador

• HTML: http://localhost:3000
• API: http://localhost:3000/api/hello

Teste via terminal (opcional)

curl http://localhost:3000/api/hello

7) Troubleshooting (Windows)

Node ou npm não reconhecidos

• Instale o Node.js LTS em https://nodejs.org
• Feche e reabra o terminal
• Teste novamente os comandos

PowerShell bloqueando npm.ps1

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Alternativa simples: use o CMD.

Cannot find module ‘express’

npm install

8) Onde entra o Windsurf?

O Windsurf, como IDE com assistência de IA, acelera:

• Criação do esqueleto do projeto
• Compreensão do código
• Correção de erros de ambiente
• Evolução incremental do servidor

Código-fonte do exemplo no GitHub:
https://github.com/fgbettio/01-TesteWindsurf

9) Próximos passos

• Criar uma rota /status
• Ler query params (/api/hello?name=Ana)
• Adicionar logs e tratamento de erros
• Separar rotas em arquivos
• Criar um front-end consumindo a API

CMaker — laboratório de aprendizado e criação.
Do protótipo ao sistema rodando.

Dúvidas? Pergunte AQUI