азработка API

Minimal APIs

Lino использует стиль Minimal API по умолчанию для генерации эндпоинтов, с приоритетом на:

• Ясность – компактный, прямой и выразительный код.
• Производительность – оптимизированные ответы без лишних накладных расходов.

Встроенные возможности

TypedResults: обеспечивают строго типизированные ответы, помогая с читаемостью и генерацией OpenAPI.

Версионирование API: эндпоинты могут развиваться без нарушения совместимости.

Расширенная документация: настраиваемые метаданные напрямую включаются в OpenAPI, включая:

• WithTags → группирует эндпоинты в логические разделы в OpenAPI.
• WithName → определяет operationId последовательно.
• WithSummary → чётко описывает назначение эндпоинта.
• Produces(statusCode, schema) → задаёт коды статуса и контракты ответа.
• MapToApiVersion → позволяет публиковать разные версии одного и того же эндпоинта.

Requests и Responses

Record classes используются по умолчанию для Requests и Responses:

• Они неизменяемы (уменьшая побочные эффекты и ошибки).
• Краткие и легко читаемые.

Интеграция с CQRS:

• Запросы, полученные через эндпоинты, преобразуются в Commands или Queries.
• Результаты Commands/Queries конвертируются в Responses, обеспечивая архитектурную согласованность.

Упрощённый пример:
public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

Создание новых API

Создать endpoint с помощью CLI Lino очень просто:

lino new api

Интерактивный мастер запросит:

• Сервис – сервис, в котором будет создан API.
• Модуль – модуль сервиса (если применимо).
• Сущность – сущность, связанная с endpoint.
• Имя API – обычно соответствует глаголу операции (например: CreatePerson).
• Тип операции – POST, PUT, PATCH, DELETE или GET.
• Маршрут – шаблон маршрута (например: /people/{id}).

Пример:

При создании POST API с именем CreatePerson, связанным с сущностью Person, CLI автоматически сгенерирует:

• Endpoint с HTTP-мэппингом.
• Request/Response DTO.
• Расширения для интеграции с OpenAPI и версионирования.
• Типизированный HttpClient для внутреннего использования другими сервисами.

Сгенерированная структура:

MyApp/
└── src/
    ├── Services/
    │   └── MyService/
    │       └── Presentation.API/
    │           ├── MyApp.MyService.Presentation.API.csproj
    │           └── Endpoints/
    │               └── People/
    │                   └── CreatePerson/
    │                       ├── CreatePersonEndpoint.cs
    │                       ├── CreatePersonExtensions.cs
    │                       ├── CreatePersonRequest.cs
    │                       └── CreatePersonResponse.cs
    └── Integrations/
        └── MyService/
            └── Http/
                ├── Contracts/
                │   └── Apis/
                │       └── People/
                │           ├── IPersonHttpClient.cs
                │           └── CreatePerson/
                │               ├── CreatePersonRequest.cs
                │               └── CreatePersonResponse.cs
                └── Clients/
                    └── Apis/
                        └── PersonHttpClient.cs

Регистрация Endpoints с помощью Source Generators

Lino устраняет необходимость в ручном маппинге эндпоинтов или интенсивном использовании Reflection во время выполнения.
Вместо этого используются Source Generators для автоматической генерации кода регистрации во время компиляции.

Как это работает

Для каждого созданного эндпоинта генератор создаёт классы/частичные классы, которые вызывают:
MapGet, MapPost, MapPut, MapDelete и т.д.

Это заменяет необходимость вручную добавлять все маппинги в Program.cs.

Преимущества:

• Регистрация во время компиляции → предотвращает ошибки времени выполнения.
• Компактный Program.cs → меньшая поверхность ручной конфигурации.
• AOT-совместимость → устраняет зависимость от Reflection.
• Встроенная документация → метаданные (tags, summary, produces) генерируются вместе с маппингом.

Эта модель гарантирует, что API, созданные в Lino, будут:

• Автодокументированы
• Производительны
• Соответствовать архитектуре CQRS фреймворка