Nesse segundo post do nosso blog, vamos aprender a criar nosso primeiro servidor Horse e responder aos primeiros requests. Você irá entender como é fácil iniciar um projeto de servidor e desenvolver sua primeira API de serviços utilizando o HORSE.

Por onde começar?

Nós já vimos aqui como é fácil instalar e configurar o Boss no Windows e a partir daí gerenciar nossos sistemas. É através dele que faremos a instalação do Horse dentro do nosso projeto e iniciar a criação de um servidor de aplicações e/ou API de serviços.

Se você não leu a Parte 1 dessa Série, LEIA AGORA.

O Horse tem como principal objetivo ser simples e fácil de utilizar. Ele é desenvolvido com boas práticas, orientação a objetos e padrões de projeto, tornando-o mais eficiente. Outro ponto importante é que ele é totalmente FREE e mantido pela equipe HashLoad. É fechado para implementações e aberto para extensões, o que significa que a comunidade pode criar middlewares para Horse aumentando o número de recursos e facilidades.

Os middleware são como como extensões que podem ser adicionados ao servidor Horse, como o tratamento de exceções, leitura e geração de JSON, paginação, basic authentication, JWT, entre outras opções.

É altamente recomendado que leia as documentações presentes em cada middleware, pois os detalhes o ajudarão bastante na criação de projetos no futuro.

O Horse

Todo o projeto está disponível no GitHub do Horse aqui. Acessando o GitHub você encontrará o guia de instalação, dicas e os middlwares já disponíveis para ele. Eles são divididos em dois grupos. Os middlewares oficiais (Official Middlewares) e os de terceiros, desenvolvidos pela comunidade (Third Party Middlewares).

Como podemos perceber, a lista é grade e dependendo de quando está lendo esse artigo, ela pode estar ainda maior nos dias atuais. Eu mencionei acima que os middlewares são como extensões e é isso mesmo. Cada middleware implementa uma funcionalidade nova ao Horse. Vejamos alguns deles:

JSON (Jhonson)

O middleware Jhonson é utilizado para que possamos trabalhar com JSON em nossos servidores. Então se você precisa devolver um JSON com alguma informação para o cliente que irá consumir seu serviço Web, use o Jhonson pra isso. Um exemplo disso é quando precisamos fazer uma listagem simples de uma determinada tabela, CLIENTES por exemplo ou mesmo devolver um JSON criado por vocês, e precisamos prover esses dados.

https://github.com/HashLoad/jhonson

O uso desse middleware é bastante simples veja:

uses Horse, Horse.Jhonson, System.JSON;

begin
  THorse.Use(Jhonson());

  THorse.Post('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    var
      LBody: TJSONObject;
    begin
      LBody := Req.Body<TJSONObject>;
      Res.Send<TJSONObject>(LBody);
    end);

  THorse.Listen(9000);
end;

Primeiro devemos instalar o middleware em nosso projeto, mas calma, já vamos ver isso. Quero que entenda o código acima. Perceba que fizemos um “Uses” da unit Horse.Jhonson e em seguida usando trecho THorse.Use(Jhonson); Pronto, a partir desse momento já estamos prontos para trafegar informações em formato JSON, detalhe: a Aplicação Servidora Inteira.

No exemplo acima disponibilizado pela própria equipe que desenvolveu o middleware, podemos notar que estamos devolvendo para a aplicação cliente um JSON usando a linha Res.Send<TJSONObject>(LBody);

Por isso é tão importante ler a documentação, pois exemplos como esse ajudarão bastante na hora de utilizar o recurso desejado.

Compression

Esse recurso é importante para comprimir os dados que serão trafegados entre servidor Horse e aplicação requisitante, o cliente. A taxa de compressão é bastante elevada e a minha recomendação é que esse middleware passe a ser obrigatório em seus servidores, seu usuário certamente gostará muito disso. 😉

Veja na tabela abaixo o comparativo:

https://github.com/HashLoad/horse-compression

O uso desse middleware é bastante simples veja:

uses Horse, Horse.Jhonson, Horse.Compression, System.JSON;

begin
  THorse
    .Use(Compression()) // Must come before Jhonson middleware
    .Use(Jhonson());

  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    var
      I: Integer;
      LPong: TJSONArray;
    begin
      LPong := TJSONArray.Create;
      for I := 0 to 1000 do
        LPong.Add(TJSONObject.Create(TJSONPair.Create('ping', 'pong')));
      Res.Send(LPong);
    end);

  THorse.Listen(9000);
end.

Perceba mais uma vez como é simples o seu uso. Em primeiro lugar fazemos o “Uses” da unit Horse.Compression e então adicionamos ele ao nosso servidor Horse utilizando o comando THorse.Use(Compression()); A partir desse momento todos os dados trafegados em nosso servidor serão comprimidos.

Observação: Quando usado o middleware Compression ele precisa necessariamente ser adicionado antes dos demais middlewares, nesse caso antes do Jhonson.

  THorse
    .Use(Compression()) // Must come before Jhonson middleware
    .Use(Jhonson());

É só seguir a documentação de cada middleware, sem erro.

Criando o primeiro servidor

Caso não tenha entendido exatamente a seção anterior, não se preocupe, pois é agora que tudo fará sentido e será mais fácil o entendimento. Na primeira etapa entendemos como funcionam os middlewares no Horse, um das disciplinas, no meu ponto de ver, mais importantes do uso da ferramenta, além é claro, da ferramenta em si. Muito bem. Vamos iniciar o entendimento do Horse propriamente dito agora.

O passo número um na criação de um server é sabermos que vamos utilizar como ponto de partida um projeto do tipo Console no Delphi. Se você não está familiarizado com o modo Console, não se preocupe também, pois a medida que vamos avançando essa barreira vai ficando para trás.

O modo console, caso seja novo no desenvolvimento, é um software que roda em modo terminal no Windows e Linux, ou seja, não possui interface gráfica. É a partir de um projeto console que instalamos e iniciamos a construção do nosso servidor Horse.

Por isso, nossa primeira providência é a criação de um novo projeto no Delphi. Então vamos seguir clicando em File > New > Console Application – Delphi. Um novo projeto será criado com apenas o “source” (DPR) do software que vamos desenvolver. Salve em uma pasta de sua preferência. No nosso tutorial vamos utilizar a pasta D:\Temp\MeuPrimeiroServidor. Eu dei o nome de ServerHorse.dproj ao nosso servidor. Se você executar esse software ele irá abrir e fechar no Windows, não se preocupe. É assim mesmo. Mas se quiser testar, altere o código como abaixo e execute.

program ServerHorse;

{$APPTYPE CONSOLE}

{$R *.res}

uses
  System.SysUtils;

begin
  try
    { TODO -oUser -cConsole Main : Insert code here }
    WriteLn('Meu primeiro projeto Horse');
    ReadLn;
  except
    on E: Exception do
      Writeln(E.ClassName, ': ', E.Message);
  end;
end.

O resultado será algo como a imagem abaixo:

Instalando o Horse

O Horse é instalado no projeto através de linha de comando, logo você precisará abrir uma seção do prompt do DOS, Terminal, Fluent, Git Bash, PowerShell, enfim, o terminal que está mais familiarizado. No post anterior eu indiquei o Fluent Terminal que é bem legal em termos visuais, talvez um pouco lento, mas bem interessante. Se preferir, uma boa dica é o Windows Terminal, também disponível na Windows Store. O legal dele é que podemos abrir várias abas na mesma janela, fica a seu critério.

Estando no terminal, navegue até a pasta onde nosso projeto está localizado. Lembre-se, salvei o meu projeto em D:\Temp\MeuPrimeiroServidor. Não vou entrar em detalhes de como entrar na pasta através do terminal, portanto se não está familiarizado, procure ajuda.

Dentro da pasta do nosso projeto vamos executar alguns comandos para inicializar o Boss e em seguida instalar o Horse em nosso projeto. A inicialização é como vimos no artigo anterior, ou seja, usando o comando init do Boss. Portanto, execute o comando abaixo:

boss init

Pronto, Boss inicializado.

Agora execute o comando de instalação do Horse:

boss i Horse

Perfeito. Retorne para o Delphi agora e veja que ele está nos avisando que alguma modificação foi feita no projeto e precisa recarregar. Apenas clique em Yes to All. A partir desse momento temos nosso projeto já com o Horse instalado nele e podemos iniciar a programação da nossa API.

Executando o servidor Horse

Ainda não estamos respondendo aos requets em nosso serviço, para isso precisamos construir nossos endpoints, implementar os verbos HTTP e então executar nosso server. Caso não esteja familiarizado com esses termos, com o protocolo HTTP ou quaisquer outras informações presentes nesse artigo, recomendo fortemente que assista minha Playlist no YouTube falando especificamente sobre o assunto.

Inicie alterando o “Uses” do projeto importando a unit Horse para que possamos começar a fazer uso do framework em nosso servidor. Uma boa dica é seguir, sempre, a documentação. Veja como implementar o verbo Get e uma rota /ping rapidamente.

uses Horse;

begin
  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('pong');
    end);

  THorse.Listen(9000);
end.

Esse trecho de código está disponível na documentação do Horse. Perceba, estamos adicionando a unit referente ao frameworks no “Uses” e logo abaixo do “begin” iniciamos o método Get usando THorse.Get.

O método requer dois parâmetros. O primeiro é a rota, o endpoint. Usamos ‘/ping’, isso significa que sempre que fizemos uma requisição a essa rota, o Horse irá nos responder. O segundo parâmetro é um procedimento anônimo. Nesse método temos três parâmetros, que são eles:

• Req do tipo THorseRequest, onde receberemos todos os requests.
• Res do tipo THorseResponse, onde enviaremos de volta ao cliente as respostas da API
• Next do tipo TProc, que não entraremos em detalhes aqui. Esse parâmetro é utilizado quando queremos chamar um outro método dentro do servidor, comumente usado na construção de middlewares. Vamos deixar pra mais tarde.

Seguindo a mesma padronização, ao pressionar Ctrl + Barra de Espaço em THorse, verá que podemos facilmente implementar os verbos Post, Put, Delete e Patch. Fácil não?

Pois bem. Todas as nossas requisições serão recebidas em Req, logo todas as nossas respostas serão dadas em Res. No exemplo acima, estamos recebendo o request em ‘/ping’ e respondendo com a palavra ‘pong’ na resposta.

A última linha desse trecho de código é a chamada ao método Listen, que fará com que nosso servidor Horse seja inicializado na porta informada (default 9000) e passe a receber os requests e funcionar de verdade.

THorse.Listen(9000);

Experimente executar com F9 esse projeto e através de uma instância do seu browser digitar:

http://localhost:9000/ping

Perceba o quão fácil é criar nosso primeiro servidor. Ele já responde ao nosso request.

Experimente agora implementar os demais verbos HTTP no servidor, segue a sintaxe e o código exemplo:

begin
  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('GET pong');
    end);

  THorse.Post('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('POST pong');
    end);

  THorse.Put('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('PUT pong');
    end);

  THorse.Delete('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('DELETE pong');
    end);

  THorse.Listen(9000);
end.

Desta vez para testar utilize o Insomnia ou o Postman que são clients para testar APIs REST. são excelentes softwares. Baixe-os e instale em seu Windows. Em qualquer um dos dois aplicativos, digite a url, selecione o verbo à esquerda e pressione sobre Send.

Em todos os requests tanto em uma ferramenta quanto na outra, você receberá a resposta que programamos no parâmetro Res.

Instalando Middlewares no Horse

A base para construção de servidores utilizando esse framework é essa, agora vamos aprender a usar outros recursos em nosso server para fecharmos o artigo com chave de outro. Assim como dito anteriormente, podemos facilmente incrementar nossa API usando middlewares que adicionarão mais recursos ao projeto. A instalação de middlwares é extremamente simples.

Retorne ao terminal que usou anteriormente e rode o comando referente a instalação do middleware que deseja, é simples. A sintaxe padrão é:

boss i |NOME_DO_MIDDLEWARE
ou
boss i |CAMINHO_DO_MIDDLEWARE

Talvez tenha ficado confuso, mas é bem simples. Se o middleware for um dos oficiais, ou seja, criados pela própria equipe HashLoad, basta o nome dele e o boss fará a instalação. Se for um middleware de terceiro, digite o caminho completo após o comando de instalação. Experimente instalar o Middleware Jhonson com o comando:

boss i jhonson

E vamos ver como instalar um middleware de terceiro, o paginate do Thulio Bittencourt. Não é necessário digitar ‘https://’.

boss i github.com/bittencourtthulio/Horse-Paginate

Isso já será suficiente para trabalharmos. Não vou entrar em detalhes do uso do paginate, quero apenas que saiba como instalar middlewares de oficiais e de terceiro.

Pronto, agora basta fazer uso do que instalou e isso é fácil. Em “uses” importe a unit da extensão instalada conforme a documentação do desenvolvedor e então faça uso dela adicionando o .Use com o nome do middleware. Exemplo:

uses
  Horse,
  Horse.Jhonson,
  Horse.eTag,
  Horse.Compression,
  Horse.Paginate,
  System.SysUtils,
  System.JSON;

begin
  THorse
    .Use(Compression())
    .Use(Jhonson)
    .Use(Paginate)
    .Use(eTag);

Tranquilo, não?

Conclusão

Com toda a base aprendida nesse artigo podemos facilmente criar serviços HTTP de qualidade, leves e fáceis de implementar novas funcionalidades. O Horse tem ganho bastante espaço na comunidade por conta de sua simplicidade de uso. A adoção dele em seus projetos pode acrescentar mais poder de processamento, maior facilidade na manutenção de seus sistemas multi-camadas, performance e sem dúvida alguma, mais profissionalismo.

E se você quiser se aprofundar no assunto, com vídeos detalhados e informações mais passo a passo de como fazer na prática, pode adquirir o meu treinamento específico neste link abaixo, com 30% de desconto exclusivo.

Muito obrigado, bons estudos e até a próxima.

Quer aprender a criar aplicativos mobile com Delphi, Boss e Horse?

Somente nesse link você tem 30% de desconto na aquisição do nosso treinamento:

Mobile com BackEnd Horse

de R$ 597,00
por

12x R$ 41,79

ou R$ 417,90 à vista