From 0e88b1c102ddbdff43fbb70c364f954671ae0815 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=93=D0=BE=D0=BB=D0=B8=D0=BA=D0=BE=D0=B2=20Maximillian?= =?UTF-8?q?=20=D0=90=D0=BD=D1=82=D0=BE=D0=BD?= Date: Mon, 19 Oct 2026 10:56:32 +0300 Subject: [PATCH] refactor(domain):lab4 add comments with ai to ease up understanding --- backend/internal/domain/errors.go | 110 ++++++++++++++++++++++++------ 1 file changed, 88 insertions(+), 22 deletions(-) diff --git a/backend/internal/domain/errors.go b/backend/internal/domain/errors.go index 89fbf32..df24988 100644 --- a/backend/internal/domain/errors.go +++ b/backend/internal/domain/errors.go @@ -1,34 +1,55 @@ package domain +// Этот файл — единственный источник доменных ошибок. +// Правила: +// 1. sentinel-ошибки (ErrXxx) нужны для errors.Is. +// 2. типы *XxxError нужны для errors.As и для поля code в JSON. +// 3. У каждого типа есть Code() ErrorCode — через него DTO маппит +// в HTTP-код (StatusFromError в httpapi/dto/error.go). +// 4. В Error() пишем только то, что безопасно показать клиенту: +// без SQL, stack trace, путей, credential'ов. + import ( "errors" "fmt" ) +// =================================================================== +// ErrorCode — машинный код для JSON {"error":{"code":"..."}} +// =================================================================== + type ErrorCode string const ( - CodeInvalidRequest ErrorCode = "invalid_request" - CodeUnauthorized ErrorCode = "unauthorized" - CodeNotFound ErrorCode = "not_found" - CodeConflict ErrorCode = "conflict" - CodeUnsupportedMediaType ErrorCode = "unsupported_media_type" - CodeInternalError ErrorCode = "internal_error" - CodeUnavailable ErrorCode = "unavailable" - CodePayloadTooLarge ErrorCode = "payload_too_large" + CodeInvalidRequest ErrorCode = "invalid_request" // 400 + CodeUnauthorized ErrorCode = "unauthorized" // 401 + CodeNotFound ErrorCode = "not_found" // 404 + CodeConflict ErrorCode = "conflict" // 409 + CodePayloadTooLarge ErrorCode = "payload_too_large" // 413 + CodeUnsupportedMediaType ErrorCode = "unsupported_media_type" // 415 + CodeUnavailable ErrorCode = "unavailable" // 503 + CodeInternalError ErrorCode = "internal_error" // 500 ) +// =================================================================== +// Sentinel-ошибки (errors.Is) +// =================================================================== + var ( ErrNotFound = errors.New("не найдено") ErrAlreadyExists = errors.New("уже существует") ErrInvalidInput = errors.New("некорректные данные") ErrUnauthorized = errors.New("требуется аутентификация") ErrUnsupportedMediaType = errors.New("неподдерживаемый тип содержимого") - ErrUnavailable = errors.New("сервис недоступен") ErrPayloadTooLarge = errors.New("превышен допустимый размер") + ErrUnavailable = errors.New("сервис недоступен") ErrConflict = errors.New("конфликт") ) +// =================================================================== +// 404 Not Found +// =================================================================== + type NotFoundError struct { Entity string ID string @@ -40,6 +61,12 @@ func (e *NotFoundError) Error() string { func (e *NotFoundError) Unwrap() error { return ErrNotFound } func (e *NotFoundError) Code() ErrorCode { return CodeNotFound } +// =================================================================== +// 409 Conflict +// =================================================================== + +// AlreadyExistsError — конфликт уникальности (например, username занят). +// Отдельно от ConflictError: другой смысл, но оба дают HTTP 409. type AlreadyExistsError struct { Entity string Field string @@ -52,6 +79,7 @@ func (e *AlreadyExistsError) Error() string { func (e *AlreadyExistsError) Unwrap() error { return ErrAlreadyExists } func (e *AlreadyExistsError) Code() ErrorCode { return CodeConflict } +// IdempotencyConflictError — тот же Idempotency-Key, но другое тело запроса. type IdempotencyConflictError struct { Key string } @@ -59,10 +87,23 @@ type IdempotencyConflictError struct { func (e *IdempotencyConflictError) Error() string { return "Idempotency-Key " + e.Key + " уже использован с другим телом запроса" } - func (e *IdempotencyConflictError) Unwrap() error { return ErrAlreadyExists } func (e *IdempotencyConflictError) Code() ErrorCode { return CodeConflict } +// ConflictError — конфликт бизнес-состояния, а не уникальности. +// Примеры: "вложение ещё не готово", "нельзя перевести failed-вложение в ready". +// Reason — короткая безопасная фраза, идёт клиенту как message. +type ConflictError struct{ Reason string } + +func (e *ConflictError) Error() string { return e.Reason } +func (e *ConflictError) Unwrap() error { return ErrConflict } +func (e *ConflictError) Code() ErrorCode { return CodeConflict } + +// =================================================================== +// 400 Bad Request +// =================================================================== + +// ValidationError — неверное поле или формат. type ValidationError struct { Field string Message string @@ -74,8 +115,15 @@ func (e *ValidationError) Error() string { func (e *ValidationError) Unwrap() error { return ErrInvalidInput } func (e *ValidationError) Code() ErrorCode { return CodeInvalidRequest } +// =================================================================== +// 401 Unauthorized +// =================================================================== + +// UnauthorizedError — нет/просрочен/отозван токен, неверные credentials. +// Reason — только для логов, в JSON не попадает (по контракту все 401 +// должны иметь одинаковое сообщение, чтобы не перебирать username). type UnauthorizedError struct { - Reason string // для логов; в JSON не попадает + Reason string } func (e *UnauthorizedError) Error() string { @@ -84,6 +132,17 @@ func (e *UnauthorizedError) Error() string { func (e *UnauthorizedError) Unwrap() error { return ErrUnauthorized } func (e *UnauthorizedError) Code() ErrorCode { return CodeUnauthorized } +// =================================================================== +// 415 Unsupported Media Type +// =================================================================== + +// UnsupportedMediaTypeError — неверный Content-Type. +// +// ВАЖНО: сейчас текст жёстко про application/json. Для lab4 (вложения) +// ожидается image/png или image/jpeg. Прежде чем использовать этот тип +// в AttachmentHandler, добавить поле Expected string (дефолт application/json) +// или сделать отдельный тип — не переиспользовать как есть, иначе клиент +// увидит неверную подсказку. type UnsupportedMediaTypeError struct { MediaType string } @@ -97,14 +156,12 @@ func (e *UnsupportedMediaTypeError) Error() string { func (e *UnsupportedMediaTypeError) Unwrap() error { return ErrUnsupportedMediaType } func (e *UnsupportedMediaTypeError) Code() ErrorCode { return CodeUnsupportedMediaType } -type UnavailableError struct{ Reason string } - -func (e *UnavailableError) Error() string { - return "сервис временно недоступен" -} -func (e *UnavailableError) Unwrap() error { return ErrUnavailable } -func (e *UnavailableError) Code() ErrorCode { return CodeUnavailable } +// =================================================================== +// 413 Payload Too Large +// =================================================================== +// PayloadTooLargeError — тело больше лимита. +// Message опционален: если пуст — формируется из Limit. type PayloadTooLargeError struct { Limit int64 Message string @@ -119,8 +176,17 @@ func (e *PayloadTooLargeError) Error() string { func (e *PayloadTooLargeError) Unwrap() error { return ErrPayloadTooLarge } func (e *PayloadTooLargeError) Code() ErrorCode { return CodePayloadTooLarge } -type ConflictError struct{ Reason string } +// =================================================================== +// 503 Service Unavailable +// =================================================================== -func (e *ConflictError) Error() string { return e.Reason } -func (e *ConflictError) Unwrap() error { return ErrConflict } -func (e *ConflictError) Code() ErrorCode { return CodeConflict } +// UnavailableError — недоступна критичная зависимость (БД, кэш, S3). +// Reason — только для логов; клиент видит общее сообщение по контракту, +// чтобы не раскрывать имена сервисов и топологию. +type UnavailableError struct{ Reason string } + +func (e *UnavailableError) Error() string { + return "сервис временно недоступен" +} +func (e *UnavailableError) Unwrap() error { return ErrUnavailable } +func (e *UnavailableError) Code() ErrorCode { return CodeUnavailable }