wshobson/nodejs-backend-patterns

O que nodejs-backend-patterns faz?

Construa serviços backend Node.js prontos para produção com Express/Fastify, implementando padrões de middleware, tratamento de erros, autenticação, integração com banco de dados e melhores práticas de design de API. Use ao criar servidores Node.js, APIs REST, backends GraphQL ou arquiteturas de microsserviços.

Visão Geral

Este skill fornece um conjunto de padrões e melhores práticas para o desenvolvimento de backend em Node.js, cobrindo:

• Estrutura de Projeto: Organização modular e escalável de código.
• Middleware: Criação e composição de middlewares para Express e Fastify.
• Tratamento de Erros: Padrões centralizados e consistentes para lidar com exceções.
• Autenticação e Autorização: Implementação com JWT, OAuth2 e sessões.
• Integração com Banco de Dados: Exemplos com PostgreSQL (via Prisma/TypeORM) e MongoDB (via Mongoose).
• Design de API: RESTful e GraphQL, com validação de entrada e versionamento.
• Microsserviços: Comunicação entre serviços, health checks e logging.

Pré-requisitos

• Node.js 18+ instalado
• Framework escolhido: Express ou Fastify
• Gerenciador de pacotes: npm, yarn ou pnpm
• Conhecimento básico de JavaScript/TypeScript

Estrutura Recomendada

meu-projeto/
├── src/
│   ├── config/          # Configurações (banco, auth, etc.)
│   ├── controllers/      # Lógica de controle das rotas
│   ├── middleware/        # Middlewares customizados
│   ├── models/           # Modelos de dados (ORM/ODM)
│   ├── routes/           # Definição de rotas
│   ├── services/         # Lógica de negócio
│   ├── utils/            # Funções utilitárias
│   └── app.js            # Ponto de entrada
├── tests/
├── .env.example
├── .gitignore
└── package.json

Exemplo Rápido com Express

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

// Middleware global
app.use(express.json());

// Rota simples
app.get('/api/health', (req, res) => {
  res.json({ status: 'OK', timestamp: new Date() });
});

// Tratamento de erros centralizado
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ message: 'Erro interno do servidor' });
});

app.listen(3000, () => console.log('Servidor rodando na porta 3000'));

Exemplo Rápido com Fastify

const fastify = require('fastify')({ logger: true });

fastify.get('/api/health', async (request, reply) => {
  return { status: 'OK', timestamp: new Date() };
});

fastify.setErrorHandler((error, request, reply) => {
  reply.status(500).send({ message: 'Erro interno do servidor' });
});

const start = async () => {
  try {
    await fastify.listen({ port: 3000 });
    console.log('Servidor rodando na porta 3000');
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};
start();

Integração com Banco de Dados

PostgreSQL (Prisma)

1. Instale o Prisma: npm install @prisma/client
2. Configure o schema em prisma/schema.prisma
3. Execute npx prisma migrate dev
4. Use o cliente no serviço:

const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

async function getUsers() {
  return await prisma.user.findMany();
}

MongoDB (Mongoose)

1. Instale: npm install mongoose
2. Conecte:

const mongoose = require('mongoose');
mongoose.connect(process.env.MONGODB_URI);

Autenticação com JWT

const jwt = require('jsonwebtoken');

function generateToken(user) {
  return jwt.sign({ id: user.id, role: user.role }, process.env.JWT_SECRET, { expiresIn: '1h' });
}

function authenticate(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ message: 'Token ausente' });
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (err) {
    res.status(401).json({ message: 'Token inválido' });
  }
}

Boas Práticas

• Variáveis de Ambiente: Use .env para configurações sensíveis.
• Validação: Utilize Joi ou zod para validar entradas.
• Testes: Escreva testes unitários e de integração (Jest, Mocha).
• Logging: Implemente logging estruturado (Pino, Winston).
• Security: Adote helmet, rate limiting e CORS.

Compatibilidade

• Plataformas: Claude Code, Cursor, Codex e outros agentes de IA.
• Frameworks: Express 4.x e Fastify 4.x.
• Bancos de Dados: PostgreSQL, MySQL, MongoDB (exemplos inclusos).

Contribuição

Sinta-se à vontade para contribuir com melhorias, correções ou novos exemplos via pull request.