العقود العامة ، وكيفية ضمان اتساقها

• هل يتكون نظامك من العديد من الخدمات المترابطة؟
• لا يزال تحديث رمز الخدمة يدويًا عند تغيير واجهة برمجة التطبيقات العامة؟
• غالبًا ما تقوض التغييرات في خدماتك عمل الآخرين ، ويكرهك المطورون الآخرون لهذا الأمر؟

شروط

عن ماذا تتحدث المقالة

كيف تبدو المشكلة

كيفية حل هذه المشكلة

سيقوم فريق خدمة الموردين بإصلاح كل شيء

قم بتحديث رمز خدمتك إلى فريق المستهلك

فكر في ما يجب فعله لمنع ظهور المشكلة

كيفية منع ظهور مشكلة

1. في مرحلة التصميم تحديد العقود بشكل معلن ؛
2. أثناء التنفيذ ، نقوم بإنشاء رمز الخادم والعميل بموجب العقود ؛
3. عند الاختبار ، نتحقق من العقود ونحاول أن نأخذ في الاعتبار احتياجات العملاء (CDC).

كيف تبدو المشكلة معنا

من مشكلة إلى مهمة

• جانب الخادم - تمت كتابة وحدات التحكم بالفعل ؛
• المتصفح هو عميل للخدمة ؛
• تتواصل الخدمات عبر HTTP.
• يجب ضبط الجيل. على سبيل المثال ، لدعم JWT.

الأسئلة

• الأداة التي تختارها ؛
• كيفية الحصول على العقود ؛
• مكان وضع العقود ؛
• مكان وضع رمز العميل ؛
• عند أي نقطة للقيام بالجيل.

الأداة التي تختارها

أدوات

أدوات للعمل مع OpenAPI

مكان ترتيب العقود. كيفية الوصول إلى الخدمات للعقود

• مجلد مشروع خدمة مقدم الخدمة هو الخيار الأسهل. إذا كنت بحاجة إلى تشغيل النهج ، فاختره.
• يعد المجلد المشترك خيارًا صالحًا إذا كانت المشاريع المطلوبة في نفس المستودع. على المدى الطويل ، سيكون من الصعب الحفاظ على سلامة العقود في المجلد. قد يتطلب هذا أداة إضافية لحساب الإصدارات المختلفة من العقود ، وما إلى ذلك.
• مستودع منفصل للمواصفات - إذا كانت المشاريع في مستودعات مختلفة ، فيجب وضع العقود في مكان عام. العيوب هي نفسها المجلد المشترك.
• من خلال واجهة برمجة تطبيقات الخدمة (swagger.ui ، swaggerhub) - خدمة منفصلة تتعامل مع إدارة المواصفات.

في أي نقطة تولد

مكان وضع رمز العميل

• رمز العميل قريب من خدمته ومحدّث باستمرار ؛
• يمكن للمستهلكين استخدام الارتباط بالمشروع داخل مستودع واحد.

• لن يعمل إذا كنت بحاجة إلى إنشاء عميل في جزء آخر من النظام ، على سبيل المثال ، مستودع مختلف. يتم حلها باستخدام مجلد مشترك على الأقل للعقود ؛
• يجب أن يكتب المستهلكون بنفس اللغة. إذا كنت بحاجة إلى عميل بلغة أخرى ، فأنت بحاجة إلى استخدام OpenApiTools.

نحن نربط NSwag

سمات المراقب

[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() { // ... }

معالج لتوليد المواصفات لعمليات الملف

• FileUploadOperationAttribute: OpenApiOperationProcessorAttribute
• FileUploadOperationProcessor: IOperationProcessor

تكوين NSwag للمواصفات وإنشاء التعليمات البرمجية

• وقت التشغيل - يحدد وقت تشغيل .net. على سبيل المثال ، NetCore22 ؛
• documentGenerator - يصف كيفية إنشاء المواصفات ؛
• codeGenerators - يحدد كيفية إنشاء التعليمات البرمجية وفقًا للمواصفات.

نقوم بإنشاء المواصفات ورمز العميل عند تجميع مشروع مزود الخدمة

1. أنشأنا مشروع WebApi للعميل.
2. كتبنا تهيئة لـ Nswag CLI - Nswag.json (الموضحة في القسم السابق).
3. كتبنا هدف PostBuild داخل مشروع مقدم خدمة csproj.

• $ (NSwagExe_Core22) تشغيل nswag.json - تشغيل الأداة المساعدة NSwag ضمن .bet runtine netCore 2.2 مع تكوين nswag.json

1. تقوم NSwag بإنشاء مواصفات من تجميع خدمة البائع.
2. تقوم NSwag بإنشاء رمز العميل وفقًا للمواصفات.

كيفية إضافة دعم لـ 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);
    }

استنتاج

• المواصفات مطولة ؛
• , ;
• ;
• .

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

إصدار العقود العامة

لماذا اصدار العقود العامة؟

خيارات الحل

بدون اصدار عقود عامة

استخدام إصدار العقود العامة

• أي أداة تستخدم ؛
• متى يتم تقديم إصدار جديد ؛
• كم من الوقت للحفاظ على الإصدارات القديمة.

الأداة التي تستخدم

متى يتم تقديم نسخة جديدة

• بالنسبة لـ OpenAPI ، هناك أداة Azure opeanapi-diff للتحقق من التوافق بين 2 من المواصفات github.com/Azure/openapi-diff ؛
• لم يتم العثور على أداة تلقائية لـ gRPC ، ولا توجد سوى سياسات للإصدار ؛
• github.com/grpc/grpc/blob/master/doc/versioning.md العامة ؛
• ضمن .Net docs.microsoft.com/en-us/aspnet/core/grpc/versioning؟view=aspnetcore-3.1 .

كم من الوقت للحفاظ على الإصدارات

• إبلاغ العملاء بأن الإصدار القديم لن يكون مدعومًا بعد الآن. في هذه الحالة ، قد نفقد دخل العميل ؛
• دعم المجموعة الكاملة من الإصدارات. تكلفة دعم البرمجيات آخذة في الازدياد ؛
• للإجابة على هذا السؤال ، عليك أن تسأل الشركة - هل يتجاوز الدخل من العملاء القدامى تكلفة دعم الإصدارات القديمة من البرنامج؟ هل يمكن أن يكون أكثر ربحية أن تطلب من العملاء الترقية؟

استنتاج

اختبار العقود و مراكز السيطرة على الأمراض

العقود الموجهة للمستهلكين (CDC)

1. يصف المستهلك العقد.
2. ينفذ المورد هذا العقد في المنزل.
3. يستخدم هذا العقد في عملية CI لدى المستهلك والمورد. إذا تم انتهاك العملية ، فقد توقف شخص عن الامتثال للعقد.

حلف

1. يكتب المستهلك الاختبارات باستخدام مكتبة PACT.
2. يتم تحويل هذه الاختبارات إلى ملف - قطعة أثرية. أنه يحتوي على معلومات حول العقود.
3. يستخدم الموفر والمستهلك ملف الاتفاقية لإجراء الاختبارات.

روابط مفيدة حول ميثاق

• وسيط Pact - حل إدارة ملفات pact docs.pact.io/pact_broker
• لا يدعم الميثاق GRPC بعد. اقرأ المزيد حول خارطة الطريق pact.canny.io .
• مزيد من المعلومات حول ميثاق docs.pact.io .
• لماذا يجب عليك استخدام PACT docs.pact.io/faq/convinceme

كيف يمكن تضمين CDC في CI

• نشر Pact + Pact broker بنفسك ؛
• شراء حل جاهز Pact Flow SaaS.

استنتاج