Статические классы Results и TypedResults в ASP.NET Core. Отправка кодов состояния HTTP 4xx

Отправка кодов состояния HTTP 4xx свидетельствует о том, что произошла ошибка на стороне клиента — ресурс не найден, пользователь не авторизован и т.д. В статических классах Results и TypedResults предусмотрен ряд методов, отправляющих клиенту наиболее распространенные коды статуса HTTP группы 4xx.

Метод BadRequest() класса Results

Этот метод отправляет клинту код статуса 400 Bad Request, который, обычно, говорит о том, что в запросе клиента допущена синтаксическая ошибка.

public static IResult BadRequest (object? error = default);

public static IResult BadRequest<TValue> (TValue? error);

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

app.MapGet("/age/{age}", (int age) =>
{
    if (age < 18)
        return Results.BadRequest(new { ErrorCode = 1001, Text = $"Вам {age} лет. Доступ запрещен" });
    else
        return Results.Content("Добро пожаловать");
});

в данном случае, если в параметрах маршрута будет задано число меньше 18, то сервер вернет код статуса 400

Метод Conflict() класса Results

Метод отправляет клиенту код статуса 409 Conflict, указывающий, что запрос не может быть выполнен из-за конфликтного обращения к ресурсу, например, если сразу два клиента пытаются изменить запись в БД.

public static IResult Conflict (object? error = default);

public static IResult Conflict<TValue> (TValue? error);

Как и предыдущий метод, Conflict() может принимать в качестве параметра некий объект, содержащий описание проблемы, который будет сериализирован в JSON и отправлен в теле ответа. При этом, объект error можно не указывать.

app.MapGet("/conflict", ()=>Results.Conflict());

Метод Forbid() класса Results

Этот метод отправляет клиенту код статуса 403 Forbidden, сообщающий о том, что пользователь не уполномочен выполнять этот запрос, например, из-за отсутствия авторизации или других ограничений.

public static IResult Forbid (AuthenticationProperties? properties = default, IList<string>? authenticationSchemes = default);

Использование этого метода мы пока отложим, так как на данный момент мы не разбирали вопросов, связанных с авторизацией, а работа этого метода напрямую связана с сервисом авторизации.

Метод NotFound() класса Results

Этот метод возвращает самую распространенный код статуса HTTP — 404 Not Found, который сообщает нам о том, что запрошенный ресурс не найден.

public static IResult NotFound (object? value = default);

public static IResult NotFound<TValue> (TValue? value);

например:

app.MapGet("/resource", () => Results.NotFound(new { ErrorCode = 1002, Details = "Resource not found"}));

Метод Unauthorized() класса Results

Этот метод отправляет клиенту код статуса 401 Unauthorized, который сообщает о том, что пользователь не уполномочен выполнять действия с ресурсом так как он не авторизован.

public static IResult Unauthorized ();

Этот метод не принимает никаких параметров. Пример использования

app.MapGet("/resource", (string token)=>
{
    if (token != "asdf")
        return Results.Unauthorized();
    else
        return Results.Ok();
});

Метод UnprocessableEntity() класса Results

Этот метод возвращает клиенту код статуса 422 Unprocessable Entity, сообщающий, что сервер успешно принял запрос и может работать с указанным видом данных, однако имеется какая-то логическая ошибка, из-за которой невозможно произвести операцию над ресурсом.

public static IResult UnprocessableEntity (object? error = default);

public static IResult UnprocessableEntity<TValue> (TValue? error);

Например,

app.MapGet("/resource/{path_token}", (string token, string path_token) =>
{
    if (token != path_token)
        return Results.UnprocessableEntity(new { message="Токены в пути и параметре не совпадают"});
    else
        return Results.Ok();
});

Метод ValidationProblem() класса Results

Этот метод, как и BadRequest возвращает клиенту код статуса 400, но, при этом, включает в тело ответа специальный объект в формате JSON — ProblemDetails

public static IResult ValidationProblem (IDictionary<string,string[]> errors, string? detail = default, string? instance = default, int? statusCode = default, string? title = default, string? type = default, IDictionary<string,object?>? extensions = default);

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

app.MapGet("/resource/{path_token}", (string token, string path_token) =>
{
    if (token != path_token)
    {
        Dictionary<string, string[]> errors = new();
        errors.Add("1", new[] { "Ошибка валидации объекта" });

        return Results.ValidationProblem(errors, //словарь с ошибками
                                         "Во время валидции модели мы обнаружили ошибку", //подробное описание 
                                         null, 
                                         400, //код статуса
                                         "Кратко об ошибка");
    }
    else
        return Results.Ok();
});

Как и метод StatusCode, который мы уже рассматривали, метод ValidationProblem может возвращать любой код статуса HTTP, например, выше мы использовали код 400, хотя могли использовать и любой другой.

Методы BadRequest(), Conflict(), Forbid(), NotFound(), Unauthorized(), UnprocessableEntity() и ValidationProblem() класса TypedResults

Методы BadRequest(), Conflict(), Forbid(), NotFound(), Unauthorized(), UnprocessableEntity() и ValidationProblem() класса TypedResults  выполняют те же самые операции, что и в классе Results и, при этом, возвращают следующие типизированные результаты:

Итого

Статические классы Results и TypedResults предоставляют сразу ряд методов, отправляющих коды состояния HTTP группы 4хх, сообщающих нам о том, что на стороне клиента произошла какая-либо ошибка. При этом, работа метода Forbid() напрямую зависит от настроек сервиса авторизации.