Express API (TypeScript) — Didática de SOLID

API REST de exemplo construída com Express e TypeScript, organizada em camadas e pensada para fins didáticos: demonstrar, na prática, os princípios SOLID em uma aplicação simples de livros.

Sumário

• Objetivo Didático
• Visão Geral
• Arquitetura e Fluxo
• Princípios SOLID na Prática
• Endpoints
• Como Rodar
• Estrutura de Pastas
• Roteiro de Palestra (Sugestão)
• Exercícios Propostos
• Perguntas Frequentes (FAQ)

---

Objetivo Didático

• Mostrar como aplicar SOLID de forma pragmática em uma API Express.
• Destacar separação de responsabilidades, uso de contratos (interfaces) e injeção de dependências.
• Facilitar demonstrações e live coding em aulas/palestras.

Visão Geral

• CRUD de livros: listar, buscar por ID, filtrar por ano, criar, atualizar e remover.
• Dados em memória para simplificar o foco nos princípios e arquitetura.
• Camadas claras: Controller → Service → Repository → Database, com middlewares e validators auxiliares.

Arquitetura e Fluxo

• Camadas:

  • Controller (src/controllers/book-controller.ts): orquestra Request/Response e delega ao serviço.
  • Service (src/services/book-service.ts): regras de negócio e casos de uso.
  • Repository (src/repositories/book-repository.ts): contrato genérico e implementação para acesso a dados.
  • Database (src/database.ts): dados em memória e modelo Book.
  • Validators (src/validators/validator.ts): contratos e validação específica por recurso.
  • Middlewares (src/middlewares.ts): preocupações transversais (log e validação básica de request).
  • Routes (src/routes.ts): define endpoints e realiza o wiring das dependências.

• Fluxo da requisição:

  • Request → middlewares (logger/validação) → controller → service → repository → database → Response.

Princípios SOLID na Prática

• SRP (Responsabilidade Única)

  • src/services/book-service.ts: cada método faz uma única coisa (listar, buscar, filtrar por ano, criar, atualizar, excluir).
  • src/validators/validator.ts: BookValidator e AuthorValidator validam apenas seus respectivos modelos.
  • src/middlewares.ts: loggerMiddleware apenas loga; validateBookMiddleware apenas valida formato.
  • src/controllers/book-controller.ts: handlers focados em orquestrar request/response.

• OCP (Aberto/Fechado)

  • IRepository<T> em src/repositories/book-repository.ts: permite novas implementações sem modificar a interface.
  • Validadores em src/validators/validator.ts: adicionar novos validadores sem alterar os existentes.
  • BookService aberto a novas fontes de dados via IRepository sem alterar a lógica do serviço.

• LSP (Substituição de Liskov)

  • Qualquer implementação de IRepository<Book> pode substituir BookRepository mantendo o contrato esperado; BookService continua funcionando.
  • AuthorValidator implementa IValidator e substitui sem quebrar comportamento.

• ISP (Segregação de Interfaces)

  • src/controllers/book-controller.ts: interfaces específicas (IGetBooks, ICreateBook, IUpdateBook, IDeleteBook) evitam depender de métodos não usados.
  • IValidator define apenas o contrato mínimo de validação.

• DIP (Inversão de Dependência)

  • BookService depende da abstração IRepository<Book>, não da implementação concreta.
  • src/routes.ts: composição das dependências na borda (instancia repositório → serviço → controller). Em projetos maiores, considerar mover o wiring para app.ts (composition root) ou usar um container de DI.

Endpoints

Base: http://localhost:3000

• GET /

  • Status do servidor.
  • Retorna: {"message":"servidor online!"}

• GET /books

  • Lista todos os livros.
  • Query opcional: ano (filtra por ano), ex.: /books?ano=1980.

• GET /books/:id

  • Busca um livro por ID.
  • 200: objeto do livro; 404: {"message":"Livro não encontrado!"}.

• POST /books

  • Cria um livro.
  • Middleware: validateBookMiddleware valida nome (string) e ano (number).
  • Exemplo de corpo:

    {
      "nome": "Hábitos Atômicos",
      "ano": 2024
    }

  • 201: objeto criado; 400: mensagens de validação.

• PATCH /books/:id

  • Atualiza parcialmente um livro.
  • Exemplo:

    {
      "nome": "Novo Título"
    }

  • 200: objeto atualizado; 404: não encontrado.

• DELETE /books/:id

  • Remove um livro.
  • 204: sem conteúdo; 404: não encontrado.

Modelo Book

Arquivo src/database.ts:

export interface Book {
  id?: number;
  nome?: string;
  ano?: number;
}

Como Rodar

Pré-requisitos:

• Node.js (LTS recomendado)
• npm

Instalação:

npm install

Desenvolvimento:

npm run dev

Hot reload (dev com reinício automático):

npm run watch

Build (TypeScript → JavaScript):

npm run build

Start (produção; depende do build):

npm start

Observações:

• Variável PORT pode ser usada para alterar a porta (padrão 3000).
• Em dev, o entrypoint é src/app.ts; em prod, dist/index.js (via prestart).

Estrutura de Pastas

├── .gitignore
├── README.MD
├── package-lock.json
├── package.json
├── src/
│   ├── app.ts                 # Inicializa Express e monta o router
│   ├── controllers/
│   │   └── book-controller.ts # Handlers HTTP orquestram o serviço
│   ├── database.ts            # Modelo e dados em memória
│   ├── middlewares.ts         # Logger e validação básica
│   ├── repositories/
│   │   └── book-repository.ts # Contrato genérico + implementação Book
│   ├── routes.ts              # Endpoints e wiring das dependências
│   ├── services/
│   │   └── book-service.ts    # Regras de negócio
│   └── validators/
│       └── validator.ts       # Contratos e validadores
└── tsconfig.json

Conclusão

Esta aplicação oferece um terreno simples e eficaz para ensinar e praticar SOLID em APIs Express. A separação em camadas, o uso de interfaces e a injeção de dependências permitem evoluir e testar com mínimo acoplamento.