hexarc pact

Pakta hexarc

HEXARC PACT menyediakan toolchain untuk mengekspos dan mengonsumsi API Web untuk proyek berbasis .NET/TypeScript.

Kembangkan proyek API .NET Web Anda dengan PACT untuk menjaga satu sumber kebenaran untuk metadata API dan mengkonsumsinya di seluruh ekosistem.

Kemasan	Platform	Versi	Unduhan
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	Naskah

Apa yang ada di Pakta?

• Fitur
• Ketik sistem
• Aturan Anotasi API
  • Atribut tambahan
• Demo API
• Cara menggunakan
  • Ekspos Pact API Skema (.NET Web API Service)
  • Konsumsi Skema API PACT (Aplikasi Klien .NET)
• Ucapan Terima Kasih
• Lisensi

Fitur

• Integrasi API bebas kerumitan dalam hitungan detik.
• Tidak ada informasi tipe yang hilang. Konsumsi API yang tepat seperti yang dirancang.
• Kode terlebih dahulu. Tidak perlu menggambarkan protokol API Anda di IDL/DSL eksternal.
• Dibebankan dengan tipe canggih. Tidak hanya DTOS sederhana tetapi enum, obat generik, serikat yang ditandai, dll.

Ketik sistem

Sistem tipe pakta didasarkan pada tipe .NET CLR dengan beberapa yang dipesan lebih dahulu untuk pengalaman pengembangan terbaik.

Apa yang ada di dalam sistem jenis pakta:

• Tipe primitif (termasuk Guid dan DateTime )
• Nilai/Jenis Referensi Semantik
• Koleksi dan obat generik (bukan hanya array dan kamus sederhana)
• Dukungan Lengkap untuk Anotasi Jenis Referensi Nullable (NRT)
• Enums (berbasis string dan berbasis angka)
• Tagged Unions (via hexarc.serialization.union)
• Tuples (via hexarc.serialization.tuple)

Aturan Anotasi API

Skema PACT API dirancang untuk memiliki semantik seperti RPC. Dengan melakukan itu, API yang terbuka harus mengikuti aturan ini:

• Pengontrol API harus ditandai dengan atribut ApiController dan Route standar.
• Atribut rute harus hanya memiliki jalur string konstan tanpa templating (misalnya [Route("Entities")] ).
• Metode API harus ditandai dengan salah satu kata kerja HTTP yang didukung ( HttpGet atau HttpPost ). Atribut kata kerja mungkin berisi jalur titik akhir. Yang lain tidak didukung saat ini.
  • Metode HttpGet dapat memiliki parameter kueri yang harus diikat melalui atribut FromQuery .
  • Metode HttpPost harus memiliki hanya satu parameter yang merupakan badan permintaan.
• Jalur metode API dapat ditentukan dalam atribut kata kerja HTTP atau atribut Route . Jika jalur metode tidak ditentukan dalam atribut kata kerja http, itu akan diambil dari Route satu atau pengecualian akan dinaikkan.

Atribut tambahan

Pakta memberikan beberapa atribut yang berguna untuk anotasi API:

• PactIgnoreAttribute dapat diterapkan pada pengontrol API atau metode yang akan dikeluarkan dari skema API.
• PactScopeAttribute dapat diterapkan pada pengontrol API untuk diisolasi ke dalam ruang lingkup spesifik dalam skema API.

Demo API Server

Demo API Server dapat ditemukan di https://hexarc-demo-api.herokuapp.com/.

Skema API PACT diekspos di https://hexarc-demo-api.herokuapp.com/pact/schema.

Untuk menghasilkan klien API, gunakan instruksi di bawah ini.

Cara menggunakan

Cari tahu cara menggunakan pakta untuk mengekspos dan mengonsumsi API Web yang khas.

Ekspos Pact API Skema

1. Instal paket Hexarc.Pact.AspNetCore dalam proyek API web .net:

dotnet add package Hexarc.Pact.AspNetCore

2. Tambahkan generasi skema pakta di metode Startup.ConfigureServices :

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

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

3. Aktifkan Pact Middleware dalam metode 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. Menerapkan pengontrol API sesuai dengan aturan anotasi pakta:

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

5. Mulai aplikasi dan buka alamat YOUR_API_HOST/pact/schema untuk memastikan skema API PACT dihasilkan.

Konsumsi skema API pakta

1. Instal paket Hexarc.Pact.Client di proyek .net:

dotnet add package Hexarc.Pact.Client

2. Instal alat Hexarc.Pact.Tool dalam proyek:

dotnet tool install Hexarc.Pact.Tool

Anda mungkin perlu mengatur manifesto alat .net sebelum menginstal alat Hexarc.Pact.Tool :

dotnet new tool-manifest

3. Tambahkan konfigurasi pact.json dalam proyek dengan pengaturan pembuatan klien API yang diinginkan:

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

Di mana

• schemaUri - Tautan ke Skema API pakta
• clientClassName - Nama untuk kelas klien API yang dihasilkan
• clientClassNamespace - Namespace di mana harus dimasukkan ke dalam kelas klien API yang dihasilkan
• outputDirectory - Direktori Output untuk sumber yang dihasilkan

4. Hasilkan Klien API melalui Pact CLI Tool:

dotnet pact

Perintah ini harus dilakukan di folder yang sama dengan konfigurasi pact.json .

5. Klien API yang dihasilkan akan tersedia untuk mengakses server 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. 

Ucapan Terima Kasih

Dibangun dengan alat JetBrains untuk proyek open source.

Lisensi

MIT © Max Kovertyaev