Files
mtusi2026lab5-fork/backend/internal/domain/errors.go
T

198 lines
8.6 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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 }