Início / Configuração do Ambiente

⚙️ Configuração do Ambiente

Guia completo para instalar e executar o JSON Server — o backend da nossa disciplina. Siga o passo a passo e tenha seu ambiente pronto em minutos.

O que é o JSON Server?

O JSON Server é uma ferramenta Node.js que cria automaticamente uma API REST completa a partir de um simples arquivo db.json. Em menos de 5 minutos você tem um backend funcional, sem precisar programar uma linha de código no servidor.

🚀

Zero configuração

Crie um arquivo JSON e o servidor está pronto

🔄

API REST completa

GET, POST, PUT, PATCH e DELETE automáticos

💾

Persistência real

Dados são salvos no arquivo db.json

💡 Para que usamos?

Na disciplina, o JSON Server substitui um backend real (Node.js, Python, PHP etc.) para que possamos focar no aprendizado do frontend. Todas as operações de banco de dados (leitura, inserção, edição, exclusão) são feitas via requisições HTTP ao JSON Server.

Arquitetura do Ambiente

Nosso ambiente tem uma arquitetura simples de duas camadas:

┌─────────────────────────────────────────────────────────┐
│                     NAVEGADOR (Cliente)                   │
│                                                          │
│   HTML + CSS + JavaScript                                │
│   (arquivos em public/ ou public2/)                      │
│                                                          │
│   fetch('http://localhost:5000/api/contatos')  ──────┐   │
└──────────────────────────────────────────────────────┼──┘
                                                       │
                                          HTTP Request │
                                                       ↓
┌─────────────────────────────────────────────────────────┐
│                  JSON SERVER (Servidor)                   │
│                                                          │
│   Porta: 5000                                            │
│   Rota: /api/*       ──→   Router JSONServer             │
│   Arquivos estáticos  ──→  pasta public/                 │
│                                                          │
│   Dados persistidos em: db/db.json                       │
└─────────────────────────────────────────────────────────┘
                           │
                     ┌─────┴──────┐
                     │  db.json   │
                     │ {          │
                     │  contatos, │
                     │  usuarios, │
                     │  locais... │
                     │ }          │
                     └────────────┘
Diagrama de Arquitetura do Ambiente JSON Server

Pré-requisitos

Antes de instalar o JSON Server, você precisa ter estes programas instalados:

🟢

Node.js (versão 16 ou superior)

O Node.js é a plataforma que executa o JSON Server. O npm (gerenciador de pacotes) já vem incluso na instalação.

↓ Baixar Node.js (nodejs.org)

Verifique a instalação:

bash
node --version   # deve mostrar v16 ou superior
npm --version    # deve mostrar a versão do npm
💙

Visual Studio Code (recomendado)

Editor de código gratuito e poderoso. Instale as extensões Live Server e Prettier para melhorar sua experiência.

↓ Baixar VS Code (code.visualstudio.com)
🔀

Git (recomendado)

Necessário para clonar este repositório e versionar seu projeto.

Instalação

Existem duas formas de usar o JSON Server: global (disponível em qualquer projeto) ou local (apenas no projeto atual). Recomendamos a instalação local via este repositório.

Criando o banco de dados (db.json)

O arquivo db.json é o banco de dados do JSON Server. Cada chave de nível superior vira uma coleção (equivalente a uma tabela no banco relacional), e cada item do array é um registro.

✅ Regra de ouro

Todo registro precisa ter um campo id único. Se você omitir o id ao criar (POST), o JSON Server gera um automaticamente.

json db/db.json
{
  "contatos": [
    {
      "id": 1,
      "nome": "Bernardo Guerra",
      "telefone": "1-770-736-8031",
      "email": "bernardo@email.com",
      "cidade": "Belo Horizonte",
      "categoria": "trabalho"
    },
    {
      "id": 2,
      "nome": "Ana Silva",
      "telefone": "31-9999-8888",
      "email": "ana@email.com",
      "cidade": "São Paulo",
      "categoria": "amigos"
    }
  ],
  "usuarios": [
    {
      "id": "uuid-unico-aqui",
      "login": "admin",
      "senha": "123",
      "nome": "Administrador",
      "email": "admin@meusite.com"
    }
  ],
  "produtos": []
}

⚠️ Atenção com senhas

Armazenar senhas em texto puro no db.json é aceitável apenas para fins de aprendizado. Em projetos reais, sempre use hashing (bcrypt, argon2 etc.) e nunca exponha o db.json publicamente.

Executando o Servidor

Com as dependências instaladas, inicie o servidor com:

bash
npm start

Você verá algo assim no terminal:

# Saída do terminal

JSON Server is running em http://localhost:5000


Resources

http://localhost:5000/api/contatos

http://localhost:5000/api/usuarios

http://localhost:5000/api/locais

http://localhost:5000/api/lancamentos

http://localhost:5000/api/cidades


Home

http://localhost:5000

💡 Como o servidor está configurado neste projeto

O arquivo index.js usa a biblioteca json-server programaticamente para servir tanto os arquivos estáticos (pasta public/) quanto a API (rota /api). Veja a configuração na seção Config. deste projeto.

Endpoints Disponíveis

Para cada coleção no db.json, o JSON Server gera automaticamente os seguintes endpoints (substituindo :recurso pelo nome da coleção, ex: contatos):

Método Endpoint Descrição
GET /api/:recurso Lista todos os registros
GET /api/:recurso/:id Busca um registro pelo ID
GET /api/:recurso?campo=valor Filtra por campo (ex: ?categoria=amigos)
GET /api/:recurso?_page=1&_limit=10 Paginação dos resultados
GET /api/:recurso?q=texto Busca full-text em todos os campos
POST /api/:recurso Cria um novo registro
PUT /api/:recurso/:id Substitui completamente um registro
PATCH /api/:recurso/:id Atualiza campos específicos
DELETE /api/:recurso/:id Remove um registro

Testando a API

Com o servidor rodando, você pode testar diretamente no navegador ou usar ferramentas dedicadas:

🌐 Via Navegador (apenas GET)

Abra no browser e veja o JSON retornado:

🔧 Via Console do Navegador (F12)

Abra o DevTools (F12) → Console e teste:

js
fetch('http://localhost:5000/api/contatos')
  .then(r => r.json())
  .then(dados => console.table(dados));

🛠️ Ferramentas recomendadas para testes

Insomnia (gratuito, insomnia.rest) ou Postman (postman.com) permitem fazer todos os tipos de requisição (GET, POST, PUT, DELETE) com interface visual. Excelente para testar sua API antes de escrever o código frontend.

Usando com a Fetch API

A Fetch API é a forma moderna de fazer requisições HTTP no navegador. Veja os exemplos completos para cada operação CRUD:

Configuração deste Projeto (index.js)

Este repositório usa o JSON Server de forma programática, via Node.js. O arquivo index.js configura:

  • Servidor na porta 5000 (ou PORT do ambiente)
  • API disponível na rota /api (ex: /api/contatos)
  • Arquivos estáticos servidos da pasta public/
  • Dados persistidos em db/db.json
javascript index.js
const jsonServer = require('json-server')
const server     = jsonServer.create()
const router     = jsonServer.router('./db/db.json')
const middlewares = jsonServer.defaults({ noCors: true })

server.use(middlewares)
server.use('/api', router)   // Todos os endpoints sob /api

const port = process.env.PORT || 5000

server.listen(port, () => {
  console.log(`JSON Server is running em http://localhost:${port}`)
})

⚠️ Atenção: rota /api

Diferente da instalação padrão (onde seria /contatos), neste projeto todos os endpoints têm o prefixo /api. Use sempre http://localhost:5000/api/contatos e não http://localhost:5000/contatos.

Alternativa: Docker

Para quem prefere não instalar Node.js na máquina, o projeto inclui um Dockerfile e docker-compose.yml prontos.

Dockerfile

dockerfile
FROM node:20-alpine

RUN npm i -g json-server@0.17.4

RUN mkdir -p /data /site
VOLUME ["/data", "/site"]
EXPOSE 5000

CMD ["sh", "-lc", "json-server \
  --watch /data/db.json \
  --static /site \
  --host 0.0.0.0 \
  --port 5000"]

docker-compose.yml

yaml
services:
  jsonserver:
    build:
      context: .
      dockerfile: Dockerfile
    image: jsonserver-web:latest
    container_name: jsonserver-web
    ports:
      - "5000:5000"
    volumes:
      - ./db:/data      # banco de dados
      - ./public:/site  # frontend estático
    restart: unless-stopped
bash
# Subir o ambiente
docker-compose up -d

# Ver logs
docker-compose logs -f

# Parar
docker-compose down

💡 Diferença do Docker vs npm start

Com Docker, a API usa a rota raiz (sem /api): localhost:5000/contatos. Com npm start, usa o prefixo /api: localhost:5000/api/contatos. Ajuste suas URLs de acordo com a forma que você subiu o servidor.

Erros Comuns e Soluções

❌ "EADDRINUSE: address already in use :::5000"

A porta 5000 já está sendo usada por outro processo.

bash
# Windows: descobrir qual processo usa a porta
netstat -ano | findstr :5000
taskkill /PID <numero> /F

# Mac/Linux: descobrir e encerrar
lsof -i :5000
kill -9 <PID>

# Ou simplesmente mude a porta no index.js:
let port = process.env.PORT || 3001
❌ "Cannot find module 'json-server'"

As dependências não foram instaladas. Execute:

bash
npm install
❌ Erro de CORS ao fazer fetch no browser

O navegador bloqueia requisições de uma origem para outra por segurança. O projeto já tem noCors: true no index.js. Se o erro persistir, certifique-se de abrir o HTML pelo servidor (via localhost:5000), não abrindo o arquivo diretamente (file://).

❌ Alterações no db.json não aparecem

Se editou o db.json enquanto o servidor estava rodando, reinicie o servidor (Ctrl+C e npm start) ou use a flag --watch se estiver usando o CLI diretamente.

❌ POST retorna 404 ou dados não são salvos

Verifique:

  • O header 'Content-Type': 'application/json' está presente
  • O body usa JSON.stringify(objeto)
  • A URL usa o prefixo correto (/api/ neste projeto)
  • A coleção existe no db.json (ex: "contatos": [])

✅ Checklist: Ambiente Configurado

Marque cada item conforme for concluindo. Seu progresso é salvo automaticamente!

Progresso 0 / 8 concluídos