азработка 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

Создание эндпоинта с помощью CLI Lino выполняется просто:

lino new api

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

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

Пример:

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

• Эндпоинт с HTTP-мэппингом.
• DTO Request/Response.
• Расширения для интеграции с OpenAPI и версионированием.

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

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Api/
                └── MyApp.MyService.Api.csproj
                    └── Endpoints/
                        └── People/
                            └── CreatePerson/
                                ├── CreatePersonEndpoint.cs
                                ├── CreatePersonExtensions.cs
                                ├── CreatePersonRequest.cs
                                └── CreatePersonResponse.cs

В проектах с добавленными веб-приложениями Blazor Lino автоматически генерирует артефакты, необходимые для потребления API.
Это включает общие контракты (Request и Response/DTO), интерфейс клиента и стандартную реализацию HTTP-вызовов, позволяя Blazor использовать API простым, типобезопасным и согласованным образом.

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Api/
                ├── MyApp.MyService.Api.Contracts.csproj
                │   └── Features/
                │       └── People/
                │           ├── CreatePerson/
                │           │   ├── CreatePersonRequest.cs
                │           │   └── CreatePersonResponse.cs
                │           └── IPersonApiClient.cs
                └── MyApp.MyService.Api.Client.csproj
                    └── Features/
                        └── PersonApiClient.cs

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

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

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

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

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

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

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

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

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