refactor(domain):lab4 add comments with ai to ease up understanding
This commit is contained in:
@@ -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 }
|
||||
|
||||
Reference in New Issue
Block a user