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" // 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("неподдерживаемый тип содержимого") ErrPayloadTooLarge = errors.New("превышен допустимый размер") ErrUnavailable = errors.New("сервис недоступен") ErrConflict = errors.New("конфликт") ) // =================================================================== // 404 Not Found // =================================================================== type NotFoundError struct { Entity string ID string } func (e *NotFoundError) Error() string { return fmt.Sprintf("%s с id %q не найден", e.Entity, e.ID) } 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 Value string } func (e *AlreadyExistsError) Error() string { return fmt.Sprintf("%s с %s %q уже существует", e.Entity, e.Field, e.Value) } func (e *AlreadyExistsError) Unwrap() error { return ErrAlreadyExists } func (e *AlreadyExistsError) Code() ErrorCode { return CodeConflict } // IdempotencyConflictError — тот же Idempotency-Key, но другое тело запроса. type IdempotencyConflictError struct { Key string } 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 } func (e *ValidationError) Error() string { return fmt.Sprintf("ошибка валидации поля %q: %s", e.Field, e.Message) } 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 } func (e *UnauthorizedError) Error() string { return "требуется аутентификация" } 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 Expected string } func (e *UnsupportedMediaTypeError) Error() string { expected := e.Expected if expected == "" { expected = "application/json" } if e.MediaType == "" { return "требуется Content-Type: " + expected } return fmt.Sprintf("неподдерживаемый Content-Type %q; требуется %s", e.MediaType, expected) } func (e *UnsupportedMediaTypeError) Unwrap() error { return ErrUnsupportedMediaType } func (e *UnsupportedMediaTypeError) Code() ErrorCode { return CodeUnsupportedMediaType } // =================================================================== // 413 Payload Too Large // =================================================================== // PayloadTooLargeError — тело больше лимита. // Message опционален: если пуст — формируется из Limit. type PayloadTooLargeError struct { Limit int64 Message string } func (e *PayloadTooLargeError) Error() string { if e.Message != "" { return e.Message } return fmt.Sprintf("превышен лимит %d байт", e.Limit) } func (e *PayloadTooLargeError) Unwrap() error { return ErrPayloadTooLarge } func (e *PayloadTooLargeError) Code() ErrorCode { return CodePayloadTooLarge } // =================================================================== // 503 Service Unavailable // =================================================================== // 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 }