-
Контекст
На текущий момент API возвращает ошибки в разных форматах (стандартные NestJS ошибки, ошибки Zod, системные падения). Это усложняет обработку ошибок на фронтенде. Необходимо внедрить глобальный фильтр для приведения всех исключений к единому стандарту.
-
Требования
Необходимо создать 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"
}
}
- Что нужно сделать:
Стандартизация кодов: Реализовать маппинг 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).
- Критерии приемки:
[ ] Все ошибки в приложении возвращаются в новом формате.
[ ] Ошибки валидации (Zod) содержат массив конкретных нарушений в details.
[ ] В каждом ответе присутствует уникальный requestId.
[ ] Логи в консоли/файле содержат ID запроса для корреляции.
[ ] Фильтр зарегистрирован глобально в main.ts.
Контекст
На текущий момент API возвращает ошибки в разных форматах (стандартные NestJS ошибки, ошибки Zod, системные падения). Это усложняет обработку ошибок на фронтенде. Необходимо внедрить глобальный фильтр для приведения всех исключений к единому стандарту.
Требования
Необходимо создать 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" } }Стандартизация кодов: Реализовать маппинг 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).
[ ] Все ошибки в приложении возвращаются в новом формате.
[ ] Ошибки валидации (Zod) содержат массив конкретных нарушений в details.
[ ] В каждом ответе присутствует уникальный requestId.
[ ] Логи в консоли/файле содержат ID запроса для корреляции.
[ ] Фильтр зарегистрирован глобально в main.ts.