O RestClient é uma biblioteca cliente REST e HTTP baseada em Promises, projetada especificamente para simplificar o manejo de requisições de rede em projetos Unity. Ele oferece uma interface intuitiva e funcionalidades robustas, facilitando a interação com serviços web e APIs externas durante o desenvolvimento de jogos.

Estrutura Arquitetural do RestClient

O código fonte do RestClient adota uma abordagem modular, com componentes bem definidos para gerenciar o ciclo de vida das requisições HTTP. Essa organização garante manutenibilidade e extensibilidade.

Componentes Chave

• RestClient: O ponto de entrada principal para todas as operações HTTP.
• RequestConfiguration: Responsável por encapsular e gerenciar os parâmetros da requisição.
• ResponseParser: Lida com a decodificação e transformação dos dados recebidos do servidor.
• HttpEngine: Abstrai as operações de baixo nível utilizando oUnityWebRequest.

Detalhes da Classe RestClient

A classeRestClient, localizada em src/Proyecto26.RestClient/RestClient.cs, é a espinha dorsal da biblioteca. Como uma classe estática, ela expõe métodos utilitários para a execução de diversas operações HTTP.

Funcionalidades Principais

1. Gerenciamento de Versão: Fornece a versão atual da biblioteca através da propriedadeVersion.
2. Configurações Globais: Permite definir parâmetros e cabeçalhos padrão para todas as requisições.
3. Métodos HTTP: Implementa as operações comuns comoGET,POST,PUT,PATCHeDELETE.

public static partial class RestClient
{
   private static System.Version _libraryVersion;
   public static System.Version LibraryVersion { get; }

   private static Dictionary<string string=""> _globalParameters;
   public static Dictionary<string string=""> GlobalParameters { get; set; }

   private static Dictionary<string string=""> _globalHeaders;
   public static Dictionary<string string=""> GlobalHeaders { get; set; }

   public static void Retrieve(string endpoint, Action<requestfailure responsedetails=""> completionHandler) { /* ... */ }
   public static void Submit(string endpoint, object payload, Action<requestfailure responsedetails=""> completionHandler) { /* ... */ }
   // Outros métodos HTTP...
}
   </requestfailure></requestfailure></string></string></string></string>

Implementação de Métodos HTTP

Cada método HTTP possui várias sobrecargas para acomodar diferentes cenários. Por exemplo, o métodoRetrieve(equivalente a GET) oferece:

// Requisição GET básica
public static void Retrieve(string url, Action<requestfailure responsedetails=""> callback)
{
   Retrieve(new RequestConfiguration { TargetUrl = url }, callback);
}

// Requisição GET com tipo de retorno esperado
public static void Retrieve<t>(string url, Action<requestfailure responsedetails="" t=""> callback)
{
   Retrieve<t>(new RequestConfiguration { TargetUrl = url }, callback);
}

// Requisição GET para retornar um array de um tipo específico
public static void RetrieveArray<t>(string url, Action<requestfailure responsedetails="" t=""> callback)
{
   RetrieveArray<t>(new RequestConfiguration { TargetUrl = url }, callback);
}
   </t></requestfailure></t></t></requestfailure></t></requestfailure>

Essas chamadas delegam a execução para o métodoExecuteRequest, que utiliza oHttpEngine:

public static void ExecuteRequest(RequestConfiguration config, Action<requestfailure responsedetails=""> callback)
{
   StaticCoroutineRunner.StartCoroutine(HttpEngine.ProcessRequest(config, callback));
}
   </requestfailure>

RequestConfiguration: O Centro de Controle da Requisição

Definida em src/Proyecto26.RestClient/Helpers/RequestConfiguration.cs, a classeRequestConfiguration gerencia todos os aspectos de uma requisição HTTP, abstraindo a complexidade doUnityWebRequest.

Propriedades e Funcionalidades

public partial class RequestConfiguration
{
   // URL de destino da requisição
   public string TargetUrl { get; set; }

   // Método HTTP (GET, POST, etc.)
   public string HttpMethod { get; set; }

   // Corpo da requisição (suporta objetos, strings e bytes)
   public object Payload { get; set; }
   public string PayloadString { get; set; }
   public byte[] PayloadRaw { get; set; }

   // Configuração de timeout
   public int? TimeoutDuration { get; set; }

   // Tipo de conteúdo
   public string ContentType { get; set; }

   // Configurações de retentativa
   public int MaxRetries { get; set; }
   public float RetryDelaySeconds { get; set; }

   // Outras opções de configuração...
}
   

Processo de Construção da Requisição

RequestConfiguration não apenas armazena os parâmetros, mas também orquestra a conversão desses parâmetros em um formato utilizável peloUnityWebRequest, cuidando da combinação de URL e parâmetros de query, configuração de cabeçalhos, serialização do corpo e tratamento de dados de formulário.

Mecanismo de Processamento Assíncrono

Uma característica marcante do RestClient é seu eficiente sistema de processamento assíncrono, que combina o sistema de Coroutines do Unity com o padrão Promise para uma experiência de programação assíncrona fluida.

Coroutines e UnityWebRequest

O RestClient utilizaStaticCoroutineRunner.StartCoroutine para iniciar as Coroutines que gerenciam as requisições HTTP:

public static void ExecuteRequest(RequestConfiguration config, Action<requestfailure responsedetails=""> callback)
{
   StaticCoroutineRunner.StartCoroutine(HttpEngine.ProcessRequest(config, callback));
}
   </requestfailure>

O métodoHttpEngine.ProcessRequest encapsula todo o ciclo de vida doUnityWebRequest, desde a criação e envio até o recebimento e processamento da resposta.

Suporte a Promises

Além do modelo baseado em callbacks, o RestClient oferece uma API baseada em Promises (emRestClientPromise.cs), que ajuda a evitar o aninhamento excessivo de callbacks (callback hell) e torna o código assíncrono mais legível:

public static IPromise<responsedetails> Retrieve(string url)
{
   return Retrieve(new RequestConfiguration { TargetUrl = url });
}

public static IPromise<responsedetails> Retrieve(RequestConfiguration options)
{
   var promise = new Promise<responsedetails>();
   ExecuteRequest(options, (failure, response) => {
       if (failure != null) promise.Reject(failure);
       else promise.Resolve(response);
   });
   return promise;
}
   </responsedetails></responsedetails></responsedetails>

Tratamento de Erros e Retentativas

O RestClient implementa um sistema robusto para tratamento de erros e mecanismos de retentativa, garantindo a confiabilidade das operações de rede.

Fluxo de Tratamento de Erros

Quando uma requisição falha, o erro é encapsulado em um objetoRequestFailure e repassado através do callback ou do métodoReject da Promise. As falhas podem incluir erros de rede, códigos de status HTTP enesperados ou timeouts.

Mecanismo Inteligente de Retentativas

A classeRequestConfiguration oferece opções configuráveis para retentativas:

// Número máximo de retentativas
public int MaxRetries { get; set; }

// Atraso entre as retentativas (em segundos)
public float RetryDelaySeconds { get; set; }

// Callback executado antes de cada retentativa
public Action<requestfailure int=""> PreRetryCallback { get; set; }

// Condição para retentar apenas em erros de rede
public bool RetryOnlyOnNetworkErrors { get; set; }
   </requestfailure>

Essas configurações permitem aos desenvolvedores adaptar a estratégia de retentativa às necessidades específicas de cada requisição, aumentando a taxa de sucesso.

Exemplo de Uso Prático

Um exemplo simples de requisiçãoGET demonstra a simplicidade de uso do RestClient:

// Usando callbacks
RestClient.Retrieve("https://api.example.com/items", (failure, response) => {
   if (failure != null) {
       Debug.LogError($"Falha na requisição: {failure.Message}");
       return;
   }
   Debug.Log($"Resposta: {response.BodyText}");
});

// Usando Promises
RestClient.Retrieve("https://api.example.com/items")
   .Then(response => Debug.Log($"Resposta: {response.BodyText}"))
   .Catch(failure => Debug.LogError($"Falha na requisição: {failure.Message}"));
   

Conclusão

O RestClient oferece uma solução podreosa e fácil de usar para clientes HTTP no Unity. Seus pontos fortes incluem:

• API Clara: Métodos HTTP intuitivos que simplificam o desenvolvimento.
• Configuração Flexível:RequestConfiguration permite personalização detalhada das requisições.
• Processamento Assíncrono: Combinação de Coroutines e Promises para uma experiência moderna.
• Tratamento de Erros Robusto: Mecanismos de erro e retentativa aprimorados.
• Otimização para Unity: Projetado para performance e estabilidade no ambiente Unity.

A compreensão do código fonte do RestClient não só aprimora seu uso, mas também oferece insights valiosos sobre as melhores práticas de programação de rede no Unity.