Aplicação de blog full stack: API REST com autenticação JWT + interface web em Next.js.
O projeto é dividido em dois apps independentes:
blog/
├── backend/ API REST (Express + TypeScript + Prisma + MariaDB/MySQL)
└── frontend/ Interface web (Next.js + React + Tailwind CSS)
| Camada | Tecnologias |
|---|---|
| Backend | Node.js, TypeScript, Express 5, Prisma 7, MariaDB/MySQL, Zod, bcrypt, JSON Web Token |
| Frontend | Next.js 16 (App Router), React 19, Tailwind CSS 4, TypeScript |
| Testes | node:test (suíte de integração da API) |
- Cadastro de usuários com senha hasheada (bcrypt, 10 rounds)
- Login com emissão de token JWT (HS256, expira em 1h)
- Criação de posts protegida por autenticação Bearer, como publicado ou rascunho
- Capa opcional por post: upload de imagem (JPG, PNG, WEBP, GIF ou AVIF, até 5 MB), com fallback para a arte da categoria
- Edição e exclusão pelo próprio autor (texto, categoria e capa), bloqueadas para os demais
- Rascunhos privados: só o autor vê, abre e publica os próprios rascunhos (para os outros, 404)
- Perfil do autor com nome e bio editáveis; a bio aparece embaixo do nome nos posts
- Listagem pública paginada (
?pagina=N) e página de detalhe, com os dados do autor (nunca a senha) - Rate limit por IP contra força bruta no login e spam de cadastro
- Validação de entrada com Zod e mensagens de erro em português
- Frontend com home paginada, login, cadastro, publicação, rascunhos, perfil e detalhe do post
(Server Components e Server Actions, token em cookie
httpOnly)
- Node.js 22.x (testado com 22.22.3)
- npm 10.x
- MySQL 8.x ou MariaDB 10.x/11.x rodando na porta
3306 - Git
git clone https://github.com/telinii/blog.git
cd blogConecte no MySQL/MariaDB como root:
mysql -u root -pE execute:
CREATE DATABASE IF NOT EXISTS bloggers;
CREATE DATABASE IF NOT EXISTS bloggers_test CHARACTER SET utf8mb4;
CREATE USER IF NOT EXISTS 'blog_user'@'localhost' IDENTIFIED BY 'SUA_SENHA';
GRANT ALL PRIVILEGES ON bloggers.* TO 'blog_user'@'localhost';
GRANT ALL PRIVILEGES ON bloggers_test.* TO 'blog_user'@'localhost';
FLUSH PRIVILEGES;
bloggers_testé usado pela suíte de testes (npm test). Ela aplica as migrations e roda contra esse banco, sem tocar no banco de desenvolvimento.
Para usar
npx prisma migrate devem desenvolvimento (ele cria um banco temporário de shadow), conceda privilégio global:GRANT ALL PRIVILEGES ON *.* TO 'blog_user'@'localhost';Para apenas rodar o projeto, o grant embloggers.*já basta.
cd backend
cp .env.example .envEdite backend/.env:
DATABASE_URL="mysql://blog_user:SUA_SENHA@localhost:3306/bloggers"
DATABASE_URL_TEST="mysql://blog_user:SUA_SENHA@localhost:3306/bloggers_test"
JWT_SECRET="uma-string-longa-e-aleatoria"Variáveis opcionais de rate limit (os valores abaixo são os padrões):
LOGIN_RATE_LIMIT_MAX=5 # tentativas falhas de login por 15 min
CADASTRO_RATE_LIMIT_MAX=10 # cadastros por hora
# TRUST_PROXY=1 # só atrás de proxy confiável (Railway/Nginx)Gere um segredo forte com:
openssl rand -base64 32Use a senha real do usuário
blog_usernaDATABASE_URL. Se ela tiver caracteres especiais (@,:,/,#), eles precisam ser percent-encoded na URL.
# dentro de backend/
npm install
npx prisma generate
npx prisma migrate deployprisma generatecria o Prisma Client emsrc/generated/prisma.prisma migrate deployaplica as migrations e cria as tabelas.
cd backend
npm run devA API ficará disponível em http://localhost:3000.
Verifique:
curl http://localhost:3000
# {"message":"API Blog online","endpoints":["/users","/login","/posts"]}Na primeira requisição pode aparecer um
pool timeout: é o pool de conexões do Prisma aquecendo. Basta repetir a requisição.
cd frontend
npm install
npm run devA interface ficará disponível em http://localhost:3001.
O frontend consome a API em http://localhost:3000 por padrão. Para apontar
para outra URL, crie frontend/.env.local:
API_URL="http://localhost:3000"
API_URLé lida apenas no servidor (Server Component), então não é exposta ao browser e não sofre CORS.
As imagens enviadas ficam em backend/uploads/ (ignorada pelo Git) e são
servidas pela API em /uploads/<uuid>.<ext>. O campo capa guarda esse
caminho, não o binário.
Em produção com disco efêmero (Railway, containers), essa pasta some a cada
deploy. No docker compose ela está no volume uploads; em outros hosts use
um volume persistente ou um storage externo (S3/R2) e guarde a URL completa no
campo capa.
Atalho para ver tudo rodando sem instalar Node nem MySQL na máquina:
cp .env.docker.example .env # edite o JWT_SECRET
docker compose up --build- interface: http://localhost:3001
- API: http://localhost:3000
O que cada serviço faz:
db— MySQL 8 com healthcheck; a API só sobe depois que ele aceita conexão.backend— aplicaprisma migrate deployno boot (docker-entrypoint.sh), roda com usuário sem root e guarda as capas no volumeuploads.frontend— build comoutput: "standalone"(ligado porBUILD_STANDALONE=1no Dockerfile, para onext startlocal não avisar); conversa com a API pela rede interna (API_URL=http://backend:3000) e publica as capas comPUBLIC_API_URL, que é o endereço que o navegador consegue alcançar.
docker compose down preserva banco e capas; docker compose down -v apaga os
dois volumes. As variáveis e os padrões estão em .env.docker.example.
Base: http://localhost:3000
| Método | Rota | Autenticação | Descrição |
|---|---|---|---|
GET |
/ |
— | Health check |
POST |
/users |
— | Cria um usuário |
POST |
/login |
— | Autentica e retorna { token } |
POST |
/posts |
Bearer token | Cria um post (JSON ou multipart/form-data com capa); publicado: false cria rascunho |
PATCH |
/posts/:id |
Bearer token (autor) | Edita o post; 403 se não for o autor; aceita publicado |
DELETE |
/posts/:id |
Bearer token (autor) | Apaga o post e a capa do disco; 403 se não for o autor; responde 204 |
GET |
/posts |
— | Lista posts publicados com o autor, paginados (limit/offset, total em X-Total-Count) |
GET |
/posts/:id |
— | Retorna um post com o autor (400 id inválido, 404 não encontrado); rascunho só para o autor |
GET |
/rascunhos |
Bearer token | Rascunhos do dono do token, paginados (total em X-Total-Count) |
GET |
/users/me |
Bearer token | Perfil do dono do token |
PATCH |
/users/me |
Bearer token | Atualiza nome e bio do dono do token |
Criar usuário (senha de 10 a 20 caracteres):
curl -X POST http://localhost:3000/users \
-H "Content-Type: application/json" \
-d '{"nome":"Maria","email":"maria@example.com","bio":"Learning dev","senha":"senha12345"}'Login:
curl -X POST http://localhost:3000/login \
-H "Content-Type: application/json" \
-d '{"email":"maria@example.com","senha":"senha12345"}'
# {"token":"eyJhbGciOiJIUzI1NiIs..."}Criar post (o autor vem do token, não do body):
TOKEN=$(curl -s -X POST http://localhost:3000/login \
-H "Content-Type: application/json" \
-d '{"email":"maria@example.com","senha":"senha12345"}' \
| grep -o '"token":"[^"]*"' | cut -d'"' -f4)
curl -X POST http://localhost:3000/posts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"titulo":"Meu primeiro post","conteudo":"Conteúdo do post","categoria":"Dev"}'Com capa (multipart; a imagem é opcional):
curl -X POST http://localhost:3000/posts \
-H "Authorization: Bearer $TOKEN" \
-F "titulo=Meu primeiro post" \
-F "conteudo=Conteúdo do post" \
-F "categoria=Dev" \
-F "capa=@/caminho/para/foto.jpg"Editar o próprio post (só o autor; 403 para os demais):
curl -X PATCH http://localhost:3000/posts/1 \
-H "Authorization: Bearer $TOKEN" \
-F "titulo=Título revisado" \
-F "conteudo=Texto novo" \
-F "categoria=Dev" \
-F "capa=@/caminho/para/nova-foto.jpg"
# Remover a capa sem enviar outra foto:
curl -X PATCH http://localhost:3000/posts/1 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"removerCapa":true}'Listar posts:
curl http://localhost:3000/postsOs testes são de integração e se viram sozinhos — não precisa da API rodando:
cd backend
npm testA suíte aplica as migrations no banco de DATABASE_URL_TEST (bloggers_test),
sobe a própria API na porta 3100 e derruba no fim. Não encosta no banco de
desenvolvimento. O arquivo rateLimit.test.mjs sobe outra instância na 3101
com limites baixos para validar os 429.
Variáveis opcionais:
BASE_URL— usa um servidor já no ar e pula o spawn e as migrationsJWT_SECRET— lida dobackend/.env
Os mesmos testes rodam no CI (.github/workflows/ci.yml) a cada push na main
e em pull request: MySQL 8 como serviço, prisma migrate deploy no banco de
teste e, no frontend, lint + tsc --noEmit + build.
A suíte cobre cadastro, login, autentic
7CC6
ação, validação, criação, edição (incluindo 403 para post de outra pessoa) e listagem de
posts, rate limit (429 após o limite) e casos de segurança (senha nunca
retornada, mensagens de erro genéricas no login, algoritmo do token fixado em
HS256).
- Senhas são hasheadas com bcrypt (10 rounds) antes de ir para o banco.
- Nenhuma resposta retorna o campo
senha. POST /loginresponde401 {"erro":"Erro no login"}tanto para e-mail inexistente quanto para senha errada, sem revelar qual falhou.- Rotas protegidas exigem
Authorization: Bearer <token>. - O middleware fixa o algoritmo
HS256e exige umidnumérico no payload. - Rate limit por IP: login 5/15min, cadastro 10/hora.
| Comando | Descrição |
|---|---|
npm run dev |
Sobe a API com tsx em modo watch |
npm test |
Sobe a API de teste na 3100 e roda a suíte |
npm run build |
Gera o Prisma Client e compila para dist/ |
npm start |
Roda a versão compilada |
| Comando | Descrição |
|---|---|
npm run dev |
Sobe o Next.js em http://localhost:3001 |
npm run build |
Build de produção |
npm start |
Serve o build em http://localhost:3001 (exige npm run build antes) |
npm run lint |
Roda o ESLint |
| Problema | Causa provável | Solução |
|---|---|---|
JWT_SECRET não está definida no .env |
backend/.env ausente ou incompleto |
Criar o .env a partir de .env.example |
DATABASE_URL não está definida no .env |
Variável ausente | Conferir backend/.env |
pool timeout na primeira request |
Pool do Prisma aquecendo | Repetir a requisição |
Can't reach database server |
MySQL/MariaDB parado ou porta errada | Iniciar o serviço e conferir a porta 3306 |
| Frontend sem posts | API parada ou API_URL errada |
Subir o backend e conferir frontend/.env.local |
Email já cadastrado |
E-mail duplicado | Usar outro e-mail |
Cannot find module ... após git pull |
Dependência nova não instalada | Rodar npm install no app correspondente |
429 Muitas tentativas |
Rate limit por IP | Esperar a janela (15 min login / 1 h cadastro) ou ajustar LOGIN_RATE_LIMIT_MAX / CADASTRO_RATE_LIMIT_MAX |
Could not find a production build |
npm start sem build |
Rodar npm run build antes, ou usar npm run dev |
| Capa não aparece | Arquivo não enviado, formato inválido ou backend reiniciado sem a pasta | Conferir se o post tem capa, testar a URL /uploads/... e revisar backend/uploads/ |
| Erro de migration por permissão | Falta de grant para shadow database | GRANT ALL PRIVILEGES ON *.* TO 'blog_user'@'localhost'; |
backend/README.md— detalhes da APIfrontend/README.md— detalhes do frontend
MIT © 2026 Luca