Что нужно возвращать клиенту при неверной валидации запроса?

Ответ на вопрос: Что возвращать клиенту при неверной валидации запроса?

При обработке невалидных запросов в C# Backend API ключевой принцип — возвращать клиенту четкую, структурированную и машиночитаемую информацию об ошибках, чтобы фронтенд или другой клиент мог корректно обработать ситуацию и, возможно, исправить данные. Основные аспекты ответа: HTTP статус код, структура тела ответа и консистентность во всем API.

1. HTTP статус код

Согласно стандартам REST API и рекомендациям HTTP/1.1, для ошибок валидации данных запроса используется статус 422 Unprocessable Entity (RFC 4918) или 400 Bad Request. В современных API предпочтительнее 422, так как он явно указывает, что сервер понял запрос, но не может обработать из-за семантических ошибок в данных (например, неверный формат email, превышение длины строки). 400 — более общий код для некорректного синтаксиса запроса. Важно не использовать 200 OK с ошибкой в теле — это противоречит семантике HTTP.

2. Структура тела ответа

Тело ответа должно содержать машиночитаемый формат (обычно JSON) с детализацией ошибок. Рекомендуемая структура включает:

• Общее сообщение (краткое описание).
• Список ошибок по полям (field-by-field errors), если ошибки связаны с конкретными свойствами модели.
• Код ошибки (опционально) для внутренней классификации.
• Timestamp (опционально) для диагностики.

Пример структуры в JSON:

{
  "type": "https://example.com/errors/validation-failed",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more validation errors occurred.",
  "errors": {
    "Email": [
      "The Email field is not a valid e-mail address."
    ],
    "Age": [
      "The field Age must be between 18 and 99."
    ]
  }
}

Эта структура соответствует Problem Details for HTTP APIs (RFC 7807) — стандарту для описания ошибок.

3. Реализация в ASP.NET Core

В ASP.NET Core встроена поддержка валидации через Data Annotations, FluentValidation или валидацию моделей. При автоматической обработке (с ApiController атрибутом) фреймворк возвращает 400 Bad Request со структурой типа ValidationProblemDetails. Однако для 422 нужно настроить поведение.

Пример контроллера с кастомной обработкой:

[ApiController]
[Route("api/users")]
public class UsersController : ControllerBase
{
    [HttpPost]
    public IActionResult CreateUser([FromBody] UserDto user)
    {
        if (!ModelState.IsValid)
        {
            // Возвращаем 422 с детализацией ошибок
            return UnprocessableEntity(ModelState);
        }
        // Логика обработки...
        return Ok();
    }
}

Для глобальной настройки можно использовать фильтры или middleware:

// В Program.cs или Startup.cs
builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.InvalidModelStateResponseFactory = context =>
        {
            var problemDetails = new ValidationProblemDetails(context.ModelState)
            {
                Type = "https://tools.ietf.org/html/rfc7231#section-6.5.1",
                Title = "Validation Error",
                Status = StatusCodes.Status422UnprocessableEntity,
                Detail = "See the errors property for details.",
                Instance = context.HttpContext.Request.Path
            };
            return new UnprocessableEntityObjectResult(problemDetails)
            {
                ContentTypes = { "application/problem+json" }
            };
        };
    });

4. Дополнительные рекомендации

• Логирование: Все ошибки валидации следует логировать (например, через ILogger) для анализа, но не включать внутренние детали (стек-трейс, пути файлов) в ответ клиенту — это угроза безопасности.
• Консистентность: Все эндпоинты API должны возвращать ошибки валидации в едином формате.
• Язык и локализация: Сообщения об ошибках можно адаптировать под язык клиента (через ресурсы или локализацию), но в машиночитаемой части лучше использовать коды ошибок.
• Документация: Формат ответа с ошибками должен быть описан в документации API (Swagger/OpenAPI). В ASP.NET Core можно настроить через Swashbuckle:

// Добавление примера ошибки в Swagger
builder.Services.AddSwaggerGen(c =>
{
    c.SchemaFilter<ValidationProblemDetailsSchemaFilter>();
});

5. Что не следует делать

• Возвращать 200 OK с флагом ошибки — это усложняет обработку на клиенте.
• Возвращать HTML или простой текст — клиент может ожидать JSON/XML.
• Показывать сырые исключения или системную информацию.
• Игнорировать валидацию на стороне сервера, даже если она есть на фронтенде — это важно для безопасности и целостности данных.

Итог: Возвращайте 422 Unprocessable Entity (или 400) с структурированным JSON-объектом, содержащим детали ошибок по полям, в формате, близком к RFC 7807. Это обеспечивает удобство отладки для разработчиков, простую интеграцию для клиентов и соответствие лучшим практикам REST API.