NClient
v0.13.0
NCLIENT : 자동 유형-안전 .NET HTTP 클라이언트NCLIENT는 주석이 달린 인터페이스를 사용하여 웹 API 메소드를 호출 할 수있는 자동 유형-안전 .NET HTTP 클라이언트입니다. 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/전송 컨텍스트; 입증; 비동기 요청; 타임 아웃; 취소 요청; 탄력성 정책; 응답 검증; 응답 매핑; 파일 업로드/다운로드; 일반 인터페이스; 인터페이스 상속; 고객 공장; 버전 작성; 손질; 구조화 된 벌목; 의존성 주입 지원.
가장 쉬운 방법은 Nuget을 사용하여 Nclient 패키지를 설치하는 것입니다.
dotnet add package NClient
NCLIENT 라이브러리를 사용하려면 .NET 표준 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
이 명령은 OpenAPI (Swagger) 사양을 사용하여 API에 대한 인터페이스를 생성합니다.
[ 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 메소드는 System.Text.Json 직렬화와 탄력성 정책없이 REST 클라이언트를 만듭니다.
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 를 호출 한 후 필요에 따라 클라이언트를 구성 할 수 있습니다. 예를 들어, 시리얼 라이저를 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 ) ;
}사용하려는 NCLIENT 속성과 의미 론적 충돌을 일으킬 수있는 ASP.NET 속성으로 컨트롤러에 주석을 달지 마십시오. 그러나 다른 속성 (자체 포함)은 제한없이 사용할 수 있습니다.
[ 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 메소드와 함께 사용할 수 있습니다. 이를 통해 동일한 애플리케이션에서 NCLIENT 컨트롤러와 함께 표준 ASP.NET 컨트롤러를 사용할 수 있습니다.
NClient 패키지를 설치하십시오 dotnet add package NClient
IWeatherForecastController client = NClientGallery . Clients . GetRest ( )
. For < IWeatherForecastController > ( host : "http://localhost:8080" )
. Build ( ) ; 4 단계를 따르기로 결정한 경우 IWeatherForecastController 대신 IWeatherForecastClient 인터페이스를 사용하십시오.
// 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에게 감사의 말을 전합니다.
