День 2289. #ЗаметкиНаПолях
5 Основных Ошибок при Создании API. Окончание
Начало
Продолжение

5. Отсутствие централизованной обработки ошибок
Ошибка: Хаотичное использование блоков try-catch по всему коду или, что ещё хуже оставление исключений необработанными.
Реальность: Нужно одно место для аккуратной обработки непредвиденных ошибок.
Плохо:

try
{
  var user = await db.Users.FindAsync(id);
  return Results.Ok(user);
}
catch (Exception ex)
{
  return Results.Problem(ex.Message);
}

Проблемы:
- Дублирование кода.
- Несогласованные ответы с ошибками.
- Трудности с правильным логированием.

Лучше (использование промежуточного ПО обработки ошибок):

app.UseExceptionHandler(app =>
{
  app.Run(async ctx =>
  {
    ctx.Response.StatusCode = 500;
    ctx.Response.ContentType = "application/json";
    await ctx.Response.WriteAsJsonAsync(new
    {
      Error = "Что-то пошло не так."
    });
  });
});

Ещё лучше – использование ProblemDetails (application/problem+json) в .NET 9 автоматически через ответ Problem().

Почему важно:
- Более чистый код.
- Стандартные сообщения об ошибках для всех клиентов.
- Простота подключения логирования (Serilog, OpenTelemetry, и т.п.).

Кроме того:
Не рекомендуется использовать исключения в качестве основного способа обработки ошибок. Вместо этого, если вы создаёте новые API сегодня, рассмотрите шаблон Result (например, Result, OneOf и т.д.). Так вы явно возвращаете результаты успеха/неудачи, вообще не полагаясь на исключения. Исключения должны использоваться для действительно неожиданных случаев, а не для обычных ошибок проверки. Тем не менее, если ваш проект (или ваша команда) уже использует исключения, лучшим решением будет централизовать их обработку.

Вот простая обработка ошибок в стиле Result:

public record Result<T>(
 bool IsSuccess,
 T? Value,
 string? ErrorMessage
);

app.MapGet("/users/{id}", 
 async (Guid id, DbContext db) =>
 {
  var user = await db.Users.FindAsync(id);
  if (user is null)
    return Results.NotFound(
     new Result<User>(
      false,
      null,
      "Пользователь не найден"));

  return Results.Ok(
   new Result<User>(true, user, null));
});

Итого
API — это не просто «передача данных туда и обратно».
API — это контракты.
API — это обещания.
Когда вы создаёте API с хорошей проверкой входных данных, управлением версиями, обработкой ошибок и продуманными ответами — вы даёте обещание своим клиентам (и себе в будущем), что ваша система будет надёжной и предсказуемой. Даже небольшие улучшения в API сейчас могут сэкономить десятки часов позже.

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