Kontrak publik, bagaimana memastikan konsistensinya

• Apakah sistem Anda terdiri dari banyak layanan yang saling berhubungan?
• masih memperbarui kode layanan secara manual saat mengubah API publik?
• perubahan layanan Anda sering merusak pekerjaan orang lain, dan pengembang lain membenci Anda karena ini?

Ketentuan

Tentang apa artikel itu

Seperti apa masalahnya

Bagaimana mengatasi masalah ini

Tim layanan pemasok akan memperbaiki semuanya

Perbarui kode layanan Anda ke tim konsumen

Pikirkan apa yang harus dilakukan untuk mencegah masalah muncul

Bagaimana mencegah manifestasi suatu masalah

1. pada tahap desain secara deklaratif mendefinisikan kontrak;
2. selama implementasi, kami menghasilkan kode server dan klien di bawah kontrak;
3. saat menguji, kami memeriksa kontrak dan mencoba mempertimbangkan kebutuhan pelanggan (CDC).

Bagaimana masalah terlihat dengan kita

Dari masalah ke tugas

• sisi server - pengendali sudah ditulis;
• browser adalah klien dari layanan;
• Layanan berkomunikasi melalui HTTP.
• generasi harus disetel. Misalnya, untuk mendukung JWT.

Pertanyaan

• alat mana yang harus dipilih;
• cara mendapatkan kontrak;
• di mana menempatkan kontrak;
• di mana menempatkan kode klien;
• pada titik apa yang harus dilakukan generasi.

Alat mana yang harus dipilih

Alat

Alat untuk bekerja dengan OpenAPI

Di mana mengatur kontrak. Cara mengakses layanan ke kontrak

• Folder proyek layanan penyedia adalah pilihan termudah. Jika Anda perlu menjalankan pendekatan, maka pilihlah.
• folder bersama adalah opsi yang valid jika proyek yang diinginkan dalam repositori yang sama. Dalam jangka panjang, akan sulit untuk mempertahankan integritas kontrak dalam folder tersebut. Ini mungkin memerlukan alat tambahan untuk menjelaskan berbagai versi kontrak, dll.
• repositori terpisah untuk spesifikasi - jika proyek berada dalam repositori yang berbeda, maka kontrak harus ditempatkan di tempat umum. Kerugiannya sama dengan folder bersama.
• melalui API layanan (swagger.ui, swaggerhub) - layanan terpisah yang berhubungan dengan manajemen spesifikasi.

Pada titik apa yang Anda hasilkan

Di mana menempatkan kode klien

• kode klien dekat dengan layanannya dan selalu terbaru;
• konsumen dapat menggunakan tautan ke proyek dalam satu gudang.

• tidak akan berfungsi jika Anda perlu membuat klien di bagian lain dari sistem, misalnya, repositori yang berbeda. Itu dipecahkan menggunakan setidaknya folder bersama untuk kontrak;
• konsumen harus ditulis dalam bahasa yang sama. Jika Anda membutuhkan klien dalam bahasa lain, Anda perlu menggunakan OpenApiTools.

Kami kencangkan NSwag

Atribut Kontroler

[Microsoft.AspNetCore.Mvc.Routing.Route("[controller]")]  //  url
[Microsoft.AspNetCore.Mvc.ApiController] //     
public class DescriptionController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("GetDescription")] //    
[Microsoft.AspNetCore.Mvc.ProducesResponseType(typeof(ConversionDescription), 200)] //    200  
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)] //    401
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)] //    403
[Microsoft.AspNetCore.Mvc.HttpGet("{pluginName}/{binaryDataId}")] //  url
public ActionResult<ConversionDescription> GetDescription(string pluginName, Guid binaryDataId) { 
 // ... 
}

[Microsoft.AspNetCore.Mvc.Route("[controller]")]
[Microsoft.AspNetCore.Mvc.ApiController]
public class FileController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("SaveFile")]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)]
[Microsoft.AspNetCore.Mvc.HttpPost("{pluginName}/{binaryDataId}/{fileName}")]
[OurNamespace.FileUploadOperation] //  
public async Task SaveFile() { // ... }

Prosesor untuk menghasilkan spesifikasi untuk operasi file

• FileUploadOperationAttribute: OpenApiOperationProcessorAttribute
• FileUploadOperationProcessor: IOperationProcessor

Konfigurasi NSwag untuk pembuatan spec dan kode

• runtime - Menentukan runtime .net. Misalnya, NetCore22;
• documentGenerator - menjelaskan cara membuat spesifikasi;
• codeGenerators - mendefinisikan cara membuat kode sesuai dengan spesifikasi.

Kami menghasilkan spesifikasi dan kode klien ketika merakit proyek penyedia layanan

1. Kami membuat proyek WebApi untuk klien.
2. Kami menulis konfigurasi untuk Nswag CLI - Nswag.json (dijelaskan di bagian sebelumnya).
3. Kami menulis Target PostBuild di dalam proyek penyedia layanan csproj.

• $ (NSwagExe_Core22) jalankan nswag.json - jalankan utilitas NSwag di bawah .bet runtine netCore 2.2 dengan konfigurasi nswag.json

1. NSwag menghasilkan spesifikasi dari unit layanan vendor.
2. NSwag menghasilkan kode klien sesuai spesifikasi.

Bagaimana cara menambahkan dukungan untuk JWT

protected Task<HttpRequestMessage> CreateHttpRequestMessageAsync(CancellationToken cancellationToken) {
      var message = new HttpRequestMessage();

      if (!string.IsNullOrWhiteSpace(this.AuthorizationToken)) {
        message.Headers.Authorization =
          new System.Net.Http.Headers.AuthenticationHeaderValue(BearerScheme, this.AuthorizationToken);
      }

      return Task.FromResult(message);
    }

Kesimpulan

• spesifikasinya adalah verbose;
• , ;
• ;
• .

• , URL, HTTP ..;
• OpenAPI;
• ;
• ;
• HTTP/2.

Kontrak Versi Publik

Mengapa mengubah kontrak publik?

Opsi solusi

Tanpa versi kontrak publik

Gunakan versi kontrak publik

• alat mana yang digunakan;
• kapan harus memperkenalkan versi baru;
• berapa lama mempertahankan versi lama.

Alat mana yang digunakan

Kapan memperkenalkan versi baru

• untuk OpenAPI ada alat Azure opeanapi-diff untuk memeriksa kompatibilitas antara 2 spesifikasi github.com/Azure/openapi-diff;
• tidak ada alat otomatis ditemukan untuk gRPC, hanya ada kebijakan versi;
• general github.com/grpc/grpc/blob/master/doc/versioning.md;
• di bawah .Net docs.microsoft.com/en-us/aspnet/core/grpc/versioning?view=aspnetcore-3.1 .

Berapa lama untuk mempertahankan versi

• beri tahu pelanggan bahwa versi lama tidak akan lagi didukung. Dalam hal ini, kami dapat kehilangan pendapatan pelanggan;
• mendukung seluruh rangkaian versi. Biaya dukungan perangkat lunak meningkat;
• untuk menjawab pertanyaan ini, Anda perlu menanyakan bisnis - apakah pendapatan dari pelanggan lama melebihi biaya untuk mendukung versi perangkat lunak yang lebih lama? Mungkinkah lebih menguntungkan untuk meminta pelanggan memperbarui?

Kesimpulan

Kontrak Pengujian dan CDC

Kontrak yang digerakkan konsumen (CDC)

1. Konsumen menggambarkan kontrak.
2. Pemasok mengimplementasikan kontrak ini di rumah.
3. Kontrak ini digunakan dalam proses CI di konsumen dan pemasok. Jika prosesnya dilanggar, maka seseorang telah berhenti mematuhi kontrak.

Pakta

1. Konsumen menulis tes menggunakan perpustakaan PACT.
2. Tes ini dikonversi ke file pakta artefak. Ini berisi informasi tentang kontrak.
3. Penyedia dan konsumen menggunakan file pakta untuk menjalankan tes.

Tautan yang bermanfaat tentang Pakta

• Pact broker - pact solusi solusi manajemen file docs.pact.io/pact_broker
• Pakta belum mendukung GRPC. Baca lebih lanjut tentang roadmap Pact pact.canny.io .
• Informasi lebih lanjut tentang PACT di docs.pact.io .
• Mengapa Anda harus menggunakan PACT docs.pact.io/faq/convinceme

Bagaimana CDC dapat tertanam dalam CI

• menyebarkan Pakta + Pakta broker sendiri;
• membeli solusi SaaS Pact Flow yang sudah jadi.

Kesimpulan