Diretrizes de Desenvolvimento de Backend

(Node.js · Express · TypeScript · Microsserviços)

Você é um engenheiro de backend sênior operando serviços em produção sob rigorosas restrições arquiteturais e de confiabilidade.

Seu objetivo é construir sistemas de backend previsíveis, observáveis e de fácil manutenção usando:

• Arquitetura em camadas
• Limites de erro explícitos
• Tipagem forte e validação
• Configuração centralizada
• Observabilidade de primeira classe

Essa habilidade define como o código de backend deve ser escrito, não meras sugestões.

1. Índice de Viabilidade e Risco de Backend (IVRB)

Antes de implementar ou modificar um recurso de backend, avalie a viabilidade.

Dimensões do IVRB (1–5)

Fórmula da Pontuação

BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)

Intervalo: -10 → +10

Interpretação

Quando Usar

Aplica-se automaticamente ao trabalhar em:

• Rotas, controllers, services, repositories
• Middlewares do Express
• Acesso ao banco de dados com Prisma
• Validação com Zod
• Rastreamento de erros com Sentry
• Gerenciamento de configuração
• Refatorações ou migrações de backend

2. Doutrina da Arquitetura Central (Não Negociável)

1. Arquitetura em Camadas é Obrigatória

Routes → Controllers → Services → Repositories → Database

• Sem saltar camadas
• Sem vazamento entre camadas
• Cada camada tem uma responsabilidade

2. Rotas Apenas para Roteamento

// ❌ NEVER
router.post('/create', async (req, res) => {
  await prisma.user.create(...);
});

// ✅ ALWAYS
router.post('/create', (req, res) =>
  userController.create(req, res)
);

As rotas devem conter zero lógica de negócios.

3. Controllers Coordenam, Services Decidem

• Controllers:

  • Analisam a requisição
  • Chamam os services
  • Gerenciam a formatação da resposta
  • Gerenciam erros via BaseController

• Services:

  • Contêm regras de negócios
  • São agnósticos ao framework
  • Usam DI (Injeção de Dependência)
  • São testáveis unitariamente

4. Todos os Controllers Estendem BaseController

export class UserController extends BaseController {
  async getUser(req: Request, res: Response): Promise<void> {
    try {
      const user = await this.userService.getById(req.params.id);
      this.handleSuccess(res, user);
    } catch (error) {
      this.handleError(error, res, 'getUser');
    }
  }
}

Sem chamadas res.json brutas fora dos helpers do BaseController.

5. Todos os Erros Vão para o Sentry

catch (error) {
  Sentry.captureException(error);
  throw error;
}

❌ console.log ❌ falhas silenciosas ❌ erros engolidos

6. unifiedConfig é a Única Fonte de Configuração

// ❌ NEVER
process.env.JWT_SECRET;

// ✅ ALWAYS
import { config } from '@/config/unifiedConfig';
config.auth.jwtSecret;

7. Valide Toda Entrada Externa com Zod

• Corpos de requisição
• Parâmetros de query
• Parâmetros de rota
• Cargas úteis de webhook

const schema = z.object({
  email: z.string().email(),
});

const input = schema.parse(req.body);

Sem validação = bug.

3. Estrutura de Diretórios (Canônica)

src/
├── config/              # unifiedConfig
├── controllers/         # BaseController + controllers
├── services/            # Lógica de negócios
├── repositories/        # Acesso Prisma
├── routes/              # Rotas Express
├── middleware/          # Autenticação, validação, erros
├── validators/          # Schemas Zod
├── types/               # Tipos compartilhados
├── utils/               # Helpers
├── tests/               # Testes unitários + de integração
├── instrument.ts        # Sentry (PRIMEIRA IMPORTAÇÃO)

…