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

Аттрибут ContentType(string).

С помошью аттрибута ContentType(string) можно принудительно указать определенный Content-Type для ответа метода контроллера. Аттрибут работает только на ответы со Status Code 2хх.

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

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

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