MinimalHelpers

الحد الأدنى من مساعدي واجهات برمجة التطبيقات

مجموعة من مكتبات المساعدين لمشاريع API الحد الأدنى.

الحد الأدنى

مكتبة توفر مساعدين توجيه لأدنى مشاريع API لتسجيل نقاط النهاية التلقائية باستخدام الانعكاس.

تثبيت

المكتبة متوفرة على Nuget. ما عليك سوى البحث عن MinorDaLHelpers.Routing في واجهة المستخدم الرسومية لمدير الحزمة أو قم بتشغيل الأمر التالي في .NET CLI :

dotnet add package MinimalHelpers.Routing

الاستخدام

قم بإنشاء فصل للاحتفاظ بتسجيل معالجات الطريق وجعله ينفذ واجهة IEndpointRouteHandlerBuilder :

 public class PeopleEndpoints : MinimalHelpers . Routing . IEndpointRouteHandlerBuilder
{
    public static void MapEndpoints ( IEndpointRouteBuilder endpoints )
    {
        endpoints . MapGet ( "/api/people" , GetList ) ;
        endpoints . MapGet ( "/api/people/{id:guid}" , Get ) ;
        endpoints . MapPost ( "/api/people" , Insert ) ;
        endpoints . MapPut ( "/api/people/{id:guid}" , Update ) ;
        endpoints . MapDelete ( "/api/people/{id:guid}" , Delete ) ;
    }

    // ...
}

استدعاء طريقة ملحق MapEndpoints() على كائن WebApplication داخل البرنامج Run()

 // using MinimalHelpers.Routing;
app . MapEndpoints ( ) ;

app . Run ( ) ;

بشكل افتراضي ، ستقوم MapEndpoints() بمسح مجموعة الاتصال للبحث عن الفئات التي تنفذ واجهة IEndpointRouteHandlerBuilder . إذا تم تعريف معالجات الطريق في مجموعة أخرى ، فلديك بديلان:

• استخدم الحمل الزائد MapEndpoints() الذي يأخذ التجميع للمسح الضوئي كوسيطة
• استخدم طريقة تمديد MapEndpointsFromAssemblyContaining<T>() وحدد نوعًا موجودًا في التجميع الذي تريد مسحه

يمكنك أيضًا تحديد أنواع الأنواع (من بين الأنواع التي تنفذ واجهة IRouteEndpointHandlerBuilder ) التي تريدها بالفعل خريطة ، وتمرير مسند إلى طريقة MapEndpoints :

 app . MapEndpoints ( type =>
{
    if ( type . Name . StartsWith ( "Products" ) )
    {
        return false ;
    }

    return true ;
} ) ;

لاحظ أن هذه الطرق تعتمد على الانعكاس لمسح التجميع وإيجاد الفئات التي تنفذ واجهة IEndpointRouteHandlerBuilder . يمكن أن يكون لهذا تأثير الأداء ، وخاصة في المشاريع الكبيرة. إذا كان لديك مشكلات في الأداء ، ففكر في استخدام طريقة التسجيل الصريحة. علاوة على ذلك ، هذا الحل غير التوافق مع AOT الأصلي.

MinimalHelpers.Routing.Analyzers

مكتبة توفر مولد مصدر لتسجيل نقاط النهاية التلقائية في مشاريع API الحد الأدنى.

تثبيت

المكتبة متوفرة على Nuget. ما عليك سوى البحث عن MinorDaLHelpers.Routing في واجهة المستخدم الرسومية لمدير الحزمة أو قم بتشغيل الأمر التالي في .NET CLI :

dotnet add package MinimalHelpers.Routing.Analyzers

الاستخدام

قم بإنشاء فصل للاحتفاظ بتسجيل معالجات الطريق وجعله ينفذ واجهة IEndpointRouteHandlerBuilder :

 public class PeopleEndpoints : IEndpointRouteHandlerBuilder
{
    public static void MapEndpoints ( IEndpointRouteBuilder endpoints )
    {
        endpoints . MapGet ( "/api/people" , GetList ) ;
        endpoints . MapGet ( "/api/people/{id:guid}" , Get ) ;
        endpoints . MapPost ( "/api/people" , Insert ) ;
        endpoints . MapPut ( "/api/people/{id:guid}" , Update ) ;
        endpoints . MapDelete ( "/api/people/{id:guid}" , Delete ) ;
    }

    // ...
}

لاحظ أنك تحتاج فقط إلى استخدام حزمة MinimalHelpers.Routing.Analyzers . مع هذا المولد المصدر ، يتم إنشاء واجهة IEndpointRouteHandlerBuilder تلقائيًا.

استدعاء طريقة ملحق MapEndpoints() على كائن WebApplication داخل البرنامج Run()

 app . MapEndpoints ( ) ;

app . Run ( ) ;

ملاحظة يتم إنشاء طريقة MapEndpoints بواسطة مولد المصدر.

MinimalHelpers.Openapi

مكتبة توفر مساعدين OpenAPI لمشاريع API الحد الأدنى.

تثبيت

المكتبة متوفرة على Nuget. فقط ابحث عن MinimalHelpers.Openapi في GUINGER MANGERM GUI أو قم بتشغيل الأمر التالي في .NET CLI :

dotnet add package MinimalHelpers.OpenApi

الاستخدام

طرق التمديد لـ OpenAPI

توفر هذه المكتبة بعض أساليب الامتدادات التي تبسط تكوين OpenAPI في مشاريع الحد الأدنى من API. على سبيل المثال ، من الممكن تخصيص وصف الاستجابة باستخدام رمز الحالة الخاص به:

 endpoints . MapPost ( "login" , LoginAsync )
    . AllowAnonymous ( )
    . WithValidation < LoginRequest > ( )
    . Produces < LoginResponse > ( StatusCodes . Status200OK )
    . Produces < LoginResponse > ( StatusCodes . Status206PartialContent )
    . Produces ( StatusCodes . Status403Forbidden )
    . ProducesValidationProblem ( )
    . WithOpenApi ( operation =>
    {
        operation . Summary = "Performs the login of a user" ;

        operation . Response ( StatusCodes . Status200OK ) . Description = "Login successful" ;
        operation . Response ( StatusCodes . Status206PartialContent ) . Description = "The user is logged in, but the password has expired and must be changed" ;
        operation . Response ( StatusCodes . Status400BadRequest ) . Description = "Incorrect username and/or password" ;
        operation . Response ( StatusCodes . Status403Forbidden ) . Description = "The user was blocked due to too many failed logins" ;

        return operation ;
    } ) ;

طرق التمديد لـ RouteHandlerBuilder

غالبًا ما يكون لدينا نقاط نهائية مع قيم إرجاع 4xx متعددة ، كل منها ينتج استجابة ProblemDetails :

 endpoints . MapGet ( "/api/people/{id:guid}" , Get )
   . ProducesProblem ( StatusCodes . Status400BadRequest )
   . ProducesProblem ( StatusCodes . Status401Unauthorized )
   . ProducesProblem ( StatusCodes . Status403Forbidden )
   . ProducesProblem ( StatusCodes . Status404NotFound ) ;

لتجنب مكالمات متعددة لإنتاج ProducesProblem ، يمكننا استخدام طريقة تمديد ProducesDefaultProblem التي توفرها المكتبة:

 endpoints . MapGet ( "/api/people/{id:guid}" , Get )
   . ProducesDefaultProblem ( StatusCodes . Status400BadRequest , StatusCodes . Status401Unauthorized ,
       StatusCodes . Status403Forbidden , StatusCodes . Status404NotFound ) ; 

MinimalHelpers.validation

مكتبة توفر مرشح نقطة النهاية لأدنى مشاريع API لإجراء التحقق من الصحة مع تعليقات البيانات ، باستخدام مكتبة Minivalidation.

تثبيت

المكتبة متوفرة على Nuget. فقط ابحث عن MinimalHelpers.validation في واجهة المستخدم الرسومية لمدير الحزمة أو قم بتشغيل الأمر التالي في .NET CLI :

dotnet add package MinimalHelpers.Validation

الاستخدام

يزين فئة بسمات لتحديد قواعد التحقق من الصحة:

 using System . ComponentModel . DataAnnotations ;

public class Person
{
    [ Required ]
    [ MaxLength ( 20 ) ]
    public string ? FirstName { get ; set ; }

    [ Required ]
    [ MaxLength ( 20 ) ]
    public string ? LastName { get ; set ; }

    [ MaxLength ( 50 ) ]
    public string ? City { get ; set ; }
}

أضف طريقة التمديد WithValidation<T>() التثبيت لتمكين مرشح التحقق من الصحة:

 using MinimalHelpers . Validation ;

app . MapPost ( "/api/people" , ( Person person ) =>
    {
        // ...
    } )
    . WithValidation < Person > ( ) ;

إذا فشل التحقق من الصحة ، فستكون الاستجابة 400 Bad Request مع كائن ValidationProblemDetails الذي يحتوي على أخطاء التحقق من الصحة ، على سبيل المثال:

{
  "type" : " https://tools.ietf.org/html/rfc9110#section-15.5.1 " ,
  "title" : " One or more validation errors occurred " ,
  "status" : 400 ,
  "instance" : " /api/people " ,
  "traceId" : " 00-009c0162ba678cae2ee391815dbbb59d-0a3a5b0c16d053e6-00 " ,
  "errors" : {
    "FirstName" : [
      " The field FirstName must be a string or array type with a maximum length of '20'. "
    ],
    "LastName" : [
      " The LastName field is required. "
    ]
  }
}

إذا كنت ترغب في تخصيص التحقق من الصحة ، يمكنك استخدام طريقة تمديد ConfigureValidation :

 using MinimalHelpers . Validation ;

builder . Services . ConfigureValidation ( options =>
{
    // If you want to get errors as a list instead of a dictionary.
    options . ErrorResponseFormat = ErrorResponseFormat . List ;

    // The default is "One or more validation errors occurred"
    options . ValidationErrorTitleMessageFactory =
        ( context , errors ) => $ "There was { errors . Values . Sum ( v => v . Length ) } error(s)" ;
} ) ;

يمكنك استخدام ValidationErrorTitleMessageFactory ، على سبيل المثال ، إذا كنت ترغب في ترجمة خاصية title للاستجابة باستخدام ملف Resx.

MinimalHelpers.FluentValidation

مكتبة توفر مرشح نقطة النهاية لأدنى مشاريع API لإجراء التحقق من الصحة باستخدام FluentValidation.

تثبيت

المكتبة متوفرة على Nuget. ما عليك سوى البحث عن MinimalHelpers.fluentValidation في Gui Manager GUI أو قم بتشغيل الأمر التالي في .NET CLI :

dotnet add package MinimalHelpers.FluentValidation

الاستخدام

قم بإنشاء فصل يمتد AbstractValidator ويحدد قواعد التحقق من الصحة:

 using FluentValidation ;

public record class Product ( string Name , string Description , double UnitPrice ) ;

public class ProductValidator : AbstractValidator < Product >
{
    public ProductValidator ( )
    {
        RuleFor ( p => p . Name ) . NotEmpty ( ) . MaximumLength ( 50 ) . EmailAddress ( ) ;
        RuleFor ( p => p . Description ) . MaximumLength ( 500 ) ;
        RuleFor ( p => p . UnitPrice ) . GreaterThan ( 0 ) ;
    }
}

تسجيل المدققات في مجموعة الخدمة:

 using FluentValidation ;

// Assuming the validators are in the same assembly as the Program class
builder . Services . AddValidatorsFromAssemblyContaining < Program > ( ) ;

أضف طريقة التمديد WithValidation<T>() التثبيت لتمكين مرشح التحقق من الصحة:

 using MinimalHelpers . FluentValidation ;

app . MapPost ( "/api/products" , ( Product product ) =>
    {
        // ...
    } )
    . WithValidation < Product > ( ) ;

إذا فشل التحقق من الصحة ، فستكون الاستجابة 400 Bad Request مع كائن ValidationProblemDetails الذي يحتوي على أخطاء التحقق من الصحة ، على سبيل المثال:

{
  "type" : " https://tools.ietf.org/html/rfc9110#section-15.5.1 " ,
  "title" : " One or more validation errors occurred " ,
  "status" : 400 ,
  "instance" : " /api/products " ,
  "traceId" : " 00-f4ced0ae470424dd04cbcebe5f232dc5-bbdcc59f310ebfb8-00 " ,
  "errors" : {
    "Name" : [
      " 'Name' cannot be empty. "
    ],
    "UnitPrice" : [
      " 'Unit Price' must be grater than '0'. "
    ]
  }
}

إذا كنت ترغب في تخصيص التحقق من الصحة ، يمكنك استخدام طريقة تمديد ConfigureValidation :

 using MinimalHelpers . Validation ;

builder . Services . ConfigureValidation ( options =>
{
    // If you want to get errors as a list instead of a dictionary.
    options . ErrorResponseFormat = ErrorResponseFormat . List ;

    // The default is "One or more validation errors occurred"
    options . ValidationErrorTitleMessageFactory =
        ( context , errors ) => $ "There was { errors . Values . Sum ( v => v . Length ) } error(s)" ;
} ) ;

يمكنك استخدام ValidationErrorTitleMessageFactory ، على سبيل المثال ، إذا كنت ترغب في ترجمة خاصية title للاستجابة باستخدام ملف Resx.

يساهم

المشروع يتطور باستمرار. المساهمات موضع ترحيب. لا تتردد في تقديم المشكلات وسحب الطلبات على الريبو وسنخاطبها قدر الإمكان.