3.9 KiB
HTTP API и ошибки
Источник контракта
Nest controllers/DTO/Swagger metadata генерируют runtime OpenAPI. Настройка
приложения — configureApp; frontend хранит derived
snapshot и generated TS. Изменения проходят
contract workflow.
API имеет prefix /api/v1; Swagger публикуется для локальной разработки по
environment policy, а не используется frontend в runtime.
Validation и identity
Global ValidationPipe использует transform: true, whitelist: true.
Unknown properties удаляются, а их rejection не обещается без
forbidNonWhitelisted. Runtime DTO validators и преобразования задают допустимый
вход; бизнес-ограничения и доступ к account проверяются service/access boundary.
Guard подтверждает identity; accountId из URL сам по себе не доказывает доступ.
Error contract
Общий HttpExceptionFilter
возвращает application/problem+json со status и публичным code.
Неожиданный exception возвращает 500 / INTERNAL_SERVER_ERROR, без исходного
message/stack. Типичный ответ:
{ "status": 401, "code": "UNAUTHORIZED" }
Для input validation контракт требует 400, VALIDATION_ERROR и errors как
массив { pointer, detail }, где pointer адресует поле запроса. Это требование
не считается проверенным одним Swagger snapshot: direct controller call не
запускает ValidationPipe. Текущий filter преобразует ValidationError.constraints,
а default Nest pipe формирует массив строк; корректность field details в
configured HTTP pipeline нужно проверять отдельно и не копировать этот seam
как доказанно полный пример.
Документированный DTO — ProblemDetailsDto.
Filter не добавляет автоматически все поля из RFC (type, title, instance).
Не вводи дополнительные обязательные поля без согласованного изменения wire contract.
Caller выбирает поведение по public code, не по внутреннему тексту exception.
Domain errors и auth
Специальный code задаётся ответственным use case; generic mapping и безопасный envelope принадлежат filter. Auth endpoints используют свои status и cookie operations: Authentication. T-Bank token failure и временная недоступность имеют разные значения: Connection API. Raw upstream/Prisma errors и secrets не передаются frontend.
Граница доказательства
OpenAPI integration проверяет равенство schemas, а не результат каждого request. Filter unit test проверяет безопасный unexpected error. Для изменения validation, guard, status/cookie или domain error нужны representative configured HTTP cases; известный e2e environment blocker не превращает отсутствующую проверку в success. Выбор уровня и команд — backend testing.