NClient
v0.13.0
nclient: ไคลเอนNClient เป็นไคลเอนต์ HTTP ที่ปลอดภัยแบบอัตโนมัติที่ปลอดภัยซึ่งสามารถเรียกวิธีการเว็บ API โดยใช้อินเทอร์เฟซที่มีคำอธิบายประกอบ ความแตกต่างที่สำคัญระหว่าง NClient และ analogues คือ 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 ) ; คุณชอบไหม สนับสนุนการพัฒนาโครงการนี้และแสดง repo นี้!
การสร้างไคลเอนต์สำหรับบริการเว็บอาจเป็นเรื่องที่ท้าทายเพราะนอกเหนือจากการถ่ายโอนข้อมูลคุณต้องใช้การสร้างแบบสอบถามการทำให้เป็นอนุกรมนโยบายการลองทำแผนที่การจัดการข้อผิดพลาดและการเข้าสู่ระบบ - ไม่ต้องพูดถึงการบำรุงรักษาที่มาพร้อมกับการอัปเดต API ของคุณ ถ้าคุณสามารถสร้างลูกค้าด้วยความพยายามเพียงเล็กน้อย นี่คือสิ่งที่ Nclient มีจุดมุ่งหมายเพื่อให้บรรลุโดยอนุญาตให้คุณสร้างลูกค้าอย่างประกาศ
โดยวิธีการที่คุณสามารถมีส่วนร่วมใน nclient ไม่ใช่แค่ใช้มัน?
คุณสมบัติ: การกำหนดเส้นทางแบบไดนามิกแบบไดนามิก; เส้นทางคงที่; พารามิเตอร์แบบสอบถามแบบไดนามิก คอลเลกชันเป็นพารามิเตอร์การสืบค้น ส่วนหัวแบบไดนามิก ส่วนหัวคงที่; ร่างกายแบบไดนามิก การทำให้เป็นอนุกรมอัตโนมัติและ deserialization; บริบท http/การขนส่ง; การรับรองความถูกต้อง; คำขอแบบอะซิงโครนัส; หมดเวลา; คำขอยกเลิก นโยบายความยืดหยุ่น การตรวจสอบการตอบสนอง การทำแผนที่การตอบสนอง อัปโหลด/ดาวน์โหลดไฟล์; อินเทอร์เฟซทั่วไป การสืบทอดอินเทอร์เฟซ โรงงานลูกค้า เวอร์ชัน; การจัดการ; การตัดไม้ที่มีโครงสร้าง; การสนับสนุนการฉีดพึ่งพา
วิธีที่ง่ายที่สุดคือการติดตั้งแพ็คเกจ nclient โดยใช้ NUGET:
dotnet add package NClient
การใช้ไลบรารี NClient ต้องการ. NET Standard 2.0 หรือสูงกว่า ตัวควบคุม NClient สามารถใช้กับ ASP.NET Core และ. NET Core 3.1 เป้าหมายหรือสูงกว่า
ก่อนอื่นคุณต้องสร้างอินเทอร์เฟซที่อธิบายถึงจุดสิ้นสุดที่มีอยู่และข้อมูลอินพุต/เอาต์พุตของบริการผ่านคำอธิบายประกอบ หลังจากนั้นคุณสามารถเลือกประเภทของไคลเอนต์ที่ต้องการใน 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 Controllers; ตัวอย่างเช่นแอตทริบิวต์ BodyParamAttribute จะถูกตั้งค่าโดยปริยายเป็นพารามิเตอร์ผลิตภัณฑ์ในวิธี createasync และแน่นอนว่าเทมเพลตเส้นทางยังได้รับการสนับสนุน อ่านเกี่ยวกับคุณสมบัติทั้งหมดในส่วนคำอธิบายประกอบและการกำหนดเส้นทาง
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. Build ( ) ; วิธีการ GetRest สร้างไคลเอนต์ REST ด้วย System.Text.Json serialization และไม่มีนโยบายความยืดหยุ่น
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 ที่สนับสนุนโครงการด้วยใบอนุญาตผู้ขับขี่โอเพนซอร์สฟรี
