Componentes de Lógica

Esta seção está atualmente em desenvolvimento. Volte em breve para documentação abrangente sobre logic components.

Logic components são pedaços de software que contêm o business logic da sua aplicação. Eles são organizados semanticamente por domínio ou funcionalidade e servem como a camada de orquestração entre controllers e adapters.

Propósito

Logic components:

• Implementam regras de negócio e domain logic

• Orquestram operações entre múltiplos adapters

• Encapsulam fluxos de trabalho complexos

• Permaneçam independentes de preocupações da camada de transporte (HTTP, WebSocket)

• Podem ser testados unitariamente de forma completa sem dependências de I/O

Localização

Logic components DEVERIAM ser colocados sob o src/logic ou src/components diretório, organizados por domínio:

src/
└── logic/
    ├── users/
    ├── content/
    ├── permissions/
    └── notifications/

Características

1. Consumo de Adapters

Logic components são os consumidores primários de adapters. Eles usam adapters para interagir com recursos externos enquanto se concentram nas regras de negócio.

export function createUserLogic(
  components: Pick<AppComponents, 'database' | 'cache' | 'logs'>
): IUserLogic {
  const { database, cache, logs } = components
  const logger = logs.getLogger('user-logic')

  async function getUserProfile(userId: string): Promise<UserProfile> {
    // Verificar cache primeiro
    const cached = await cache.get(`user:${userId}`)
    if (cached) {
      return cached
    }

    // Buscar do database
    const user = await database.query('SELECT * FROM users WHERE id = $1', [userId])
    
    // Aplicar business logic
    const profile = transformUserToProfile(user)
    
    // Cachear o resultado
    await cache.set(`user:${userId}`, profile, { ttl: 3600 })
    
    return profile
  }

  return {
    getUserProfile
  }
}

2. Regras de Negócio

Logic components aplicam regras de negócio e validação:

async function createUser(userData: CreateUserInput): Promise<User> {
  // Regra de negócio: o username deve ser único
  const existing = await database.query(
    'SELECT id FROM users WHERE username = $1',
    [userData.username]
  )
  
  if (existing.rows.length > 0) {
    throw new UserAlreadyExistsError(userData.username)
  }

  // Regra de negócio: validar dados do usuário
  if (!isValidEmail(userData.email)) {
    throw new InvalidEmailError(userData.email)
  }

  // Criar o usuário
  const user = await database.query(
    'INSERT INTO users (username, email) VALUES ($1, $2) RETURNING *',
    [userData.username, userData.email]
  )

  logger.info('User created', { userId: user.id })
  
  return user
}

3. Orquestração de Workflow

Logic components coordenam operações complexas em múltiplas etapas:

async function publishContent(
  userId: string,
  content: ContentInput
): Promise<PublishedContent> {
  // Passo 1: Validar permissions
  const canPublish = await permissions.canUserPublish(userId)
  if (!canPublish) {
    throw new UnauthorizedError('User cannot publish content')
  }

  // Passo 2: Processar content
  const processed = await processContent(content)

  // Passo 3: Armazenar content
  const stored = await storage.save(processed)

  // Passo 4: Atualizar indexes
  await searchIndex.index(stored)

  // Passo 5: Notificar subscribers
  await notifications.notifySubscribers(userId, stored)

  logger.info('Content published', { contentId: stored.id, userId })

  return stored
}

Boas Práticas

1. Responsabilidade Única

Cada logic component deve focar em um domínio ou contexto limitado:

// Bom: Focado no domínio do user
createUserLogic()
createContentLogic()
createPermissionsLogic()

// Evitar: Responsabilidades mistas
createUserAndContentLogic()

2. Injeção de Dependências

Sempre injete dependências através do parâmetro components:

export function createOrderLogic(
  components: Pick<AppComponents, 'database' | 'payments' | 'inventory' | 'logs'>
): IOrderLogic {
  // Use dependências injetadas
}

3. Tratamento de Erros

Lance erros de domínio significativos que controllers possam capturar e tratar:

// Definir erros específicos do domínio
export class InsufficientInventoryError extends Error {
  constructor(public readonly productId: string, public readonly requested: number) {
    super(`Insufficient inventory for product ${productId}. Requested: ${requested}`)
    this.name = 'InsufficientInventoryError'
  }
}

4. Business Logic Pura

Mantenha logic components livres de preocupações da camada de transporte:

// Bom: business logic pura
async function calculateOrderTotal(items: OrderItem[]): Promise<number> {
  return items.reduce((total, item) => total + item.price * item.quantity, 0)
}

// Evitar: preocupações com HTTP/camada de transporte
async function calculateOrderTotal(req: Request, res: Response): Promise<void> {
  // Não faça isso em logic components
}

Testando Logic Components

Logic components devem ser exaustivamente testados unitariamente. Veja a Testing Services (WKC) documentation para detalhes.

describe('when creating a user', () => {
  let userLogic: IUserLogic
  let mockDatabase: jest.Mocked<IDatabase>

  beforeEach(() => {
    mockDatabase = createMockDatabase()
    userLogic = createUserLogic({ database: mockDatabase, logs: mockLogs })
  })

  describe('and the username already exists', () => {
    beforeEach(() => {
      mockDatabase.query.mockResolvedValueOnce({ rows: [{ id: '123' }] })
    })

    it('should throw UserAlreadyExistsError', async () => {
      await expect(
        userLogic.createUser({ username: 'existing', email: '[email protected]' })
      ).rejects.toThrow(UserAlreadyExistsError)
    })
  })
})

Em Breve

Esta seção será expandida com:

• Exemplos detalhados de domain-driven logic components

• Padrões para lidar com workflows complexos

• Diretrizes para organizar large domain logic

• Integração com event systems

• Estratégias de caching

• Padrões de gerenciamento de transações