Posted on Nov 28

Entendendo o Pipeline do Brighter

O Brighter adota uma abordagem distinta em comparação a muitos outros frameworks, priorizando a clareza explícita em seu pipeline de tratamento de requisições. Em vez de depender de convenções ocultas ou configurações complexas, você define explicitamente o comportamento do pipeline usando atributos, garantindo controle total sobre a ordem de execução.

O Modelo da Boneca Russa (Matryoshka)

O pipeline do Brighter é arquitetado com base no Modelo da Boneca Russa. Imagine um conjunto de bonecas encaixadas: cada boneca contém uma menor em seu interior.

No Brighter, cada componente de middleware (uma "boneca") envolve o próximo na cadeia. Um método handler fica no centro. Quando uma requisição é processada, ela atravessa cada camada de middleware antes de chegar ao handler, e depois retorna passando novamente por cada camada na ordem inversa. Esse design implementa perfeitamente o Padrão Pipe and Filter.

Um recurso essencial desse modelo é a capacidade de interromper o pipeline (short-circuit). Qualquer middleware pode parar o processamento e retornar um resultado imediatamente, impedindo que a requisição chegue às camadas internas (incluindo o próprio handler).

Essa arquitetura permite que qualquer etapa do pipeline:

Execute ações antes da requisição chegar ao handler.
Encaminhe a requisição para a próxima etapa.
Execute ações após o retorno do handler interno.
Interrompa o pipeline retornando antecipadamente (cancelando o processamento).

Observação: Embora este guia use exemplos de handlers síncronos, os mesmos conceitos se aplicam a handlers assíncronos. Basta usar os atributos e classes base correspondentes (ex: RequestHandlerAsync<T>).

Adicionando um Pipeline ao Seu Handler

No Brighter, middlewares são adicionados via Atributos do C#. Você deve decorar explicitamente o método Handle do seu Request Handler.

A ordem de execução é controlada pelo parâmetro step:

Números menores executam primeiro na entrada e por último na saída.

public class SampleHandler : RequestHandler<SomeMessage> { // O 'step' define a ordem.  // Step 1 executa antes do Step 2. [RequestLogging(step: 0)] public virtual TRequest Handle(TRequest command) { ... } }

Implementando Middleware "Global"

O Brighter não oferece uma API fluente (ex: services.AddGlobalMiddleware(...)) para injetar lógica globalmente em todas as requisições. Essa é uma escolha deliberada de design para manter o pipeline explícito no nível do handler.

Porém, para aplicar lógica a todos os handlers ("middleware global"), use herança: crie um Handler Base com os atributos desejados. Todos os handlers que herdarem dessa classe adotarão o pipeline definido.

Exemplo: Criando um Handler Base com Políticas Globais

// 1. Crie um handler base com middleware comum public abstract class MyGlobalPolicyHandler<T> : RequestHandler<T> where T : class, IRequest { [RequestLogging(step: 0)] [FallbackPolicy(backstop: true, circuitBreaker: false, step: 1)] public override T Handle(T command) { // Este método propaga o comando pelo pipeline até o handler real. return base.Handle(command); } } // 2. Herde do handler base nas suas implementações public class SampleHandler : MyGlobalPolicyHandler<SomeCommand> { [UseResiliencePipeline("MyPolicy", step: 2)] public override SomeCommand Handle(SomeCommand command) { // Sua lógica de negócio principal aqui. Console.WriteLine("Handling SomeCommand"); return base.Handle(command); } }

Ordem de execução para SampleHandler:

RequestLogging → FallbackPolicy → UseResiliencePipeline → SampleHandler.Handle.

Middleware Oferecido pelo Brighter

O Brighter inclui middlewares prontos para uso:

RequestLoggingAttribute / RequestLoggingAsyncAttribute → Registra a entrada/saída do pipeline, incluindo tempo de execução e detalhes da requisição.
FallbackPolicyAttribute / FallbackPolicyAsyncAttribute → Define uma ação de fallback se a execução falhar. Chama o método Fallback do handler.
TimeoutPolicyAttribute → (Obsoleto) Define tempo máximo de execução. Prefira UseResiliencePipeline.
UsePolicyAttribute / UsePolicyAsyncAttribute → (Obsoleto) Usa políticas do Polly. Prefira UseResiliencePipeline.
UseResiliencePipelineAsyncAttribute / UseResiliencePipelineAttribute → Aplica pipelines de resiliência do Polly (retry, circuit-breaker, timeouts).
MonitorAttribute / MonitorAsyncAttribute → Permite monitoramento de handlers.
FeatureSwitchAttribute / FeatureSwitchAsyncAttribute → Habilita/desabilita dinamicamente um handler com base em um feature flag.

Implementando Seu Próprio Middleware

Para criar middleware personalizado, você precisa de duas classes por modo de execução (síncrono/assíncrono):

O Atributo: Decora o método do handler.
O Handler: Contém a lógica do middleware.

Exemplo de Implementação:

// 1. Classe do Atributo [AttributeUsage(AttributeTargets.Method)] public class MyFeatureFlagAttribute : RequestHandlerAttribute { public string FeatureName { get; } public MyFeatureFlagAttribute(string featureName, int step) : base(step, HandlerTiming.Before) { FeatureName = featureName; } public override object[] InitializerParams() { return new object[] { FeatureName }; } public override Type GetHandlerType() { // Indica qual classe handler usar para este atributo. return typeof(MyFeatureFlagHandler<>); } } // 2. Classe do Handler public class MyFeatureFlagHandler<TRequest> : RequestHandler<TRequest> where TRequest : class, IRequest { private string _featureName; private IFeatureManager _featureManager; // Gerenciador de features hipotético public override void InitializeFromAttributeParams(params object[] initializerList) { // Recebe parâmetros do método InitializerParams() _featureName = (string)initializerList[0]; _featureManager = ...; // Normalmente injetado via DI (Injeção de Dependência) } public override TRequest Handle(TRequest command) { // Verifica se a funcionalidade está habilitada if (!_featureManager.IsEnabled(_featureName)) { return command; } // Se habilitada, continua para o próximo handler no pipeline. return base.Handle(command); } } // 3. Usando o Middleware Personalizado public class DiscountHandler : RequestHandler<ApplyDiscountCommand> { [MyFeatureFlag("AdvancedDiscounts", step: 1)] public override ApplyDiscountCommand Handle(ApplyDiscountCommand command) { // Este código só executa se a funcionalidade "AdvancedDiscounts" estiver habilitada. return base.Handle(command); } }

Conclusão

O pipeline explícito e baseado em atributos do Brighter oferece clareza e controle incomparáveis sobre as preocupações transversais da sua aplicação. Ao utilizar o Modelo da Boneca Russa, você constrói pipelines de handlers robustos, bem ordenados e fáceis de manter. Seja com políticas embutidas ou middlewares personalizados, o processo permanece consistente e transparente.