60 lines
3.9 KiB
Markdown
60 lines
3.9 KiB
Markdown
# HTTP API и ошибки
|
||
|
||
## Источник контракта
|
||
|
||
Nest controllers/DTO/Swagger metadata генерируют runtime OpenAPI. Настройка
|
||
приложения — [configureApp](../../backend/src/main.ts); frontend хранит derived
|
||
snapshot и generated TS. Изменения проходят
|
||
[contract workflow](../development/runtime-openapi-verification.md).
|
||
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](../../backend/src/common/filters/http-exception.filter.ts)
|
||
возвращает `application/problem+json` со `status` и публичным `code`.
|
||
Неожиданный exception возвращает `500` / `INTERNAL_SERVER_ERROR`, без исходного
|
||
message/stack. Типичный ответ:
|
||
|
||
```json
|
||
{ "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](../../backend/src/common/decorators/api-safe-error-response.decorator.ts).
|
||
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](../features/authentication.md).
|
||
T-Bank token failure и временная недоступность имеют разные значения:
|
||
[Connection API](../features/tbank-connection.md#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](../../backend/.ai/conventions/backend-testing.md).
|