{"id":920,"date":"2024-11-21T09:58:18","date_gmt":"2024-11-21T12:58:18","guid":{"rendered":"https:\/\/adrianosantostreina.com.br\/blog\/?p=920"},"modified":"2024-12-13T14:34:33","modified_gmt":"2024-12-13T17:34:33","slug":"como-criar-metodos-encadeados-com-fluent-interface","status":"publish","type":"post","link":"https:\/\/adrianosantostreina.com.br\/blog\/como-criar-metodos-encadeados-com-fluent-interface\/","title":{"rendered":"Como criar m\u00e9todos encadeados com Fluent Interface?"},"content":{"rendered":"\n

A Fluent Interface<\/strong> \u00e9 um padr\u00e3o de design que permite encadear m\u00e9todos para criar um c\u00f3digo mais leg\u00edvel, parecido com uma linguagem natural. Esse padr\u00e3o \u00e9 particularmente \u00fatil em cen\u00e1rios complexos, como o de configura\u00e7\u00e3o e emiss\u00e3o de documentos fiscais, onde diversos par\u00e2metros precisam ser definidos antes de uma a\u00e7\u00e3o ser executada.<\/p>\n\n\n\n\n\n\n\n

Neste artigo, exploraremos como implementar esse padr\u00e3o em Delphi, aplicando-o a um caso real: a emiss\u00e3o de uma Nota Fiscal Eletr\u00f4nica (NF-e). A implementa\u00e7\u00e3o demonstrar\u00e1 como utilizar m\u00e9todos fluentes para configurar dados obrigat\u00f3rios, como emitente, destinat\u00e1rio e itens da nota, finalizando com a valida\u00e7\u00e3o e gera\u00e7\u00e3o da NF-e.<\/p>\n\n\n\n

Implementa\u00e7\u00e3o de Fluent Interface para NF-e<\/strong><\/p>\n\n\n\n

Vamos imaginar um cen\u00e1rio de emiss\u00e3o de uma NF-e, onde precisamos configurar diferentes aspectos: emitente, destinat\u00e1rio, itens e tributos. Abaixo est\u00e1 a implementa\u00e7\u00e3o com m\u00e9todos fluentes.<\/p>\n\n\n\n

A Classe Principal TNFeBuilder<\/code><\/p>\n\n\n\n

type\n  TNFeBuilder = class\n  private\n    FEmitente: string;\n    FDestinatario: string;\n    FItens: TStringList;\n    FTotal: Currency;\n  public\n    constructor Create;\n    destructor Destroy; override;\n    function SetEmitente(const AEmitente: string): TNFeBuilder;\n    function SetDestinatario(const ADestinatario: string): TNFeBuilder;\n    function AddItem(const ADescricao: string; AQuantidade: Integer; AValorUnitario: Currency): TNFeBuilder;\n    function CalcularTotal: TNFeBuilder;\n    function GerarXML: string;\n  end;\n\nimplementation\n\nconstructor TNFeBuilder.Create;\nbegin\n  FItens := TStringList.Create;\n  FTotal := 0.0;\nend;\n\ndestructor TNFeBuilder.Destroy;\nbegin\n  FItens.Free;\n  inherited;\nend;\n\nfunction TNFeBuilder.SetEmitente(const AEmitente: string): TNFeBuilder;\nbegin\n  FEmitente := AEmitente;\n  Result := Self;\nend;\n\nfunction TNFeBuilder.SetDestinatario(const ADestinatario: string): TNFeBuilder;\nbegin\n  FDestinatario := ADestinatario;\n  Result := Self;\nend;\n\nfunction TNFeBuilder.AddItem(const ADescricao: string; AQuantidade: Integer; AValorUnitario: Currency): TNFeBuilder;\nbegin\n  FItens.Add(Format('%s | Qtd: %d | Unit: %.2f', [ADescricao, AQuantidade, AValorUnitario]));\n  FTotal := FTotal + (AQuantidade * AValorUnitario);\n  Result := Self;\nend;\n\nfunction TNFeBuilder.CalcularTotal: TNFeBuilder;\nbegin\n  \/\/ Aqui podem ser aplicados c\u00e1lculos de impostos ou descontos\n  Result := Self;\nend;\n\nfunction TNFeBuilder.GerarXML: string;\nbegin\n  Result := Format(\n    '<NFe><Emitente>%s<\/Emitente><Destinatario>%s<\/Destinatario><Itens>%s<\/Itens><Total>%.2f<\/Total><\/NFe>',\n    [FEmitente, FDestinatario, FItens.Text, FTotal]\n  );\nend;\n<\/pre><\/div>\n\n\n\n
Exemplo de Uso:<\/p>\n\n\n\n
var\n  NFe: TNFeBuilder;\n  XML: string;\nbegin\n  NFe := TNFeBuilder.Create;\n  try\n    XML := NFe.SetEmitente('Empresa ABC LTDA')\n              .SetDestinatario('Jo\u00e3o da Silva')\n              .AddItem('Notebook', 1, 3500.00)\n              .AddItem('Mouse', 2, 120.00)\n              .CalcularTotal\n              .GerarXML;\n\n    Writeln(XML);\n  finally\n    NFe.Free;\n  end;\nend;\n<\/pre><\/div>\n\n\n\n
Sa\u00edda do XML Gerado<\/p>\n\n\n\n
<NFe>\n  <Emitente>Empresa ABC LTDA<\/Emitente>\n  <Destinatario>Jo\u00e3o da Silva<\/Destinatario>\n  <Itens>\n    Notebook | Qtd: 1 | Unit: 3500.00\n    Mouse | Qtd: 2 | Unit: 120.00\n  <\/Itens>\n  <Total>3740.00<\/Total>\n<\/NFe>\n<\/pre><\/div>\n\n\n\n
Explicando o C\u00f3digo: Conceitos Aplicados<\/strong><\/h3>\n\n\n\n
O padr\u00e3o Fluent Interface<\/strong> utiliza uma t\u00e9cnica simples, por\u00e9m poderosa, para possibilitar o encadeamento de m\u00e9todos: retornar a pr\u00f3pria inst\u00e2ncia da classe (Self<\/code>). Isso permite que cada m\u00e9todo execute sua opera\u00e7\u00e3o e, ao mesmo tempo, devolva o controle ao objeto que iniciou a sequ\u00eancia. Aqui est\u00e3o os principais conceitos aplicados no c\u00f3digo:<\/p>\n\n\n\n
    \n
  1. O Uso de Self<\/code> para Encadeamento<\/strong><\/li>\n<\/ol>\n\n\n\n
    No c\u00f3digo, cada m\u00e9todo que modifica ou configura a classe termina com a seguinte linha:<\/p>\n\n\n\n
    Result := Self;\n<\/pre><\/div>\n\n\n\n
    O Self<\/code> \u00e9 uma refer\u00eancia para a pr\u00f3pria inst\u00e2ncia do objeto que est\u00e1 executando o m\u00e9todo. Quando o m\u00e9todo retorna essa inst\u00e2ncia, \u00e9 poss\u00edvel continuar chamando outros m\u00e9todos sem sair do contexto do objeto. Isso cria o efeito de “fluidez” que caracteriza o padr\u00e3o Fluent Interface.<\/p>\n\n\n\n
    Exemplo pr\u00e1tico:<\/h5>\n\n\n\n
    No m\u00e9todo SetEmitente<\/code>, configuramos o emitente e retornamos a inst\u00e2ncia:<\/p>\n\n\n\n
    function TNFeBuilder.SetEmitente(const AEmitente: string): TNFeBuilder;\nbegin\n  FEmitente := AEmitente; \/\/ Configura o emitente\n  Result := Self;         \/\/ Retorna a pr\u00f3pria inst\u00e2ncia\nend;\n<\/pre><\/div>\n\n\n\n
    Ao encadear chamadas, como em:<\/p>\n\n\n\n
    NFe.SetEmitente('Empresa ABC LTDA')\n   .SetDestinatario('Jo\u00e3o da Silva');\n<\/pre><\/div>\n\n\n\n
    2. Manuten\u00e7\u00e3o do Estado Interno do Objeto<\/strong><\/p>\n\n\n\n
    Cada m\u00e9todo modifica o estado interno do objeto (TNFeBuilder<\/code>), atualizando os atributos privados. Isso assegura que os dados sejam acumulados \u00e0 medida que os m\u00e9todos s\u00e3o encadeados.<\/p>\n\n\n\n
    Exemplo:<\/h5>\n\n\n\n
    O m\u00e9todo AddItem<\/code> adiciona um item \u00e0 lista interna e recalcula o total:<\/p>\n\n\n\n
    function TNFeBuilder.AddItem(const ADescricao: string; AQuantidade: Integer; AValorUnitario: Currency): TNFeBuilder;\nbegin\n  FItens.Add(Format('%s | Qtd: %d | Unit: %.2f', [ADescricao, AQuantidade, AValorUnitario]));\n  FTotal := FTotal + (AQuantidade * AValorUnitario);\n  Result := Self;\nend;\n<\/pre><\/div>\n\n\n\n
    Ao encadear m\u00faltiplos itens:<\/p>\n\n\n\n
    NFe.AddItem('Notebook', 1, 3500.00)\n   .AddItem('Mouse', 2, 120.00);\n<\/pre><\/div>\n\n\n\n
    Os itens s\u00e3o adicionados \u00e0 lista interna FItens<\/code>, e o total \u00e9 atualizado ap\u00f3s cada adi\u00e7\u00e3o.<\/p>\n\n\n\n
    3. Retorno Diferente no \u00daltimo M\u00e9todo<\/strong><\/p>\n\n\n\n
    O \u00faltimo m\u00e9todo no encadeamento (GerarXML<\/code>) n\u00e3o retorna a inst\u00e2ncia 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\u00e3o fluente.<\/p>\n\n\n\n
    Exemplo:<\/h5>\n\n\n\n
    function TNFeBuilder.GerarXML: string;\nbegin\n  Result := Format(\n    '<NFe><Emitente>%s<\/Emitente><Destinatario>%s<\/Destinatario><Itens>%s<\/Itens><Total>%.2f<\/Total><\/NFe>',\n    [FEmitente, FDestinatario, FItens.Text, FTotal]\n  );\nend;\n<\/pre><\/div>\n\n\n\n
    Essa distin\u00e7\u00e3o garante que, enquanto os m\u00e9todos de configura\u00e7\u00e3o e processamento retornam a inst\u00e2ncia para continuar o encadeamento, o m\u00e9todo final entrega o resultado da opera\u00e7\u00e3o.<\/p>\n\n\n\n
    4. Vantagens do Fluent Interface<\/strong><\/p>\n\n\n\n