Mds.Libraries.CSharp.Api

Пакет для работы с api и Mds протоколом.

Mds протокол

Пакет позволяет подключить Mds протокол. Протокол позволяет без особых трудозатрат возвращать расширенную информацию по ошибкам, обрабатывать искочения и т.п.

Подключение

Для подкулючения необходимо использовать метод AddMdsApiProtocol(options) + UseMdsApiProtocol. В options указывается DefaultStrategy - стратегия использовния (Mds/Default). Дополнительно указываются массивы ApplyUrls и IgnoreUrls, в которых указываются regexp маски урлов, которые необходимо исключить либо принудительно добавить в обработку.

Options можно не указвать, тогда все будет подключено как Mds с пустыми массивами разрешенных/игнорируемых уролов.

Пример использования

Подключение в конфигурации IServiceCollection

private static void AddMdsProtocol(this IServiceCollection services)
{
    services.AddMdsApiProtocol(options =>
    {
        options.IgnoreUrls = new[] {
            "/health/*",
            "/metrics/*"
        };
    });
}

Подключение в IApplicationBuilder

internal static void UseApi(this IApplicationBuilder app)
{
    app.UseRouting();

    app.UseMdsApiProtocol();

    // ...

    app.UseEndpoints();
}

Фильтры

Фильтр CustomContentType(string).

С помошью аттрибута CustomContentType можно принудительно указать определенный Content-Type для ответа метода контроллера. Аттрибут работает только на ответы c 2хх кодами.

Пример подключения:

internal static IServiceCollection AddFilters(this IServiceCollection services)
{
    //...

    services.AddCustomContentTypeFilter();

    //...

    return services;
}

Пример использования:

[CustomContentType("application/xml")]
public ActionResult GetActualBySlug(string locationSlug)
{
    /// ...
}

Фильтр ValidateFluently<>().

С помошью аттрибута ValidateFluently<> можно указать параметр с каким типо надо провалидировать через FluentValidation. Подразумевается наличие IValidator<T> для указанного типа в DI.

Пример подключения:

internal static IServiceCollection AddFilters(this IServiceCollection services)
{
    //...

    services.AddGenericFluentValidationFilter();

    //...

    return services;
}

Пример использования:

[HttpPost("api_285/admin/feeds/yandex/mobile")]
[ValidateFluently<CommitFeedRequest>]
public async Task<ActionResult<JToken>> CommitYandexMobileFeedAsync([FromBody] CommitFeedRequest request)
{
    //...
}

LogicError, LogicErrorsSet и ResultAccessor

У нас есть механизм, чтобы иметь возможность возвращать больше одной ошибки из метода и работать НЕ через Exception.

LogicError

Это контейнер для ошибок. Он изначально затачивался под Api, но его можно использовать для проблем внутри системы.

Он содержит числовой код, строковый код и описание. Желательно заполнять все поля, чтобы в разных частях системы можно было корректно отслеживать ошибки. В коде лучше ориентироваться на код и строковый код. Описание для разработчика или исследования проблемы.

Пример использования

Хранение карты ошибок

public static class Auth
{
    public static LogicError ReachVerificationsLimit { get; } = new (100, "LIMIT_IS_REACHED", "Limit of verifications is reached.");
}

Возврат успешного кода

private LogicError DoMagic()
{
    // ...
    return LogicError.Ok;
}

LogicErrorsSet

Для хранения нескольких LogicError используется LogicErrorsSet. Его задача объединять несколько ошибок.

Удобно использовать, когда ваш метод может вернуть несколько ошибок.

У него есть автоматическое приведение для следующих типов:

• LogicError - можно вернуть из метода одну ошибку, этого будет достаточно.
• LogicError[] - можно вернуть из метода набор ошибок от ResultAccessor.Errors

Такая возможность нужна, чтобы можно было делать код методов чище.

Пример использования

private async Task<LogicErrorsSet> DoAndSaveMagicAsync(CancellationToken cancellationToken)
{
    var accessor1 = await _service1.DoMagicAsync(cancellationToken);
    if (accessor1.HasErrors)
    {
        return accessor1.Errors;
    }

    var accessor2 = await _service2.DoMagicAsync(accessor1.Data, cancellationToken);
    if (accessor2.HasErrors)
    {
        return accessor2.Errors;
    }

    await SaveMagicAsync(accessor2.Data, cancellationToken);

    return LogicErrorsSet.Ok;
}

ResultAccessor

Очень часто надо вернуть из сервиса данные или ошибку в ином случае. Чтобы меньше иметь проблем с исключениями.

Для таких сценариев используется ResultAccessor<TResultData>. Он позволяет относительно удобно вернуть результат работы методы или сообщить об ошибках, которые произошли. Своей структурой очень напоминает LogicErrorsSet, но содержит результат работы (Data).

Пример использования

Создавать можно напрямую:

var accessor = new ResultAccessor<string>("John");

Или:

var accessor = new ResultAccessor<string>(LogicErrorsSet.Ok);

Основной пример использования:

ResultAccessor<int> Parse(HttpResponse response)
{
    if (TryParse(response, out var result) is false)
    {
        return new(new LogicError(-1, message: "Problem with parsing."));
    }

    return new(result);
}