Skip to content

[Feature] Унификация обработки исключений #17

@soorq

Description

@soorq
  1. Контекст
    На текущий момент API возвращает ошибки в разных форматах (стандартные NestJS ошибки, ошибки Zod, системные падения). Это усложняет обработку ошибок на фронтенде. Необходимо внедрить глобальный фильтр для приведения всех исключений к единому стандарту.

  2. Требования
    Необходимо создать GlobalExceptionFilter, который будет перехватывать все исключения и возвращать ответ в следующем формате:

{
  "error": {
    "code": "TEAM_INVITE_ALREADY_EXISTS",
    "message": "Пользователь уже приглашен в эту команду",
    "target": "email",
    "retryable": false,
    "details": [
      {
        "code": "unique_violation",
        "message": "Приглашение для user@example.com активно до 15.04.2026",
        "path": ["email"]
      }
    ]
  },
  "meta": {
    "requestId": "clv123abc0000p9",
    "timestamp": "2026-04-14T15:55:00Z",
    "path": "/api/v1/teams/lab/invitations",
    "method": "POST"
  }
}
  1. Что нужно сделать:
    Стандартизация кодов: Реализовать маппинг HttpException в строковые коды (например, 404 -> NOT_FOUND, 403 -> FORBIDDEN).

Интеграция с Zod: Обработать ZodValidationException, вытаскивая массив ошибок в поле details.

RequestId: Использовать x-request-id из заголовков или генерировать новый через cuid2 для обеспечения прослеживаемости (traceability).

Безопасность (Production): Скрывать детальные сообщения о системных ошибках (500) в production-окружении, заменяя их на "An unexpected error occurred".

Логирование: * Ошибки 5xx логировать через Logger.error с полным стек-трейсом.

Ошибки 4xx логировать через Logger.warn.

Retry Logic: Поле retryable должно быть true только для серверных ошибок (status >= 500).

  1. Критерии приемки:
    [ ] Все ошибки в приложении возвращаются в новом формате.
    [ ] Ошибки валидации (Zod) содержат массив конкретных нарушений в details.
    [ ] В каждом ответе присутствует уникальный requestId.
    [ ] Логи в консоли/файле содержат ID запроса для корреляции.
    [ ] Фильтр зарегистрирован глобально в main.ts.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Type

No fields configured for Task.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions