.NET Разработчик on Telegram: “День 2287. #ЗаметкиНаПолях 5 Основных Ошибок при…”

День 2287. #ЗаметкиНаПолях
5 Основных Ошибок при Создании API. Начало
Создание API кажется простым… пока не придётся их поддерживать. Прекрасные API рушились просто из-за мелких решений, принятых на раннем этапе, — вещей, которых вы даже не замечаете, пока API не окажется под давлением реального мира. Разберём 5 самых распространённых ошибок при создании API и как вы можете избежать попадания в эти ловушки.

1. Плохая или отсутствующая проверка ввода
Ошибка: Вера в то, что клиенты всегда будут отправлять допустимые данные.
Реальность: Если вы не проверяете ввод должным образом, API становится уязвимым для ошибок, сбоев и даже угроз безопасности.
Плохо:

app.MapPost("/users", async (UserDto user) =>
{
  // Подразумеваем, что имя и email
  // всегда предоставляются…
  var newUser = new User { 
   Name = user.Name,
   Email = user.Email };
  await db.Users.AddAsync(newUser);
  await db.SaveChangesAsync();
  return Results.Ok();
});

Замечание: не размещайте логику доступа к БД непосредственно в контроллерах (конечных точках).

Проблемы:
- Нет проверки на пустые поля.
- Нет проверки формата email.
- Не применяются бизнес-правила (например, минимальная/максимальная длина).

Лучше:

app.MapPost("/users", async (UserDto user) =>
{
  if (string.IsNullOrWhiteSpace(user.Name) || string.IsNullOrWhiteSpace(user.Email))
   return Results.BadRequest(
    "Имя и email обязательны.");

  if (!user.Email.Contains("@"))
   return Results.BadRequest(
    "Неверный формат email.");

  var newUser = new User { 
   Name = user.Name.Trim(),
   Email = user.Email.Trim() };
  …
});

Ещё лучше – используйте FluentValidation или собственный сервис валидации, чтобы избежать замусоривания ваших конечных точек.

Почему важно:
- Защищает целостность БД.
- Упрощает отладку на стороне клиента («BadRequest» вместо «ошибки 500»).
- Уберегает бэкенд от загадочных ошибок в будущем.

2. Отсутствие версионирования API
Ошибка: Выпуск API без версий, потому что «добавим позже».
Реальность: Нужно будет изменить API. И когда вы это сделаете, вы пожалеете, что не запланировали версионирование.
Плохо:

app.MapGet("/products", () =>
{
  // возврат продуктов
});

Проблема: Когда структура вашего ответа изменится, старые клиенты сломаются.

Лучше:

app.MapGroup("/api/v1")
 .MapGet("/products", () =>
 {
   // возврат продуктов версии 1
 });

app.MapGroup("/api/v2")
 .MapGet("/products", () =>
 {
   // возврат продуктов версии 2
 });

Или используйте .RequireHost() для разных поддоменов.

Почему важно:
- Вы можете развёртывать улучшения, не нарушая работу существующих клиентов.
- Даёт команде возможность постепенного отказа от старых клиентов.

Продолжение следует…

Источник: https://thecodeman.net/posts/building-apis-top-5-mistakes