Como criar métodos encadeados com Fluent Interface?

Print 🖨 PDF 📄 eBook 📱

A Fluent Interface é um padrão de design que permite encadear métodos para criar um código mais legível, parecido com uma linguagem natural. Esse padrão é particularmente útil em cenários complexos, como o de configuração e emissão de documentos fiscais, onde diversos parâmetros precisam ser definidos antes de uma ação ser executada.

Neste artigo, exploraremos como implementar esse padrão em Delphi, aplicando-o a um caso real: a emissão de uma Nota Fiscal Eletrônica (NF-e). A implementação demonstrará como utilizar métodos fluentes para configurar dados obrigatórios, como emitente, destinatário e itens da nota, finalizando com a validação e geração da NF-e.

Implementação de Fluent Interface para NF-e

Vamos imaginar um cenário de emissão de uma NF-e, onde precisamos configurar diferentes aspectos: emitente, destinatário, itens e tributos. Abaixo está a implementação com métodos fluentes.

A Classe Principal TNFeBuilder


type
  TNFeBuilder = class
  private
    FEmitente: string;
    FDestinatario: string;
    FItens: TStringList;
    FTotal: Currency;
  public
    constructor Create;
    destructor Destroy; override;
    function SetEmitente(const AEmitente: string): TNFeBuilder;
    function SetDestinatario(const ADestinatario: string): TNFeBuilder;
    function AddItem(const ADescricao: string; AQuantidade: Integer; AValorUnitario: Currency): TNFeBuilder;
    function CalcularTotal: TNFeBuilder;
    function GerarXML: string;
  end;

implementation

constructor TNFeBuilder.Create;
begin
  FItens := TStringList.Create;
  FTotal := 0.0;
end;

destructor TNFeBuilder.Destroy;
begin
  FItens.Free;
  inherited;
end;

function TNFeBuilder.SetEmitente(const AEmitente: string): TNFeBuilder;
begin
  FEmitente := AEmitente;
  Result := Self;
end;

function TNFeBuilder.SetDestinatario(const ADestinatario: string): TNFeBuilder;
begin
  FDestinatario := ADestinatario;
  Result := Self;
end;

function TNFeBuilder.AddItem(const ADescricao: string; AQuantidade: Integer; AValorUnitario: Currency): TNFeBuilder;
begin
  FItens.Add(Format('%s | Qtd: %d | Unit: %.2f', [ADescricao, AQuantidade, AValorUnitario]));
  FTotal := FTotal + (AQuantidade * AValorUnitario);
  Result := Self;
end;

function TNFeBuilder.CalcularTotal: TNFeBuilder;
begin
  // Aqui podem ser aplicados cálculos de impostos ou descontos
  Result := Self;
end;

function TNFeBuilder.GerarXML: string;
begin
  Result := Format(
    '<NFe><Emitente>%s</Emitente><Destinatario>%s</Destinatario><Itens>%s</Itens><Total>%.2f</Total></NFe>',
    [FEmitente, FDestinatario, FItens.Text, FTotal]
  );
end;

type

TNFeBuilder = class

private

FEmitente: string;

FDestinatario: string;

FItens: TStringList;

FTotal: Currency;

public

constructor Create;

destructor Destroy; override;

function SetEmitente(const AEmitente: string): TNFeBuilder;

function SetDestinatario(const ADestinatario: string): TNFeBuilder;

function AddItem(const ADescricao: string; AQuantidade: Integer; AValorUnitario: Currency): TNFeBuilder;

function CalcularTotal: TNFeBuilder;

function GerarXML: string;

end;

implementation

constructor TNFeBuilder.Create;

begin

FItens := TStringList.Create;

FTotal := 0.0;

end;

destructor TNFeBuilder.Destroy;

begin

FItens.Free;

inherited;

end;

function TNFeBuilder.SetEmitente(const AEmitente: string): TNFeBuilder;

begin

FEmitente := AEmitente;

Result := Self;

end;

function TNFeBuilder.SetDestinatario(const ADestinatario: string): TNFeBuilder;

begin

FDestinatario := ADestinatario;

Result := Self;

end;

function TNFeBuilder.AddItem(const ADescricao: string; AQuantidade: Integer; AValorUnitario: Currency): TNFeBuilder;

begin

FItens.Add(Format('%s | Qtd: %d | Unit: %.2f', [ADescricao, AQuantidade, AValorUnitario]));

FTotal := FTotal + (AQuantidade * AValorUnitario);

Result := Self;

end;

function TNFeBuilder.CalcularTotal: TNFeBuilder;

begin

// Aqui podem ser aplicados cálculos de impostos ou descontos

Result := Self;

end;

function TNFeBuilder.GerarXML: string;

begin

Result := Format(

'<NFe><Emitente>%s</Emitente><Destinatario>%s</Destinatario><Itens>%s</Itens><Total>%.2f</Total></NFe>',

[FEmitente, FDestinatario, FItens.Text, FTotal]

);

end;

Exemplo de Uso:


var
  NFe: TNFeBuilder;
  XML: string;
begin
  NFe := TNFeBuilder.Create;
  try
    XML := NFe.SetEmitente('Empresa ABC LTDA')
              .SetDestinatario('João da Silva')
              .AddItem('Notebook', 1, 3500.00)
              .AddItem('Mouse', 2, 120.00)
              .CalcularTotal
              .GerarXML;

    Writeln(XML);
  finally
    NFe.Free;
  end;
end;

var

NFe: TNFeBuilder;

XML: string;

begin

NFe := TNFeBuilder.Create;

try

XML := NFe.SetEmitente('Empresa ABC LTDA')

.SetDestinatario('João da Silva')

.AddItem('Notebook', 1, 3500.00)

.AddItem('Mouse', 2, 120.00)

.CalcularTotal

.GerarXML;

Writeln(XML);

finally

NFe.Free;

end;

Saída do XML Gerado


<NFe>
  <Emitente>Empresa ABC LTDA</Emitente>
  <Destinatario>João da Silva</Destinatario>
  <Itens>
    Notebook | Qtd: 1 | Unit: 3500.00
    Mouse | Qtd: 2 | Unit: 120.00
  </Itens>
  <Total>3740.00</Total>
</NFe>

<NFe>

<Emitente>Empresa ABC LTDA</Emitente>

<Destinatario>João da Silva</Destinatario>

<Itens>

Notebook | Qtd: 1 | Unit: 3500.00

Mouse | Qtd: 2 | Unit: 120.00

</Itens>

</NFe>

Explicando o Código: Conceitos Aplicados

O padrão Fluent Interface utiliza uma técnica simples, porém poderosa, para possibilitar o encadeamento de métodos: retornar a própria instância da classe (Self). Isso permite que cada método execute sua operação e, ao mesmo tempo, devolva o controle ao objeto que iniciou a sequência. Aqui estão os principais conceitos aplicados no código:

O Uso de Self para Encadeamento

No código, cada método que modifica ou configura a classe termina com a seguinte linha:


Result := Self;

Result := Self;

O Self é uma referência para a própria instância do objeto que está executando o método. Quando o método retorna essa instância, é possível continuar chamando outros métodos sem sair do contexto do objeto. Isso cria o efeito de “fluidez” que caracteriza o padrão Fluent Interface.

Exemplo prático:

No método SetEmitente, configuramos o emitente e retornamos a instância:


function TNFeBuilder.SetEmitente(const AEmitente: string): TNFeBuilder;
begin
  FEmitente := AEmitente; // Configura o emitente
  Result := Self;         // Retorna a própria instância
end;

function TNFeBuilder.SetEmitente(const AEmitente: string): TNFeBuilder;

begin

FEmitente := AEmitente; // Configura o emitente

Result := Self; // Retorna a própria instância

end;

Ao encadear chamadas, como em:


NFe.SetEmitente('Empresa ABC LTDA')
   .SetDestinatario('João da Silva');

NFe.SetEmitente('Empresa ABC LTDA')

.SetDestinatario('João da Silva');

2. Manutenção do Estado Interno do Objeto

Cada método modifica o estado interno do objeto (TNFeBuilder), atualizando os atributos privados. Isso assegura que os dados sejam acumulados à medida que os métodos são encadeados.

Exemplo:

O método AddItem adiciona um item à lista interna e recalcula o total:


function TNFeBuilder.AddItem(const ADescricao: string; AQuantidade: Integer; AValorUnitario: Currency): TNFeBuilder;
begin
  FItens.Add(Format('%s | Qtd: %d | Unit: %.2f', [ADescricao, AQuantidade, AValorUnitario]));
  FTotal := FTotal + (AQuantidade * AValorUnitario);
  Result := Self;
end;

function TNFeBuilder.AddItem(const ADescricao: string; AQuantidade: Integer; AValorUnitario: Currency): TNFeBuilder;

begin

FItens.Add(Format('%s | Qtd: %d | Unit: %.2f', [ADescricao, AQuantidade, AValorUnitario]));

FTotal := FTotal + (AQuantidade * AValorUnitario);

Result := Self;

end;

Ao encadear múltiplos itens:


NFe.AddItem('Notebook', 1, 3500.00)
   .AddItem('Mouse', 2, 120.00);

NFe.AddItem('Notebook', 1, 3500.00)

.AddItem('Mouse', 2, 120.00);

Os itens são adicionados à lista interna FItens, e o total é atualizado após cada adição.

3. Retorno Diferente no Último Método

O último método no encadeamento (GerarXML) não retorna a instância da classe. Em vez disso, ele retorna um resultado final (uma string com o XML). Essa abordagem permite finalizar o fluxo com o dado esperado, sem interromper o padrão fluente.

Exemplo:


function TNFeBuilder.GerarXML: string;
begin
  Result := Format(
    '<NFe><Emitente>%s</Emitente><Destinatario>%s</Destinatario><Itens>%s</Itens><Total>%.2f</Total></NFe>',
    [FEmitente, FDestinatario, FItens.Text, FTotal]
  );
end;

function TNFeBuilder.GerarXML: string;

begin

Result := Format(

'<NFe><Emitente>%s</Emitente><Destinatario>%s</Destinatario><Itens>%s</Itens><Total>%.2f</Total></NFe>',

[FEmitente, FDestinatario, FItens.Text, FTotal]

);

end;

Essa distinção garante que, enquanto os métodos de configuração e processamento retornam a instância para continuar o encadeamento, o método final entrega o resultado da operação.

4. Vantagens do Fluent Interface

Legibilidade: O código resultante é claro, com métodos que se comportam como frases descritivas.
Manutenção: As configurações são aplicadas no mesmo objeto, centralizando o estado e reduzindo variáveis temporárias.
Encapsulamento: Todos os detalhes de implementação são ocultos. O desenvolvedor interage apenas com os métodos necessários.

Comparação:

Sem Fluent Interface:


var
  NFe: TNFeBuilder;
begin
  NFe := TNFeBuilder.Create;
  NFe.SetEmitente('Empresa ABC LTDA');
  NFe.SetDestinatario('João da Silva');
  NFe.AddItem('Notebook', 1, 3500.00);
  NFe.AddItem('Mouse', 2, 120.00);
  NFe.CalcularTotal;
  Writeln(NFe.GerarXML);
end;

var

NFe: TNFeBuilder;

begin

NFe := TNFeBuilder.Create;

NFe.SetEmitente('Empresa ABC LTDA');

NFe.SetDestinatario('João da Silva');

NFe.AddItem('Notebook', 1, 3500.00);

NFe.AddItem('Mouse', 2, 120.00);

NFe.CalcularTotal;

Writeln(NFe.GerarXML);

end;

Com Fluent Interface:


Writeln(
  TNFeBuilder.Create
    .SetEmitente('Empresa ABC LTDA')
    .SetDestinatario('João da Silva')
    .AddItem('Notebook', 1, 3500.00)
    .AddItem('Mouse', 2, 120.00)
    .CalcularTotal
    .GerarXML
);

Writeln(

TNFeBuilder.Create

.SetEmitente('Empresa ABC LTDA')

.SetDestinatario('João da Silva')

.AddItem('Notebook', 1, 3500.00)

.AddItem('Mouse', 2, 120.00)

.CalcularTotal

.GerarXML

);

Encadeamento Avançado com Retorno à Classe Pai

Vamos avançar um pouco mais? E se quisermos ter outras classes para preenchimento?

O conceito de encadeamento avançado com retorno à classe pai resolve um problema recorrente em APIs fluentes: a necessidade de navegar entre configurações de componentes subordinados sem perder o contexto do objeto principal. Esse modelo é especialmente útil em cenários onde partes específicas de uma configuração (como itens em uma nota fiscal) têm regras ou estruturas próprias, mas ainda precisam fazer parte de um contexto maior, representado pela classe pai.

Motivo para Fazer Isso

A abordagem de retornar à classe pai é necessária quando:

Modularidade: Partes do sistema, como itens, tributos ou pagamentos, possuem lógica própria e precisam ser organizadas em classes separadas para melhorar a coesão. Isso evita que a classe principal fique sobrecarregada com responsabilidades que poderiam ser delegadas.
Encadeamento Natural: Para que a API fluente seja contínua e legível, os métodos de uma classe subordinada (como AddItem) precisam retornar ao fluxo principal ao final de suas operações. O uso de um método como &End permite retornar à classe pai sem quebrar o padrão fluente.
Reuso de Componentes: Com componentes subordinados encapsulados em classes específicas (como TItens), é possível reutilizá-los em diferentes contextos, sem necessidade de replicar lógica na classe principal.
Hierarquia de Configuração: No exemplo de emissão de NF-e, as configurações possuem uma hierarquia natural: o cabeçalho pertence ao documento principal, enquanto os itens e seus detalhes pertencem a uma parte específica dessa estrutura. Essa hierarquia deve ser refletida no design das classes.

Vantagens do Retorno à Classe Pai

Legibilidade e Fluidez: O código gerado é mais próximo de uma linguagem natural. Desenvolvedores podem configurar diferentes partes do objeto sem perder o encadeamento ou criar blocos confusos.Exemplo:


NFe
  .Itens
    .AddItem('001', 3500.00, 1)
    .AddItem('002', 120.00, 2)
  .&End
  .GerarXML;

NFe

.Itens

.AddItem('001', 3500.00, 1)

.AddItem('002', 120.00, 2)

.&End

.GerarXML;

Esse fluxo é muito mais legível do que manter todas as configurações em uma única classe.

Encapsulamento: Cada componente, como TItens, gerencia seu próprio estado e lógica, sem expor detalhes à classe principal. Isso melhora o design orientado a objetos, facilitando a manutenção e extensão do código.

Organização Modular: Com as classes subordinadas, a lógica específica fica isolada. Por exemplo, a lógica para adicionar itens à nota fiscal está completamente encapsulada em TItens. A classe principal (TNFeBuilder) foca em tarefas de alto nível, como gerar o XML.

Extensibilidade: Esse design facilita a adição de novos componentes ou funcionalidades. Caso seja necessário adicionar tributos ou pagamentos à NF-e, bastaria criar novas classes subordinadas e vinculá-las ao fluxo principal.

Menor Acoplamento: A classe subordinada (TItens) mantém uma referência à classe pai, mas o oposto não é verdadeiro. Isso reduz o acoplamento e melhora a flexibilidade do código.

Melhoria de Testabilidade: Componentes encapsulados podem ser testados isoladamente. Por exemplo, a funcionalidade de adicionar itens e calcular o total pode ser testada diretamente em TItens, sem interferir na lógica da classe principal.

Resumo

O encadeamento avançado com retorno à classe pai não é apenas uma questão de melhorar a legibilidade. Ele reflete boas práticas de design orientado a objetos, dividindo responsabilidades, reduzindo o acoplamento e tornando o código mais modular e testável. Em sistemas complexos, essa abordagem oferece uma combinação poderosa de flexibilidade, clareza e escalabilidade, essencial para aplicações robustas e fáceis de manter.

Vamos a um exemplo prático:

1. Classe TItens para Gerenciar os Itens


type
  TNFeBuilder = class; // Declaração forward da classe pai

  TItens = class
  private
    FParent: TNFeBuilder; // Referência à classe pai
    FItens: TStringList;
  public
    constructor Create(AParent: TNFeBuilder);
    destructor Destroy; override;

    function AddItem(const AID: string; APreco: Currency; AQuantidade: Integer): TItens;
    function &End: TNFeBuilder; // Retorna à classe pai
  end;

type

TNFeBuilder = class; // Declaração forward da classe pai

TItens = class

private

FParent: TNFeBuilder; // Referência à classe pai

FItens: TStringList;

public

constructor Create(AParent: TNFeBuilder);

destructor Destroy; override;

function AddItem(const AID: string; APreco: Currency; AQuantidade: Integer): TItens;

function &End: TNFeBuilder; // Retorna à classe pai

end;

2. Classe TNFeBuilder para a NF-e


type
  TNFeBuilder = class
  private
    FEmitente: string;
    FCNPJ: string;
    FEndereco: string;
    FItens: TItens; // Instância de `TItens`
  public
    constructor Create;
    destructor Destroy; override;

    // Métodos fluentes para o cabeçalho
    function SetEmitente(const ARazaoSocial: string): TNFeBuilder;
    function SetCNPJ(const ACNPJ: string): TNFeBuilder;
    function SetEndereco(const AEndereco: string): TNFeBuilder;

    // Método fluente para acessar os itens
    function Itens: TItens;

    // Finaliza e gera o XML
    function GerarXML: string;
  end;

type

TNFeBuilder = class

private

FEmitente: string;

FCNPJ: string;

FEndereco: string;

FItens: TItens; // Instância de `TItens`

public

constructor Create;

destructor Destroy; override;

// Métodos fluentes para o cabeçalho

function SetEmitente(const ARazaoSocial: string): TNFeBuilder;

function SetCNPJ(const ACNPJ: string): TNFeBuilder;

function SetEndereco(const AEndereco: string): TNFeBuilder;

// Método fluente para acessar os itens

function Itens: TItens;

// Finaliza e gera o XML

function GerarXML: string;

end;

3. Implementação dos Métodos

Métodos da Classe TItens


constructor TItens.Create(AParent: TNFeBuilder);
begin
  FParent := AParent; // Armazena a referência à classe pai
  FItens := TStringList.Create;
end;

destructor TItens.Destroy;
begin
  FItens.Free;
  inherited;
end;

function TItens.AddItem(const AID: string; APreco: Currency; AQuantidade: Integer): TItens;
begin
  FItens.Add(Format('ID: %s | Preço: %.2f | Quantidade: %d', [AID, APreco, AQuantidade]));
  Result := Self; // Permite continuar adicionando itens
end;

function TItens.&End: TNFeBuilder;
begin
  Result := FParent; // Retorna à classe pai para continuar o encadeamento
end;

constructor TItens.Create(AParent: TNFeBuilder);

begin

FParent := AParent; // Armazena a referência à classe pai

FItens := TStringList.Create;

end;

destructor TItens.Destroy;

begin

FItens.Free;

inherited;

end;

function TItens.AddItem(const AID: string; APreco: Currency; AQuantidade: Integer): TItens;

begin

FItens.Add(Format('ID: %s | Preço: %.2f | Quantidade: %d', [AID, APreco, AQuantidade]));

Result := Self; // Permite continuar adicionando itens

end;

function TItens.&End: TNFeBuilder;

begin

Result := FParent; // Retorna à classe pai para continuar o encadeamento

end;

4. Exemplo de Uso


var
  NFe: TNFeBuilder;
  XML: string;
begin
  NFe := TNFeBuilder.Create;
  try
    XML := NFe
      .SetEmitente('Empresa ABC LTDA')
      .SetCNPJ('12.345.678/0001-99')
      .SetEndereco('Rua das Flores, 123')
      .Itens
        .AddItem('001', 3500.00, 1)
        .AddItem('002', 120.00, 2)
      .&End
      .GerarXML;

    Writeln(XML);
  finally
    NFe.Free;
  end;
end;

var

NFe: TNFeBuilder;

XML: string;

begin

NFe := TNFeBuilder.Create;

try

XML := NFe

.SetEmitente('Empresa ABC LTDA')

.SetCNPJ('12.345.678/0001-99')

.SetEndereco('Rua das Flores, 123')

.Itens

.AddItem('001', 3500.00, 1)

.AddItem('002', 120.00, 2)

.&End

.GerarXML;

Writeln(XML);

finally

NFe.Free;

end;

Saída do XML Gerado


<NFe>
  <Emitente>Empresa ABC LTDA</Emitente>
  <CNPJ>12.345.678/0001-99</CNPJ>
  <Endereco>Rua das Flores, 123</Endereco>
  <Itens>
    ID: 001 | Preço: 3500.00 | Quantidade: 1
    ID: 002 | Preço: 120.00 | Quantidade: 2
  </Itens>
</NFe>

<NFe>

<Emitente>Empresa ABC LTDA</Emitente>

<Endereco>Rua das Flores, 123</Endereco>

<Itens>

ID: 001 | Preço: 3500.00 | Quantidade: 1

ID: 002 | Preço: 120.00 | Quantidade: 2

</Itens>

</NFe>

Explicando o Funcionamento

Retorno à Classe Pai (&End):
A função &End da classe TItens retorna a instância da classe TNFeBuilder, armazenada em FParent. Isso permite continuar o encadeamento no objeto principal após configurar os itens.
Referência Cruzada:
A classe TItens conhece sua classe pai (TNFeBuilder), mas o oposto não ocorre diretamente. Isso garante encapsulamento, permitindo que TItens administre apenas os dados relacionados aos itens.
Legibilidade:
Esse modelo de encadeamento dentro de encadeamentos melhora a organização e torna o código mais expressivo e próximo da linguagem natural.

Participe da Comunidade no Telegram

🚀 Quer continuar essa discussão e trocar ideias com outros desenvolvedores? Junte-se à nossa comunidade no Telegram! Lá, você pode comentar sobre o que achou deste artigo, tirar suas dúvidas e compartilhar suas experiências com Delphi e ainda discutir ou tirar suas dúvidas sobre os mais variados temas em uma comunidade com mais de 1.000 desenvolvedores.

🔗 Clique aqui para entrar na comunidade

Te vejo lá!

Conclusão

O padrão Fluent Interface, combinado com o uso de Self, é uma ferramenta poderosa para criar APIs legíveis e práticas. No exemplo de emissão de NF-e, os métodos encadeados simplificam a configuração e emissão, proporcionando um fluxo natural. Ao dominar esse padrão, você melhora significativamente a qualidade e a clareza do código, beneficiando todo o ciclo de desenvolvimento.

2 thoughts on “Como criar métodos encadeados com Fluent Interface?”

Carlos H Oliveira disse:

25 de novembro de 2024 às 23:01

Gosto de utilizar esse padrão, nem sabia que tinha um nome. Muito bom artigo.

Responder
1. Adriano Santos disse:
  
  26 de novembro de 2024 às 07:06
  
  Obrigado, vamos juntos.
  
  Responder

Como criar métodos encadeados com Fluent Interface?

Explicando o Código: Conceitos Aplicados

Exemplo prático:

Exemplo:

Exemplo:

Comparação:

Motivo para Fazer Isso

Vantagens do Retorno à Classe Pai

Resumo

Explicando o Funcionamento

Participe da Comunidade no Telegram

Conclusão

2 thoughts on “Como criar métodos encadeados com Fluent Interface?”

Deixe um comentário para Carlos H Oliveira Cancelar resposta

Posts Relacionados

Migração Eduzz para HotmartMigração Eduzz para Hotmart

Evento realizado com sucesso! Veja como foi.Evento realizado com sucesso! Veja como foi.

Entendendo Generics no DelphiEntendendo Generics no Delphi