NClient
v0.13.0
Nclient: cliente HTTP .NET de tipo automático.NClient es un cliente .NET HTTP automático, tipo seguro, que puede llamar a métodos de API web utilizando interfaces anotadas. La principal diferencia entre Nclient y sus análogos es que Nclient le permite anotar controladores ASP.NET a través de interfaces y luego usar estas interfaces para crear clientes. Esto le permite deshacerse de las dependencias no deseadas del lado del cliente y reutilizar una descripción de la API en los clientes sin código Boilerplate.
// 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 ) ; ¿Te gusta? ¡Apoye el desarrollo de este proyecto y protagonice este repositorio!
La creación de clientes para los servicios web puede ser un gran desafío porque, además de la transferencia de datos, debe implementar la construcción de consultas, la serialización, las políticas de reintento, el mapeo, el manejo de errores y el registro, sin mencionar el mantenimiento que viene con cada actualización de sus API. ¿Qué pasaría si pudiera crear clientes con una fracción del esfuerzo? Esto es exactamente lo que Nclient tiene como objetivo lograr al permitirle crear clientes declarativamente.
Por cierto, ¿puede contribuir al Nclient, no solo usarlo?
Características: Enrutamiento plantado dinámico; Enrutamiento estático; Parámetros de consulta dinámica; Colecciones como parámetros de consulta; Encabezados dinámicos; Encabezados estáticos; Cuerpo dinámico; Serialización automática y deserialización; HTTP/Contexto de transporte; Autenticación; Solicitudes asincrónicas; Tiempos de espera; Solicitudes de cancelación; Política de resiliencia; Validación de respuesta; Mapeo de respuesta; Archivo de carga/descarga; Interfaces genéricas; Herencia de interfaz; Fábrica de clientes; Versiones; Manejo; Registro estructurado; Soporte de inyección de dependencia.
La forma más fácil es instalar el paquete Nclient con NUGET:
dotnet add package NClient
El uso de la biblioteca Nclient requiere .NET Standard 2.0 o superior. Los controladores Nclient se pueden usar con ASP.NET Core y .NET Core 3.1 Target o superior.
Primero, debe crear una interfaz que describa los puntos finales disponibles y los datos de entrada/salida de un servicio a través de anotaciones. Después de eso, puede seleccionar el tipo de cliente requerido en NClientGallery y luego establecer configuraciones adicionales si es necesario.
Si desea enviar solicitudes a un servicio de terceros, debe crear una interfaz que describa el servicio al que desea realizar solicitudes. Siga los pasos a continuación:
NClient en el proyecto del cliente 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
Este comando generará una interfaz para la API utilizando la especificación OpenApi (swagger):
[ Path ( "api" ) ]
public interface IProductServiceClient
{
[ PostMethod ( "products" ) ]
Task < Product > CreateAsync ( Product product ) ;
[ GetMethod ( "products/{id}" ) ]
Task < Product > GetAsync ( [ RouteParam ] int id ) ;
} Si es necesario, la interfaz se puede cambiar. Es fácil hacer esto porque la anotación de la interfaz es muy similar a la anotación de controladores en ASP.NET. El PathAttribute define la ruta base para todos los métodos de interfaz. El PostMethodAttribute especifica el tipo de método HTTP y la ruta al punto final. Además, las anotaciones implícitas funcionan como en los controladores ASP.NET; Por ejemplo, el atributo BodyParamAttribute se establecerá implícitamente en el parámetro del producto en el método CreateAsync. Y ciertamente, las plantillas de ruta también son compatibles. Lea sobre todas las características en las secciones de anotación y enrutamiento.
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. Build ( ) ; El método GetRest crea un cliente REST con System.Text.Json Serialization y sin una política de resiliencia.
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 ( ) ; Después de llamar al método For , puede configurar el cliente según sea necesario. Por ejemplo, puede reemplazar el serializador con Newtonsoft.Json , agregar una política de reintento, etc. Ver la documentación completa.
// 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" ) ) ;Si desea generar un cliente para su servicio web ASP.NET, debe extraer una interfaz para su controlador y anotarlo con los atributos de Nclient. Estos atributos son muy similares a los utilizados para los controladores ASP.NET. Siga los pasos a continuación:
NClient.AspNetCore en el lado del servidor dotnet add package NClient.AspNetCore
public class WeatherForecastController : ControllerBase
{
public async Task < WeatherForecast > GetAsync ( DateTime date ) =>
new WeatherForecast ( date : date , temperatureC : - 25 ) ;
}No anote su controlador con los atributos ASP.NET que pueden causar conflictos semánticos con los atributos NCLIENT que tiene la intención de usar. Sin embargo, otros atributos (incluido el suyo) se pueden usar sin restricciones.
[ 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 { .. . }La anotación en la interfaz en lugar del controlador le permite colocar la interfaz en un ensamblaje separado. En consecuencia, el cliente que usa esta interfaz no depende de la aplicación ASP.NET.
public interface IWeatherForecastClient : IWeatherForecastController { } Debe hacerlo si desea que su tipo de cliente no contenga "controlador" en el nombre o si desea anular algunos métodos para el cliente (consulte OverrideAttribute en la sección de anotación). No hay necesidad de duplicar los atributos de la interfaz, ya que son heredados.
public void ConfigureServices ( IServiceCollection services )
{
.. .
services . AddNClientControllers ( ) ;
} El método AddNClientControllers se puede usar en combinación con el método AddControllers . Esto le permite usar controladores ASP.NET estándar junto con controladores Nclient en la misma aplicación.
NClient en el lado del cliente dotnet add package NClient
IWeatherForecastController client = NClientGallery . Clients . GetRest ( )
. For < IWeatherForecastController > ( host : "http://localhost:8080" )
. Build ( ) ; Si decide seguir el cuarto paso, use la interfaz IWeatherForecastClient en lugar de 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 ) ; Puede encontrar documentación de Nclient en el wiki.
Ver muestras de aplicaciones en el proyecto Nclient.samples.
¿Estás pensando en contribuir a Nclient? ¡Excelente! ¡Nos encanta recibir contribuciones de la comunidad! La contribución más simple es darle a este proyecto una estrella.
Ayudar con la documentación, extraer solicitudes, problemas, comentarios o cualquier otra cosa también es muy bienvenido. Revise nuestra guía de contribución.
Vale la pena ponerse en contacto con nosotros para discutir cambios en el caso de cualquier pregunta. También podemos dar consejos sobre la forma más fácil de hacer las cosas.
El Nclient desea agradecer a JetBrains por apoyar el proyecto con licencias gratuitas de Wraider Open Source.
