Скачать MinimalHelpers - Загрузка исходного кода MinimalHelpers

Минимальные помощники APIS

Коллекция библиотек помощников для минимальных проектов API.

Минималпелперс.

Библиотека, которая предоставляет помощниками по маршрутизации для минимальных проектов API для автоматической регистрации конечных точек с использованием отражения.

Установка

Библиотека доступна на Nuget. Просто найдите MinimalHelpers.Routing в графическом интерфейсе диспетчера пакетов или запустите следующую команду в CLI .NET :

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 Inside Program.cs перед методом 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.

Установка

dotnet add package MinimalHelpers.Routing.Analyzers

Использование

 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 Inside Program.cs перед методом Run() .

 app . MapEndpoints ( ) ;

app . Run ( ) ;

Примечание. Метод MapEndpoints генерируется генератором источника.

Minimalhelpers.openapi

Библиотека, которая предоставляет помощникам OpenAPI для минимальных проектов API.

Установка

Библиотека доступна на Nuget. Просто найдите MinimalHelpers.openapi в графическом интерфейсе менеджера пакетов или запустите следующую команду в CLI .NET :

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 ) ;

Минималпелперс. Validation

Библиотека, которая предоставляет фильтр конечной точки для минимальных проектов API для выполнения проверки с аннотациями данных, используя библиотеку Minivalidation.

Установка

Библиотека доступна на Nuget. Просто найдите MinimalHelpers.validation в графическом интерфейсе менеджера пакетов или запустите следующую команду в CLI .NET :

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.

Минималпелперс.fluentvalidation

Библиотека, которая предоставляет фильтр конечной точки для минимальных проектов API для выполнения проверки с использованием FluentValidation.

Установка

Библиотека доступна на Nuget. Просто найдите MinimalHelpers.fluentValidation в графическом интерфейсе менеджера пакетов или запустите следующую команду в CLI .NET :

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 > ( ) ;

{
  "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)" ;
} ) ;