refactor(domain):lab4 add comments with ai to ease up understanding

This commit is contained in:
Голиков Maximillian Антон
2026-10-19 10:56:32 +03:00
parent 57bcb05da8
commit 0e88b1c102
+88 -22
View File
@@ -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 }