Casos de Uso & Serviços

Q: Consultas devem ser casos de uso?

Sim. GetOrderById é um caso de uso de consulta - somente leitura, sem efeitos colaterais.

Q: Como as transações se encaixam?

Caso de uso chama a porta unitOfWork.withTransaction(async () => { ... }) ou método de repositório que aceita cliente.

Q: E sobre Fastify?

Mesmo padrão - rota chama placeOrder.execute; use a fábrica FastifyPlugin para injeção.

Q: Casos de uso registram logs?

Aceite uma porta Logger ou um logger estruturado injetado - registre eventos de negócio, não PII bruto.

Q: Mapeamento NestJS?

OrdersService frequentemente se torna casos de uso ou um invólucro fino em torno deles - evite um OrdersService gordo e centralizador.

A camada de aplicação implementa casos de uso - etapas de orquestração que cumprem uma intenção do usuário ("Fazer pedido", "Reembolsar fatura"). Serviços agrupam casos de uso relacionados quando eles compartilham políticas; repositórios e gateways ficam atrás de portas.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// application/place-order.ts
export class PlaceOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly inventory: InventoryPort
  ) {}
 
  async execute(cmd: { customerId: string; sku: string; qty: number }) {
    await this.inventory.reserve(cmd.sku, cmd.qty);
    const order = { id: crypto.randomUUID(), ...cmd, status: "pending" as const };
    await this.orders.save(order);
    return order;
  }
}

Quando usar isso:

Manipuladores de rota cresceram além de 30 linhas com regras de negócio
Mesmo fluxo invocado de consumidor HTTP e de fila
Você precisa de limites transacionais documentados por operação
Testes unitários exigem orquestração sem banco de dados

Exemplo de Trabalho

// domain/ports/order-repository.ts
export type Order = { id: string; customerId: string; sku: string; qty: number; status: string };
export interface OrderRepository {
  save(order: Order): Promise<void>;
}
 
// domain/ports/inventory-port.ts
export interface InventoryPort {
  reserve(sku: string, qty: number): Promise<void>;
}
 
// application/place-order.ts
export class PlaceOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly inventory: InventoryPort
  ) {}
 
  async execute(cmd: { customerId: string; sku: string; qty: number }) {
    if (cmd.qty <= 0) throw new AppError("INVALID_QTY", 400);
    await this.inventory.reserve(cmd.sku, cmd.qty);
    const order = { id: crypto.randomUUID(), ...cmd, status: "pending" };
    await this.orders.save(order);
    return order;
  }
}
 
// application/order-service.ts - fachada opcional para comandos relacionados
export class OrderService {
  constructor(
    private readonly placeOrder: PlaceOrder,
    private readonly cancelOrder: CancelOrder
  ) {}
 
  place(cmd: Parameters<PlaceOrder["execute"]>[0]) {
    return this.placeOrder.execute(cmd);
  }
  cancel(orderId: string) {
    return this.cancelOrder.execute(orderId);
  }
}
 
// infrastructure/http/orders-controller.ts
import express from "express";
import type { PlaceOrder } from "../../application/place-order";
 
export function ordersRouter(placeOrder: PlaceOrder) {
  const router = express.Router();
  router.post("/", async (req, res, next) => {
    try {
      const order = await placeOrder.execute(req.body);
      res.status(201).json({ data: toOrderDto(order) });
    } catch (err) {
      next(err);
    }
  });
  return router;
}
 
function toOrderDto(order: { id: string; status: string }) {
  return { id: order.id, status: order.status };
}
 
class AppError extends Error {
  constructor(
    public code: string,
    public status: number
  ) {
    super(code);
  }
}
 
class CancelOrder {
  async execute(_orderId: string) {
    return { cancelled: true };
  }
}

O que isso demonstra:

PlaceOrder sequencia inventário e persistência
Camada HTTP mapeia resultado de domínio para DTO JSON
OrderService opcional quando múltiplos comandos compartilham a entrada do módulo
Erros de domínio levantados no caso de uso; o adaptador HTTP não ramifica em strings

Mergulho Profundo

Como Funciona

Caso de uso = uma operação específica da aplicação com entrada/saída claras
Serviço de aplicação = fachada que exporta múltiplos casos de uso para adaptadores
Sem detalhes de I/O - SQL, códigos de status HTTP e retentativas de SDK vivem fora
Transações - caso de uso abre um limite transacional ou delega para uma porta de unidade de trabalho

Convenções de Nomenclatura

Padrão de nome	Exemplo
Comando verbal	`PlaceOrder`, `CancelSubscription`
Consulta	`GetOrderById`, `ListOpenInvoices`
Serviço de política	`PricingService` (regras puras, sem I/O)

Caso de Uso vs. Serviço de Domínio

Camada	Responsabilidade
Serviço de domínio	Regras de negócio puras em entidades
Caso de uso	Orquestrar portas, transações, verificações de autorização

Notas de TypeScript

// Tipos de entrada/saída explícitos para mapeamento do adaptador
export type PlaceOrderInput = { customerId: string; sku: string; qty: number };
export type PlaceOrderResult = { id: string; status: "pending" };

Armadilhas

Caso de uso "Deus" - OrderEverything com 12 responsabilidades. Correção: Dividir por comando/consulta.
Caso de uso retornando Resposta HTTP - Acopla ao Express. Correção: Retornar objeto de domínio ou tipo Result.
Pular autorização no caso de uso - Apenas middleware verifica papéis. Correção: Caso de uso impõe canPlaceOrder(user, cmd).
Caso de uso anêmico - Apenas chama o repositório sem regras. Correção: Talvez a rota seja suficiente; não adicionar camadas por cerimônia.
Orquestração duplicada em worker e HTTP - Copiar e colar diverge. Correção: Ambos chamam o mesmo PlaceOrder.execute.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Script de transação na rota	CRUD de 3 endpoints	Regras e orquestração crescem
Manipuladores CQRS	Divisão de escala de leitura/escrita	CRUD simples
Apenas eventos de domínio	Fluxos de trabalho com muitos eventos	Fluxos síncronos simples
Manipuladores de comando Nest	Módulo CQRS Nest adotado	Serviços Express simples

FAQs

Classe ou função por caso de uso?

Ambos funcionam. Classes ajudam contêineres de DI; funções com parâmetro deps servem para DI manual.

Onde vai a validação Zod?

O adaptador HTTP valida a forma; o caso de uso valida regras de negócio (inventário disponível, conta ativa).

Consultas devem ser casos de uso?

Sim. GetOrderById é um caso de uso de consulta - somente leitura, sem efeitos colaterais.

Como as transações se encaixam?

Caso de uso chama a porta unitOfWork.withTransaction(async () => { ... }) ou método de repositório que aceita cliente.

Casos de uso podem chamar outros casos de uso?

Prefira compor serviços de domínio menores ou helpers privados compartilhados. Cadeias profundas de casos de uso escondem o fluxo.

E sobre Fastify?

Mesmo padrão - rota chama placeOrder.execute; use a fábrica FastifyPlugin para injeção.

Qual o tamanho de um arquivo de caso de uso?

Abaixo de 150 linhas. Extraia funções privadas ou serviços de domínio quando a ramificação explodir.

Casos de uso registram logs?

Aceite uma porta Logger ou um logger estruturado injetado - registre eventos de negócio, não PII bruto.

Como lidar com idempotência?

A verificação da chave de idempotência pertence ao caso de uso ou a um caso de uso decorador dedicado IdempotentPlaceOrder.

Mapeamento NestJS?

OrdersService frequentemente se torna casos de uso ou um invólucro fino em torno deles - evite um OrdersService gordo e centralizador.

Relacionados

Noções Básicas de Modularidade - rotas finas
Padrão Repositório - porta de persistência
Padrões de Injeção de Dependência - conectando casos de uso
Arquitetura Hexagonal em Node - posicionamento de camadas
Tratamento de Erros no Express - mapear AppError para HTTP

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// application/place-order.ts
export class PlaceOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly inventory: InventoryPort
  ) {}
 
  async execute(cmd: { customerId: string; sku: string; qty: number }) {
    await this.inventory.reserve(cmd.sku, cmd.qty);
    const order = { id: crypto.randomUUID(), ...cmd, status: "pending" as const };
    await this.orders.save(order);
    return order;
  }
}

Quando usar isso:

Manipuladores de rota cresceram além de 30 linhas com regras de negócio
Mesmo fluxo invocado de consumidor HTTP e de fila
Você precisa de limites transacionais documentados por operação
Testes unitários exigem orquestração sem banco de dados

Exemplo de Trabalho

// domain/ports/order-repository.ts
export type Order = { id: string; customerId: string; sku: string; qty: number; status: string };
export interface OrderRepository {
  save(order: Order): Promise<void>;
}
 
// domain/ports/inventory-port.ts
export interface InventoryPort {
  reserve(sku: string, qty: number): Promise<void>;
}
 
// application/place-order.ts
export class PlaceOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly inventory: InventoryPort
  ) {}
 
  async execute(cmd: { customerId: string; sku: string; qty: number }) {
    if (cmd.qty <= 0) throw new AppError("INVALID_QTY", 400);
    await this.inventory.reserve(cmd.sku, cmd.qty);
    const order = { id: crypto.randomUUID(), ...cmd, status: "pending" };
    await this.orders.save(order);
    return order;
  }
}
 
// application/order-service.ts - fachada opcional para comandos relacionados
export class OrderService {
  constructor(
    private readonly placeOrder: PlaceOrder,
    private readonly cancelOrder: CancelOrder
  ) {}
 
  place(cmd: Parameters<PlaceOrder["execute"]>[0]) {
    return this.placeOrder.execute(cmd);
  }
  cancel(orderId: string) {
    return this.cancelOrder.execute(orderId);
  }
}
 
// infrastructure/http/orders-controller.ts
import express from "express";
import type { PlaceOrder } from "../../application/place-order";
 
export function ordersRouter(placeOrder: PlaceOrder) {
  const router = express.Router();
  router.post("/", async (req, res, next) => {
    try {
      const order = await placeOrder.execute(req.body);
      res.status(201).json({ data: toOrderDto(order) });
    } catch (err) {
      next(err);
    }
  });
  return router;
}
 
function toOrderDto(order: { id: string; status: string }) {
  return { id: order.id, status: order.status };
}
 
class AppError extends Error {
  constructor(
    public code: string,
    public status: number
  ) {
    super(code);
  }
}
 
class CancelOrder {
  async execute(_orderId: string) {
    return { cancelled: true };
  }
}

O que isso demonstra:

PlaceOrder sequencia inventário e persistência
Camada HTTP mapeia resultado de domínio para DTO JSON
OrderService opcional quando múltiplos comandos compartilham a entrada do módulo
Erros de domínio levantados no caso de uso; o adaptador HTTP não ramifica em strings

Mergulho Profundo

Como Funciona

Caso de uso = uma operação específica da aplicação com entrada/saída claras
Serviço de aplicação = fachada que exporta múltiplos casos de uso para adaptadores
Sem detalhes de I/O - SQL, códigos de status HTTP e retentativas de SDK vivem fora
Transações - caso de uso abre um limite transacional ou delega para uma porta de unidade de trabalho

Convenções de Nomenclatura

Padrão de nome	Exemplo
Comando verbal	`PlaceOrder`, `CancelSubscription`
Consulta	`GetOrderById`, `ListOpenInvoices`
Serviço de política	`PricingService` (regras puras, sem I/O)

Caso de Uso vs. Serviço de Domínio

Camada	Responsabilidade
Serviço de domínio	Regras de negócio puras em entidades
Caso de uso	Orquestrar portas, transações, verificações de autorização

Notas de TypeScript

// Tipos de entrada/saída explícitos para mapeamento do adaptador
export type PlaceOrderInput = { customerId: string; sku: string; qty: number };
export type PlaceOrderResult = { id: string; status: "pending" };

Armadilhas

Caso de uso "Deus" - OrderEverything com 12 responsabilidades. Correção: Dividir por comando/consulta.
Caso de uso retornando Resposta HTTP - Acopla ao Express. Correção: Retornar objeto de domínio ou tipo Result.
Pular autorização no caso de uso - Apenas middleware verifica papéis. Correção: Caso de uso impõe canPlaceOrder(user, cmd).
Caso de uso anêmico - Apenas chama o repositório sem regras. Correção: Talvez a rota seja suficiente; não adicionar camadas por cerimônia.
Orquestração duplicada em worker e HTTP - Copiar e colar diverge. Correção: Ambos chamam o mesmo PlaceOrder.execute.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Script de transação na rota	CRUD de 3 endpoints	Regras e orquestração crescem
Manipuladores CQRS	Divisão de escala de leitura/escrita	CRUD simples
Apenas eventos de domínio	Fluxos de trabalho com muitos eventos	Fluxos síncronos simples
Manipuladores de comando Nest	Módulo CQRS Nest adotado	Serviços Express simples

FAQs

Classe ou função por caso de uso?

Ambos funcionam. Classes ajudam contêineres de DI; funções com parâmetro deps servem para DI manual.

Onde vai a validação Zod?

O adaptador HTTP valida a forma; o caso de uso valida regras de negócio (inventário disponível, conta ativa).

Consultas devem ser casos de uso?

Sim. GetOrderById é um caso de uso de consulta - somente leitura, sem efeitos colaterais.

Como as transações se encaixam?

Caso de uso chama a porta unitOfWork.withTransaction(async () => { ... }) ou método de repositório que aceita cliente.

Casos de uso podem chamar outros casos de uso?

Prefira compor serviços de domínio menores ou helpers privados compartilhados. Cadeias profundas de casos de uso escondem o fluxo.

E sobre Fastify?

Mesmo padrão - rota chama placeOrder.execute; use a fábrica FastifyPlugin para injeção.

Qual o tamanho de um arquivo de caso de uso?

Abaixo de 150 linhas. Extraia funções privadas ou serviços de domínio quando a ramificação explodir.

Casos de uso registram logs?

Aceite uma porta Logger ou um logger estruturado injetado - registre eventos de negócio, não PII bruto.

Como lidar com idempotência?

A verificação da chave de idempotência pertence ao caso de uso ou a um caso de uso decorador dedicado IdempotentPlaceOrder.

Mapeamento NestJS?

OrdersService frequentemente se torna casos de uso ou um invólucro fino em torno deles - evite um OrdersService gordo e centralizador.

Relacionados

Noções Básicas de Modularidade - rotas finas
Padrão Repositório - porta de persistência
Padrões de Injeção de Dependência - conectando casos de uso
Arquitetura Hexagonal em Node - posicionamento de camadas
Tratamento de Erros no Express - mapear AppError para HTTP

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Casos de Uso & Serviços

Buscar na documentação

Casos de Uso & Serviços