Projetando um sistema flexível de automação de fluxo de trabalho com o padrão Builder no PHP Laravel

A automação de fluxo de trabalho está no centro da eficiência de software moderna, permitindo que as equipes orquestrem processos de negócios complexos com clareza e controle. No ecossistema Laravel, uma abordagem comprovada que equilibra elegantemente flexibilidade e manutenção é o padrão Builder. Este artigo fornece um guia profundo e prático para projetar um sistema de automação de fluxo de trabalho usando o padrão Builder em Laravel, passando de princípios básicos para implementações avançadas e prontas para a produção.

Entender o padrão do construtor num contexto Laravel

O padrão Builder é um padrão de design criacional que separa a construção de um objeto complexo da sua representação final. Em vez de forçar um único construtor com muitos parâmetros, o padrão Builder permite-lhe construir um objeto passo a passo, tornando o processo de criação tanto legível quanto flexível.

No contexto da automação de fluxo de trabalho, o “objeto complexo” é uma sequência de etapas (um fluxo de trabalho). Usando um Construtor, você pode definir fluxos de trabalho de composição variável – adicionar, remover ou reordenar etapas – sem alterar as classes de passos subjacentes. Esta dissociação torna o sistema fácil de estender e testar. Os desenvolvedores Laravel já desfrutam de APIs fluentes, semelhantes a construtores em muitas partes do framework (por exemplo, Construtor de Consultas, Construtor de Mail), adotando a mesma filosofia para fluxos de trabalho parece natural.

As principais vantagens incluem:

Componentes Principais do Sistema de Fluxo de Trabalho

Um design limpo requer três abstrações primárias: o Workflow em si, uma interface Step e um Construtor que sabe montar etapas em um Workflow.

Definição da classe de fluxo de trabalho

A classe Workflow possui uma coleção ordenada de etapas e fornece um método para executá-las em sequência. Não deve se preocupar com as especificidades de cada etapa – apenas que eles implementem um contrato definido.

<?php

namespace App\Workflow;

class Workflow
{
 protected array $steps = [];

 public function addStep(Step $step): self
 {
 $this->steps[] = $step;
 return $this;
 }

 public function run(): void
 {
 foreach ($this->steps as $step) {
 $step->execute();
 }
 }

 public function getSteps(): array
 {
 return $this->steps;
 }
}

Esta implementação mínima é suficiente para demonstrar o conceito. Numa aplicação Laravel real, você pode injetar um ou no fluxo de trabalho, mas mesmo sem eles, o padrão permanece sólido.

Criando a Interface de Passos

Cada passo que participa de um fluxo de trabalho deve implementar uma interface comum. Isso garante que o Workflow pode chamar em qualquer etapa sem conhecer sua lógica interna.

<?php

namespace App\Workflow;

interface Step
{
 public function execute(): void;
}

Você pode expandir esta interface ao longo do tempo. Por exemplo, adicionar ou permite execução condicional e rollbacks como transações – ambos úteis em fluxos de trabalho de produção.

Implementação de Passos de Concreto

Passos concretos realizam o trabalho real. Abaixo estão exemplos de duas etapas comuns: enviar um e-mail e processar dados.

<?php

namespace App\Workflow\Steps;

use App\Workflow\Step;
use Illuminate\Support\Facades\Mail;

class EmailStep implements Step
{
 public function __construct(
 private readonly string $recipient,
 private readonly string $subject = 'Workflow Notification',
 private readonly string $body = ''
 ) {}

 public function execute(): void
 {
 Mail::raw($this->body, function ($message) {
 $message->to($this->recipient)
 ->subject($this->subject);
 });
 }
}

class DataProcessingStep implements Step
{
 public function __construct(
 private readonly array $data
 ) {}

 public function execute(): void
 {
 // Transform, validate, or persist $this->data
 // For demo: log the data
 \Log::info('Processing data', $this->data);
 }
}

Ao manter os passos pequenos e focados, você incentiva a reutilização em diferentes fluxos de trabalho.

Implementação do Construtor

A classe Construtor oferece uma interface fluente para construir um objeto Workflow. Cada método no construtor adiciona um passo configurado à instância de fluxo de trabalho interno, retornando-se para encadeamento.

<?php

namespace App\Workflow;

class WorkflowBuilder
{
 protected Workflow $workflow;

 public function __construct()
 {
 $this->workflow = new Workflow();
 }

 public function addEmailStep(string $recipient, string $subject = 'Notification', string $body = ''): self
 {
 $this->workflow->addStep(
 new Steps\EmailStep($recipient, $subject, $body)
 );
 return $this;
 }

 public function addDataProcessingStep(array $data): self
 {
 $this->workflow->addStep(
 new Steps\DataProcessingStep($data)
 );
 return $this;
 }

 public function build(): Workflow
 {
 return $this->workflow;
 }
}

Interface Fluente e Corrente

A interface fluente é o que faz o padrão do Construtor brilhar em Laravel. Os desenvolvedores podem compor um fluxo de trabalho em uma única expressão:

$workflow = (new WorkflowBuilder())
 ->addEmailStep('[email protected]', 'Welcome', 'Your account is ready.')
 ->addDataProcessingStep(['user_id' => 42, 'action' => 'register'])
 ->build();

$workflow->run();

Esta legibilidade reduz a carga cognitiva e facilita a reorganização dos passos quando as regras de negócio mudam. Para cenários mais complexos, uma classe Director[] pode encapsular vários construtores predefinidos, por exemplo, que devolve um fluxo de trabalho totalmente construído para o registro de novos usuários.

Recursos avançados de fluxo de trabalho

Um sistema de fluxo de trabalho de produção precisa de mais do que execução linear. Vamos melhorar a arquitetura para suportar etapas condicionais, manipulação de erros e persistência.

Passos Condicionais Usando Predicados

Nem todos os passos devem ser executados sempre. Ao estender a interface Step com um método , você pode tomar decisões de execução com base em dados de execução.

interface Step
{
 public function shouldExecute(Context $context): bool;
 public function execute(): void;
}

class ConditionalEmailStep implements Step
{
 public function shouldExecute(Context $context): bool
 {
 return $context->get('send_email') === true;
 }

 public function execute(): void
 {
 // send email...
 }
}

O método do Workflow verificaria então a condição de cada etapa antes de executá-la.

Tratamento de Erros e Retrocessos

Quando um passo falhar, você pode querer desfazer os passos previamente concluídos (um padrão saga). Adicione um método à interface Passo:

interface Step
{
 public function execute(): void;
 public function rollback(): void;
}

O Workflow torna-se então um gestor de transacções:

public function run(): void
{
 $completed = [];
 try {
 foreach ($this->steps as $step) {
 $step->execute();
 $completed[] = $step;
 }
 } catch (\Throwable $e) {
 // Rollback in reverse order
 foreach (array_reverse($completed) as $completedStep) {
 $completedStep->rollback();
 }
 throw $e;
 }
}

Este padrão é especialmente valioso para operações multi-step que devem manter a consistência dos dados, como transações financeiras ou ajustes de inventário.

Estado persistente do fluxo de trabalho

Os fluxos de trabalho de longo prazo (por exemplo, cadeias de aprovação do usuário) precisam persistir no seu estado entre as solicitações. A ORM Eloquente de Laravel torna isso simples.

Criar um modelo que armazena a lista de passos (serializado) e o índice de execução atual. Use uma tabela dedicada:

Schema::create('workflows', function (Blueprint $table) {
 $table->id();
 $table->text('steps'); // serialized array of Step objects
 $table->unsignedSmallInteger('current_step')->default(0);
 $table->string('status'); // pending, running, completed, failed
 $table->timestamps();
});

Ao retomar, o objeto Workflow é reconstruído a partir das etapas serializadas armazenadas (ou definições de passo que podem ser reinstanciadas usando o construtor). Um passo pode ser uma classe de trabalho Laravel, tornando a execução assíncrona nativa.

Integrando-se com o Ecosistema de Laravel

Usar Tarefas para Passos Assíncronos

Para passos que devem ser executados em segundo plano (por exemplo, enviando relatórios grandes), converta cada passo em uma tarefa Laravel. O Workflow pode enviar tarefas em sequência, ou o construtor pode embrulhar um passo dentro de uma classe de trabalho.

class DispatchJobStep implements Step
{
 public function __construct(
 private readonly object $job
 ) {}

 public function execute(): void
 {
 dispatch($this->job);
 }
}

// Usage in builder
public function addReportGenerationJobStep(int $userId): self
{
 $this->workflow->addStep(
 new DispatchJobStep(new GenerateReportJob($userId))
 );
 return $this;
}

Progresso no fluxo de trabalho de transmissão

As atualizações de UI em tempo real podem alavancar a transmissão de eventos de Laravel. Cada passo pode disparar um evento antes e depois da execução:

public function execute(): void
{
 StepStarted::dispatch($this);
 // perform work
 StepCompleted::dispatch($this);
}

Os ouvintes podem então transmitir através do WebSockets (usando Laravel Echo) para um painel de frontend.

Casos de uso real-mundo

Em cada caso, o padrão Builder permite que diferentes departamentos definam sua própria composição de fluxo de trabalho sem tocar no motor de execução subjacente.

Teste de Fluxos de Trabalho

Uma das maiores vitórias do padrão é a testabilidade. Cada Passo pode ser testado independentemente. O Construtor pode ser testado com passos simulados para verificar se a sequência correta de passos é montada. Testes de integração podem executar o fluxo de trabalho completo usando implementações falsas de serviços externos (por exemplo, ]).

public function test_email_step_is_added_to_workflow()
{
 $builder = new WorkflowBuilder();
 $workflow = $builder
 ->addEmailStep('[email protected]')
 ->build();

 $steps = $workflow->getSteps();
 $this->assertCount(1, $steps);
 $this->assertInstanceOf(EmailStep::class, $steps[0]);
}

Conclusão

O padrão Builder é um ajuste natural para construir automação flexível de fluxo de trabalho em Laravel. Ele promove código legível, configurável e testável, enquanto a interface fluente reflete a elegância que os desenvolvedores Laravel já amam. Ao estender o padrão com execução condicional, retrocessos e persistência, você pode construir um sistema que scase de ações lineares simples para orquestrações complexas e de estado.

Para aprofundar sua compreensão, explore a documentação oficial de Laravel sobre as quedas e eventos[] para execução de fluxo de trabalho assíncrono, e reveja o padrão do construtor[ no Guru de Refatorização para considerações adicionais de design.