NClient
v0.13.0
NClient: Automatic Type-Safe .net http clientNClient-это автоматический клиент HTTP-клиента .NET .NET, который может вызывать методы веб-API с использованием аннотированных интерфейсов. Основное различие между NClient и его аналогами заключается в том, что NClient позволяет аннотировать контроллеры ASP.NET через интерфейсы, а затем использовать эти интерфейсы для создания клиентов. Это позволяет вам избавиться от нежелательных зависимостей от клиента и повторно использовать описание API в клиентах без кода шаблона.
// WebService.dll:
public class WeatherController : ControllerBase , IWeatherFacade {
public Task < Weather > GetAsync ( string city , DateTime date ) => .. . ;
}
// WebService.Facade.dll:
[ HttpFacade , Path ( "api/[facade]" ) ]
public interface IWeatherFacade {
[ GetMethod ( "{city}" ) ]
Task < Weather > GetAsync ( [ RouteParam ] string city , [ QueryParam ] DateTime date ) ;
}
// Client.dll:
IWeatherFacade weatherFacade = NClientGallery . Clients . GetRest ( )
. For < IWeatherFacade > ( host : "http://localhost:5000" )
. WithSafeResilience ( maxRetries : 3 )
. Build ( ) ;
Weather todaysWeather = await weatherFacade . GetAsync ( city : "Chelyabinsk" , date : DateTime . Today ) ; Вам это нравится? Поддержите разработку этого проекта и составите этот репо!
Создание клиентов для веб -служб может быть довольно сложной задачей, потому что, в дополнение к передаче данных, вам необходимо реализовать построение запросов, сериализацию, политики повторения, картирование, обработку ошибок и регистрацию - не говоря уже о техническом обслуживании, которое поставляется с каждым обновлением ваших API. Что если бы вы могли создать клиентов с частью усилий? Это именно то, чего Nclient стремится достичь, позволяя вам декларативно создавать клиентов.
Кстати, вы можете внести свой вклад в NClient, а не просто использовать его?
Особенности: динамическая шаблонная маршрутизация; Статическая маршрутизация; Динамические параметры запроса; Коллекции как параметры запроса; Динамические заголовки; Статические заголовки; Динамическое тело; Авто сериализация и десериализация; HTTP/транспортный контекст; Аутентификация; Асинхронные запросы; Тайм -ауты; Запросы на отмену; Политика устойчивости; Проверка ответа; Картирование ответов; Загрузка файла/скачать; Общие интерфейсы; Интерфейс наследование; Клиентский фабрика; Версия; Умение обращаться; Структурированная регистрация; Поддержка инъекции зависимости.
Самый простой способ - установить пакет NClient с помощью Nuget:
dotnet add package NClient
Использование библиотеки NClient требует .NET STANTARD 2.0 или выше. Контроллеры NClient могут использоваться с целью ASP.NET Core и .NET Core 3.1 Target или выше.
Во -первых, вы должны создать интерфейс, описывающий доступные конечные точки и входные/выходные данные службы через аннотации. После этого вы можете выбрать необходимый тип клиента в NClientGallery , а затем установить дополнительные настройки для него, если это необходимо.
Если вы хотите отправить запросы в стороннюю службу, вам следует создать интерфейс, который описывает услугу, на которую вы хотите сделать запросы. Следуйте шагам ниже:
NClient в клиентский проект dotnet add package NClient
dotnet-nclient dotnet tool install --global dotnet-nclient
dotnet nclient generate facade --api path/to/product-service-swagger.json --output MyProject/Client.cs
Эта команда будет генерировать интерфейс для API с использованием спецификации OpenAPI (Swagger):
[ Path ( "api" ) ]
public interface IProductServiceClient
{
[ PostMethod ( "products" ) ]
Task < Product > CreateAsync ( Product product ) ;
[ GetMethod ( "products/{id}" ) ]
Task < Product > GetAsync ( [ RouteParam ] int id ) ;
} При необходимости интерфейс может быть изменен. Это легко сделать, потому что аннотация интерфейса очень похожа на аннотацию контроллеров в ASP.NET. PathAttribute определяет базовый путь для всех методов интерфейса. PostMethodAttribute указывает тип метода HTTP и путь к конечной точке. Более того, неявные аннотации работают, как в контроллерах ASP.NET; Например, атрибут BodyParamAttribute будет неявно устанавливаться на параметр продукта в методе CreateAsync. И, конечно, шаблоны маршрута также поддерживаются. Прочитайте обо всех функциях в разделах аннотации и маршрутизации.
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. Build ( ) ; Метод GetRest создает клиента REST с сериализацией System.Text.Json и без политики устойчивости.
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. WithNewtonsoftJsonSerialization ( )
. WithResilience ( x => x
. ForMethod ( client => ( Func < Product , Task < Product > > ) client . CreateAsync )
. Use ( maxRetries : 2 , attempt => TimeSpan . FromSeconds ( Math . Pow ( 2 , attempt ) ) ) )
.. .
. Build ( ) ; После вызова For вы можете настроить клиента по мере необходимости. Например, вы можете заменить Serializer на Newtonsoft.Json , добавить политику повторной попытки и так далее. Смотрите полную документацию.
// Equivalent to the following request:
// curl -X POST -H "Content-type: application/json" --data "{ id: 1 }" http://localhost:8080/api/products
Product product = await client . CreateAsync ( new Product ( name : "MyProduct" ) ) ;Если вы хотите создать клиента для вашего веб -службы ASP.NET, вам необходимо извлечь интерфейс для вашего контроллера и аннотировать его с помощью атрибутов NClient. Эти атрибуты очень похожи на те, которые используются для контроллеров ASP.NET. Следуйте шагам ниже:
NClient.AspNetCore на стороне сервера dotnet add package NClient.AspNetCore
public class WeatherForecastController : ControllerBase
{
public async Task < WeatherForecast > GetAsync ( DateTime date ) =>
new WeatherForecast ( date : date , temperatureC : - 25 ) ;
}Не аннотируйте свой контроллер атрибутами ASP.NET, которые могут вызвать семантические конфликты с атрибутами NClient, которые вы намерены использовать. Однако другие атрибуты (включая ваши собственные) могут использоваться без ограничений.
[ HttpFacade , Path ( "[controller]" ) ] // equivalent to [ApiController, Route("[controller]")]
public interface IWeatherForecastController
{
[ GetMethod ] // equivalent to [HttpGet]
Task < WeatherForecast > GetAsync ( [ QueryParam ] DateTime date ) ; // equivalent to [FromQuery]
}
public class WeatherForecastController : ControllerBase , IWeatherForecastController { .. . }Аннотация в интерфейсе вместо контроллера позволяет разместить интерфейс в отдельную сборку. Следовательно, клиент, использующий этот интерфейс, не зависит от приложения ASP.NET.
public interface IWeatherForecastClient : IWeatherForecastController { } Вы должны сделать это, если вы хотите, чтобы ваш тип клиента не содержал «контроллера» в имени или если вы хотите переопределить некоторые методы для клиента (см. OverrideAttribute в разделе аннотации). Нет необходимости дублировать атрибуты интерфейса, поскольку они наследуются.
public void ConfigureServices ( IServiceCollection services )
{
.. .
services . AddNClientControllers ( ) ;
} Метод AddNClientControllers может использоваться в сочетании с методом AddControllers . Это позволяет вам использовать стандартные контроллеры ASP.NET вместе с контроллерами NClient в одном и том же приложении.
NClient на стороне клиента dotnet add package NClient
IWeatherForecastController client = NClientGallery . Clients . GetRest ( )
. For < IWeatherForecastController > ( host : "http://localhost:8080" )
. Build ( ) ; Если вы решите выполнить 4 -й шаг, используйте интерфейс IWeatherForecastClient вместо IWeatherForecastController .
// Equivalent to the following request:
// curl -X GET -H "Content-type: application/json" http://localhost:8080/WeatherForecast?date=2021-03-13T00:15Z
WeatherForecast forecast = await client . GetAsync ( DateTime . Now ) ; Вы можете найти документацию NClient на вики.
См. Образцы приложений в проекте nclient.samples.
Вы думаете о том, чтобы внести свой вклад в NClient? Большой! Мы любим получать вклад от сообщества! Самый простой вклад - дать этому проекту звезду.
Помощь в документации, запросах по выявлению, вопросам, комментариям или чем -то еще также очень приветствуется. Пожалуйста, просмотрите наше руководство по взносу.
Стоит связаться с нами, чтобы обсудить изменения в случае любых вопросов. Мы также можем дать советы по самым простым способу сделать что -то.
Nclient желает поблагодарить Jetbrains за поддержку проекта бесплатными лицензиями Rider Rider.
