RestClient.Net 5

 

RestClient.Net упрощает HTTP-вызовы в .NET. Отправьте тело запроса как строго типизированный объект и получите обратно строго типизированный объект. Вы можете внедрить абстракцию в свои классы обслуживания и быстро имитировать их, не беспокоясь о подключении HTTP или преобразовании в JSON. RestClient.Net 5 — это значительно улучшенная, закаленная в боях версия, основанная на подходе V4, в которой представлены неизменяемые типы и свободный API. Он снижает вероятность ошибо, он прекрасно работает с внедрением зависимостей, интегрируется с Polly, а дизайн должен быть знаком и удобен программистам на F #.

Зачем использовать Rest Client?

Классы HttpClient и System.Uri представляют собой беспорядок, и тем не менее мы видим, что они используются во всей кодовой базе. Вам не следует использовать HttpClient напрямую, и вам, конечно, не следует создавать новый HttpClient в вашем коде, потому что это делает невозможным модульное тестирование вашего кода. Используйте надежный клиент Rest, который поднимает вас на один уровень абстракции и устраняет неприятные грани с HttpClient.

Возможность тестирования модулей

Прежде всего, HttpClient не имеет простой абстракции. Если вы хотите имитировать HttpClient для модульного тестирования, вам необходимо внедрить DelegatingHandler в клиент. Даже в этом случае вам нужно смоделировать преобразование в необработанные данные и обратно. Это отвлекает от простого действия по проверке того, что клиент отправляет и получает правильный объект. RestClient.Net решает эту проблему с помощью интерфейса IClient. Вы отправляете строго типизированный объект в теле ответа и получаете строго типизированный объект в теле ответа. Это несложно смоделировать, и вы можете смоделировать это в одной строке.

/// <summary>
/// Dependency Injection abstraction for Rest Clients. Use the CreateClient delegate to create an IClient when more than one is needed for an application.
/// </summary>
public interface IClient
{
    /// <summary>
    /// Sends a strongly typed request to the server and waits for a strongly typed response
    /// </summary>
    /// <typeparam name="TResponseBody">The expected type of the response body</typeparam>
    /// <param name="request">The request that will be translated to a HTTP request</param>
    /// <returns>The response as the strong type specified by TResponseBody /></returns>
    /// <typeparam name="TRequestBody"></typeparam>
    Task<Response<TResponseBody>> SendAsync<TResponseBody, TRequestBody>(IRequest<TRequestBody> request);

    /// <summary>
    /// Default headers to be sent with HTTP requests
    /// </summary>
    IHeadersCollection DefaultRequestHeaders { get; }

    /// <summary>
    /// Base Url for the client. Any resources specified on requests will be relative to this.
    /// </summary>
    AbsoluteUrl BaseUrl { get; }
}

Внедрение зависимости

Твердая абстракция также означает простоту внедрения зависимостей. Вы можете напрямую внедрить интерфейс IClient или использовать фабричный подход с CreateClient. Это означает, что вам не нужно использовать реализацию IClient по умолчанию. При необходимости вы можете написать собственную реализацию IClient. Пакет RestClient.Net.DependencyInjection работает с внедрением зависимостей ASP.NET Core и использует реализацию IHttpClientFactory по умолчанию для создания HttpClient. Это означает, что RestClient.Net всегда получает HttpClient через фабрику, которую поддерживает Microsoft.

var serviceCollection = new ServiceCollection()
    //Add a service which has an IClient dependency
    .AddSingleton<IGetString, GetString1>()
    //Add RestClient.Net with a default Base Url of http://www.test.com
    .AddRestClient((o) => o.BaseUrl = "http://www.test.com".ToAbsoluteUrl());

//Use HttpClient dependency injection
_ = serviceCollection.AddHttpClient();

URLs

System.Uri — это раздутый класс, который создает множество запутанных случаев. Например, если поставить косую черту не в том месте, это может привести к неверному URL-адресу. Объединение Uris подвержено ошибкам, и из-за этого возникает множество тонких ошибок.

RestClient.Net использует библиотеку Urls вместо System.Uri для создания и передачи URL-адресов по всей системе. Это упрощает создание URL-адресов, делает их более читаемыми и менее подверженными ошибкам. Добавление пути и строки запроса к базовому URL-адресу всегда безопасно, и вам не нужно беспокоиться о объединении строк вручную. Между прочим, переход на эту библиотеку резко повысил оценку RestClient.Net при тестировании на мутации. Вероятно, это связано с меньшим количеством возможных случаев.

Вот пример F #

[<TestMethod>]
member this.TestComposition () =

    let uri =
        "host.com".ToHttpUrlFromHost(5000)
        .AddQueryParameter("fieldname1", "field<>Value1")
        .WithCredentials("username", "password")
        .AddQueryParameter("FieldName2", "field<>Value2")
        .WithFragment("frag")
        .WithPath("pathpart1", "pathpart2")

    Assert.AreEqual("http://username:[email protected]:5000/pathpart1/pathpart2?fieldname1=field%3C%3EValue1&FieldName2=field%3C%3EValue2#frag",uri.ToString());

Неизменяемые типы

HttpClient позволяет изменять множество свойств. Это означает, что если несколько частей вашей системы используют один и тот же экземпляр, они могут изменить какое-то свойство и сломать другую часть системы. Например, один класс может добавить заголовок по умолчанию, а другой класс может удалить его. Это проблема безопасности потоков. Все классы в RestClient.Net неизменяемы. Вы не можете изменить их значения после постройки. Это соответствует подходу к программированию в функциональном стиле, который знаком программистам на F #. Вы можете быстро клонировать существующий клиент, используя методы With (неразрушающая мутация) или использовать параметры фабрики CreateClient, чтобы указать свойства клиента.

var client = new Client(
  new NewtonsoftSerializationAdapter(),
  baseUrl: testServerBaseUri,
  defaultRequestHeaders: 
    HeadersExtensions
      .FromJsonContentType()
      //Non-destructive mutation to create a new headers collection
      .WithBearerTokenAuthentication(bearerToken));

Почему RestClient .Net?

Поддержка старых версий (.NET Framework 4.5, .NET Standard 2.0)

Многие команды застряли на старых версиях .NET, Xamarin или UWP. Эти системы не предлагают того же API, что и .NET Core. Вы можете использовать RestClient.Net прямо сейчас и взять его с собой при обновлении до .NET Core. RestClient возник на фоне разрозненных реализаций .NET. Я понимаю, что экосистема .NET не так проста, как многие думают. В вашей кодовой базе должен быть первоклассный клиент Rest, независимо от того, какую реализацию .NET вы используете.

Тщательно протестировано

RestClient.Net следует за разработкой, основанной на тестировании, и на .NET Core имеется 100% покрытие кода. Я также использую Stryker Mutator для тестирования модульных тестов и получил 66% и улучшился. Это означает, что если я что-то сломаю в будущем, вероятность того, что модульные тесты обнаружат эту проблему, высока.

Это просто и масштабируется

Вы можете выполнить вызов с помощью одной строки кода, повторно использовать клиента и выполнять последующие вызовы, указав новый RelativeUrls. Это означает меньше возни, когда вы начинаете новый проект, но это не значит, что вы откажетесь от хорошей практики. Я использую RestClient.Net, потому что считаю его наиболее доступным клиентом при запуске нового проекта, но я также могу доверять ему в более сложных проектах.

Нет известных ошибок

Я исправил несколько ошибок между V4 и V5. На момент выпуска нет известных ошибок, и в будущем я буду рассматривать ошибки с высоким приоритетом. RestClient.Net идеально фокусируется на основных операциях REST по отправке и получению данных через HTTP. Особенности появляются только тогда, когда они не имеют изгибов.

Подведение итогов

Попробуйте RestClient.Net для своего следующего проекта. Возьмите пакет RestClient.Net.DependencyInjection, если вы используете внедрение зависимостей ASP.NET Core или RestClient.Net для использования базовой библиотеки. В настоящее время в решении для примеров есть образец Blazor, и я скоро обновлю образцы Uno Platform и Xamarin Forms с версии 4. Помогите своей команде отказаться от ненадлежащего использования HttpClient.