hexarc pact

ميثاق السداسي

يوفر Hexarc Pact مجموعة أدوات لفضح واستهلاك واجهة برمجة تطبيقات الويب للمشاريع القائمة على .NET/TypeScript.

قم بتطوير مشروع API .NET Web الخاص بك مع PACT للحفاظ على مصدر واحد للحقيقة لبيانات تعريف API واستهلته عبر النظام الإيكولوجي .NET (الخدمات الصغيرة وسطح المكتب والجوال) أو على الويب عبر TypeScript.

طَرد	منصة	إصدار	التنزيلات
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	TypeScript

ماذا يوجد في الاتفاق؟

• سمات
• اكتب النظام
• قواعد شرح API
  • سمات إضافية
• API التجريبي
• كيفية استخدام
  • فضح مخطط واجهة برمجة تطبيقات PACT (.NET Web API Service)
  • تستهلك مخطط API PACT (.NET CLINE Application)
• شكر وتقدير
• رخصة

سمات

• تكاملات API خالية من المتاعب في ثوان.
• لا يوجد نوع معلومات فقدان. استهلك API الدقيق كما تم تصميمه.
• رمز أولا. لا حاجة لوصف بروتوكول API الخاص بك في IDL/DSL الخارجي.
• مشحونة بأنواع متقدمة. ليس فقط DTOs البسيطة ولكن التعدادات ، الأدوية ، النقابات الموسومة ، إلخ.

اكتب النظام

يعتمد نظام نوع المعدل على أنواع .NET CLR مع بعض الأنواع المخصصة لأفضل تجربة تطوير.

ما هو داخل نظام نوع الاتفاق:

• الأنواع البدائية (بما في ذلك Guid و DateTime )
• القيمة/نوع المرجع الدلالات
• المجموعات والبنادق (ليس فقط المصفوفات والقواميس البسيطة)
• الدعم الكامل لشروط التعليقات التوضيحية من النوع المرجعي (NRT)
• التعدادات (القائمة على الأوتار والقائمة على الأرقام)
• النقابات الموسومة (عبر hexarc.serialization.union)
• tuples (عبر hexarc.serialization.tuple)

قواعد شرح API

تم تصميم مخطط واجهة برمجة تطبيقات PACT للحصول على دلالي يشبه RPC. في القيام بذلك ، يجب أن يتبع واجهة برمجة التطبيقات المكشوفة هذه القواعد:

• يجب وضع علامة على وحدات التحكم في API مع سمات ApiController القياسية Route .
• يجب أن يكون لسمة المسار مسار سلسلة ثابتة فقط دون ترتيب (على سبيل المثال [Route("Entities")] ).
• يجب وضع علامة على أساليب API مع أحد أفعال HTTP المدعومة ( HttpGet أو HttpPost ). قد تحتوي سمات الفعل على مسار نقطة النهاية. البعض الآخر غير مدعوم في الوقت الحالي.
  • يمكن أن تحتوي طرق HttpGet على معلمات استعلام يجب ربطها عبر سمة FromQuery .
  • يجب أن تحتوي طرق HttpPost على معلمة واحدة فقط وهي هيئة الطلب.
• يمكن تحديد مسار طريقة API في سمة VERB HTTP أو سمة Route . إذا لم يتم تحديد مسار الطريقة في سمة VERB HTTP ، فسيتم أخذها من Route الأول أو سيتم رفع استثناء.

سمات إضافية

يوفر الاتفاق بعض السمات المفيدة لشرح API:

• يمكن تطبيق PactIgnoreAttribute على وحدات تحكم API أو طرق لاستبعادها من مخطط API.
• يمكن تطبيق PactScopeAttribute على وحدات تحكم API ليتم عزلها في نطاق محدد في مخطط API.

Demo API Server

يمكن العثور على خادم API التجريبي على https://hexarc-demo-api.herokuapp.com/.

يتم كشف مخطط API PACT على https://hexarc-demo-api.herokuapp.com/pact/schema.

لإنشاء عميل API استخدم التعليمات أدناه.

كيفية استخدام

تعرف على كيفية استخدام PACT لفضح واستهلاك واجهة برمجة تطبيقات الويب النموذجية.

فضح مخطط واجهة برمجة تطبيقات اتفاق

1. قم بتثبيت حزمة Hexarc.Pact.AspNetCore في مشروع .NET Web API:

dotnet add package Hexarc.Pact.AspNetCore

2. أضف توليد مخطط الاتفاقية في Startup.ConfigureServices طريقة:

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

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

3. قم بتمكين البرامج الوسيطة للمعدل في طريقة 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 وفقًا لقواعد التعليقات التوضيحية للائحة:

 [ 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 لضمان إنشاء مخطط واجهة برمجة تطبيقات PACT.

تستهلك مخطط واجهة برمجة تطبيقات اتفاق

1. قم بتثبيت حزمة Hexarc.Pact.Client في مشروع .NET:

dotnet add package Hexarc.Pact.Client

2. قم بتثبيت أداة Hexarc.Pact.Tool في المشروع:

dotnet tool install Hexarc.Pact.Tool

قد تحتاج إلى إعداد بيان .NET Tools قبل تثبيت أداة Hexarc.Pact.Tool :

dotnet new tool-manifest

3. إضافة تكوين pact.json في المشروع مع إعدادات توليد عميل API المطلوبة:

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

أين

• schemaUri - رابط إلى مخطط API اتفاق
• clientClassName - اسم لفئة عميل API التي تم إنشاؤها
• clientClassNamespace - مساحة الاسم حيث يتم وضعها في فئة عميل API التي تم إنشاؤها
• outputDirectory - دليل الإخراج للمصادر التي تم إنشاؤها

4. قم بإنشاء عميل API عبر أداة Pact CLI:

dotnet pact

يجب تنفيذ هذا الأمر في نفس المجلد مع تكوين pact.json .

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