hexarc pact

สนธิสัญญา hexarc

SPACT Hexarc เป็นเครื่องมือสำหรับการเปิดเผยและใช้ Web API สำหรับโครงการ. NET/TypeScript

พัฒนาโครงการ. NET Web API ของคุณด้วย PACT เพื่อรักษาแหล่งความจริงเดียวสำหรับข้อมูลเมตา API และใช้งานได้ทั่วทั้งระบบนิเวศ. NET (Microservices, เดสก์ท็อปและแอปพลิเคชันมือถือ) หรือบนเว็บผ่านตัวพิมพ์

บรรจุุภัณฑ์	แพลตฟอร์ม	รุ่น	การดาวน์โหลด
Hexarch.Pact.Protocol	.NET 7.0+
Hexarch.Pact.AspNetCore	.NET 7.0+
Hexarch.Pact.Client	.NET 7.0+
Hexarch.Pact.Tool	.NET 7.0+
@hexarc/pact-tool	ตัวพิมพ์ใหญ่

มีอะไรในสนธิสัญญา?

• คุณสมบัติ
• พิมพ์ระบบ
• กฎคำอธิบายประกอบ API
  • คุณลักษณะเพิ่มเติม
• Demo API
• วิธีใช้
  • เปิดเผย PACT API Schema (.NET Web API Service)
  • กินสคีมา PACT API (แอปพลิเคชันไคลเอนต์ NET)
• กิตติกรรมประกาศ
• ใบอนุญาต

คุณสมบัติ

• การรวม API ที่ไม่ยุ่งยากในไม่กี่วินาที
• ไม่มีการสูญเสียข้อมูลประเภท กิน API ที่แน่นอนตามที่ออกแบบมา
• รหัสก่อน ไม่จำเป็นต้องอธิบายโปรโตคอล API ของคุณใน IDL/DSL ภายนอก
• เรียกเก็บเงินกับประเภทขั้นสูง ไม่เพียง แต่ DTOs ที่เรียบง่ายเท่านั้น แต่ยังรวมถึง enums, Generics, Tagged Unions ฯลฯ

พิมพ์ระบบ

ระบบประเภท PACT ขึ้นอยู่กับประเภท. NET CLR ที่มีบางส่วนสำหรับประสบการณ์การพัฒนาที่ดีที่สุด

มีอะไรอยู่ในระบบประเภท PACT:

• ประเภทดั้งเดิม (รวมถึง Guid และ DateTime )
• ความหมายประเภทค่า/อ้างอิง
• คอลเลกชันและยาสามัญ (ไม่เพียง แต่อาร์เรย์และพจนานุกรมที่เรียบง่าย)
• การสนับสนุนที่สมบูรณ์สำหรับคำอธิบายประกอบประเภทอ้างอิงที่เป็นโมฆะ (NRT)
• enums (ตามสตริงและตามจำนวน)
• Tagged Unions (ผ่าน hexarc.serialization.Union)
• tuples (ผ่าน hexarc.serialization.tuple)

กฎคำอธิบายประกอบ API

Schema Pact API ได้รับการออกแบบให้มีความหมายคล้าย RPC ในการทำเช่นนั้น API ที่เปิดเผยจะต้องปฏิบัติตามกฎเหล่านี้:

• ตัวควบคุม API จะต้องทำเครื่องหมายด้วย ApiController มาตรฐานและแอตทริบิวต์ Route
• แอตทริบิวต์เส้นทางจะต้องมีเส้นทางสตริงคงที่โดยไม่ต้องใช้เทมเพลต (เช่น [Route("Entities")] )
• วิธี API จะต้องทำเครื่องหมายด้วยหนึ่งในคำกริยา HTTP ที่รองรับ ( HttpGet หรือ HttpPost ) แอตทริบิวต์คำกริยาอาจมีเส้นทางปลายทาง คนอื่นไม่ได้รับการสนับสนุนในขณะนี้
  • วิธี HttpGet สามารถมีพารามิเตอร์การสืบค้นซึ่งจะต้องผูกผ่านแอตทริบิวต์ FromQuery
  • วิธี HttpPost จะต้องมีพารามิเตอร์เดียวเท่านั้นซึ่งเป็นตัวคำขอ
• สามารถระบุเส้นทาง API Method ในแอตทริบิวต์ HTTP VERB หรือแอตทริบิวต์ Route หากไม่ได้ระบุเส้นทางเมธอดในแอตทริบิวต์ HTTP คำกริยามันจะถูกนำมาจาก Route ที่หนึ่งหรือจะยกข้อยกเว้น

คุณลักษณะเพิ่มเติม

PACT ให้คุณลักษณะที่เป็นประโยชน์สำหรับคำอธิบายประกอบ API:

• PactIgnoreAttribute สามารถนำไปใช้กับตัวควบคุม API หรือวิธีการที่จะแยกออกจากสคีมา API
• PactScopeAttribute สามารถนำไปใช้กับตัวควบคุม API เพื่อแยกออกเป็นขอบเขตเฉพาะในสคีมา API

เซิร์ฟเวอร์ Demo API

Demo API Server สามารถดูได้ที่ https://hexarc-demo-api.herokuapp.com/

Schema Pact API ถูกเปิดเผยที่ https://hexarc-demo-api.herokuapp.com/pact/schema

เพื่อสร้างไคลเอนต์ API ให้ใช้คำสั่งด้านล่าง

วิธีใช้

ค้นหาวิธีใช้สนธิสัญญาเพื่อเปิดเผยและบริโภคเว็บ API ทั่วไป

เปิดเผยสคีมา Pact API

1. ติดตั้งแพ็คเกจ Hexarc.Pact.AspNetCore ในโครงการ. Web API:

dotnet add package Hexarc.Pact.AspNetCore

2. เพิ่มการสร้าง Schema Pact ในวิธี Startup.ConfigureServices :

 public void ConfigureServices ( IServiceCollection services )
{
    services . AddControllers ( ) ;

    // Register the Pact schema generation.
    services . AddPactGeneration ( ) ;
}

3. เปิดใช้งาน Middleware PACT ในวิธี Startup.Configure :

 public void Configure ( IApplicationBuilder app )
{
    // Enable the Pact middleware to expose the generated API schema.
    app . UsePact ( ) ;

    app . UseRouting ( ) ;
    app . UseEndpoints ( endpoints => endpoints . MapControllers ( ) ) ;
}

4. ใช้ตัวควบคุม API ตามกฎคำอธิบายประกอบ PACT:

 [ ApiController , Route ( "Misc" ) ]
public sealed class MiscController : ControllerBase
{
    [ HttpGet ( nameof ( Ping ) ) ]
    public String Ping ( [ FromQuery ] String message ) => $ "Hello, { message } " ;
}

5. เริ่มต้นแอปและเปิดที่อยู่ YOUR_API_HOST/pact/schema เพื่อให้แน่ใจว่า Schema PACT API ถูกสร้างขึ้น

กินสคีมา Pact API

1. ติดตั้งแพ็คเกจ Hexarc.Pact.Client ในโครงการ. NET:

dotnet add package Hexarc.Pact.Client

2. ติดตั้งเครื่องมือ Hexarc.Pact.Tool ในโครงการ:

dotnet tool install Hexarc.Pact.Tool

คุณอาจต้องตั้งค่าเครื่องมือ. NET Manifesto ก่อนที่จะติดตั้งเครื่องมือ Hexarc.Pact.Tool :

dotnet new tool-manifest

3. เพิ่ม pact.json config ในโครงการด้วยการตั้งค่าการสร้างไคลเอนต์ API ที่ต้องการ:

{
   "schemaUri" : " YOUR_API_HOST/pact/schema " ,
   "clientClassName" : " DemoClient " ,
   "clientClassNamespace" : " DemoNamespace " ,
   "outputDirectory" : " Generated "
}

ที่ไหน

• schemaUri - เชื่อมโยงไปยัง Schema Pact API
• clientClassName - ชื่อสำหรับคลาสไคลเอนต์ API ที่สร้างขึ้น
• clientClassNamespace - เนมสเปซที่จะใส่ในคลาสไคลเอนต์ API ที่สร้างขึ้น
• outputDirectory - ไดเรกทอรีเอาต์พุตสำหรับแหล่งที่มาที่สร้างขึ้น

4. สร้างไคลเอนต์ API ผ่านเครื่องมือ PACT CLI:

dotnet pact

คำสั่งนี้จะต้องดำเนินการในโฟลเดอร์เดียวกันกับ pact.json config

5. ไคลเอนต์ API ที่สร้างขึ้นจะพร้อมใช้งานสำหรับการเข้าถึงเซิร์ฟเวอร์ API:

 var client = new DemoClient ( new HttpClient { BaseAddress = new Uri ( "YOUR_API_HOST" ) } ) ;
var pong = await client . Misc . Ping ( "World" ) ;
Console . WriteLine ( pong ) ; // Prints "Hello, World" to the output. 

กิตติกรรมประกาศ

สร้างขึ้นด้วยเครื่องมือ Jetbrains สำหรับโครงการโอเพนซอร์ส

ใบอนุญาต

MIT © Max Koverdyaev