Ошибки и исключения: как падать красиво
Ошибки - это часть жизни. Вопрос: кто их увидит и насколько быстро поймёт, что случилось.
В Go ошибки - это значения, а не исключения. Это фундаментальное решение дизайна языка: ошибку видно прямо в сигнатуре функции. Но проигнорировать её всё же можно: вызов f.Close() без присваивания результата компилируется молча. Такие места ловит линтер errcheck (в golangci-lint он включён по умолчанию). В PHP подход другой - исключения через try/catch.
Три правила обработки ошибок
- Ошибка должна быть понятной - из текста ясно, что произошло
- Добавляй контекст - где произошла ошибка и при каких условиях
- Не глотай ошибки молча -
_ = doSomething()- худшее, что можно сделать
Sentinel errors: именованные ошибки
Sentinel error - это предопределённая переменная-ошибка (Go), с которой сравнивают через errors.Is. В PHP и Python ближайший аналог - отдельный класс исключения, который ловят по типу (строго говоря, проверка по типу ближе к errors.As, о нём ниже).
// Объявление sentinel errors
var (
ErrNotFound = errors.New("not found")
ErrUnauthorized = errors.New("unauthorized")
ErrForbidden = errors.New("forbidden")
)
// Использование
func GetUser(ctx context.Context, id int) (*User, error) {
user, err := repo.FindByID(ctx, id)
if err != nil {
return nil, fmt.Errorf("get user %d: %w", id, err)
}
if user == nil {
return nil, ErrNotFound
}
return user, nil
}
// Проверка через errors.Is
user, err := GetUser(ctx, 42)
if errors.Is(err, ErrNotFound) {
http.Error(w, "user not found", 404)
}
В Go ошибки - это значения: возвращаются вторым параметром, проверяются errors.Is / errors.As, оборачиваются %w.
// Объявление sentinel-исключений (по классу)
final class NotFoundException extends RuntimeException {}
final class UnauthorizedException extends RuntimeException {}
final class ForbiddenException extends RuntimeException {}
// Использование: метод показан вместе с классом, которому принадлежит -
// иначе `$this->repo` не к чему привязать, а блок нельзя запустить.
final class UserService
{
public function __construct(private UserRepository $repo) {}
public function getUser(int $id): User
{
try {
$user = $this->repo->findById($id);
} catch (Throwable $e) {
throw new RuntimeException("get user {$id} failed", previous: $e);
}
if ($user === null) {
throw new NotFoundException("user {$id} not found");
}
return $user;
}
}
// Проверка через try/catch
try {
$user = $service->getUser(42);
} catch (NotFoundException $e) {
return new JsonResponse(['error' => 'user not found'], 404);
}
В PHP ошибки - это исключения: проверяются catch по типу, оборачиваются через previous, идиоматично кидать конкретный класс на каждый вид сбоя.
# Объявление sentinel-исключений (по классу)
class NotFoundError(Exception): ...
class UnauthorizedError(Exception): ...
class ForbiddenError(Exception): ...
# Использование: метод показан вместе с классом, которому принадлежит -
# иначе self._repo не к чему привязать, а блок нельзя запустить.
class UserService:
def __init__(self, repo: UserRepository) -> None:
self._repo = repo
def get_user(self, user_id: int) -> User:
# Сбой репозитория не ловим и не заворачиваем в RuntimeError:
# исключение уходит наверх своего типа, а шаг виден в traceback
user = self._repo.find_by_id(user_id)
if user is None:
raise NotFoundError(f"user {user_id} not found")
return user
# Проверка через except по типу (в FastAPI это тело обработчика маршрута)
def get_user_handler(service: UserService, user_id: int) -> JSONResponse:
try:
user = service.get_user(user_id)
except NotFoundError:
return JSONResponse({"error": "user not found"}, status_code=404)
return JSONResponse({"id": user.id, "email": user.email})
Здесь ошибки - это тоже исключения: ловятся except по типу, оборачиваются через raise ... from e (цепочка __cause__), на каждый вид сбоя - свой класс.
Sentinel errors хороши для стандартных ситуаций: «не найдено», «нет доступа», «конфликт». Не создавай sentinel для каждой мелочи - иначе получишь зоопарк.
Custom error types: когда нужен контекст
Когда простого текста недостаточно - создай свой тип ошибки:
type ValidationError struct {
Field string
Message string
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("validation: %s - %s", e.Field, e.Message)
}
// Использование
func ValidateAge(age int) error {
if age < 0 || age > 150 {
return &ValidationError{
Field: "age",
Message: "must be between 0 and 150",
}
}
return nil
}
// Проверка типа через errors.As
var ve *ValidationError
if errors.As(err, &ve) {
fmt.Printf("поле %s: %s\n", ve.Field, ve.Message)
}
<?php
declare(strict_types=1);
// PHP-эквивалент: typed exception с публичными readonly-полями для контекста
final class ValidationException extends DomainException
{
public function __construct(
public readonly string $field,
public readonly string $reason,
) {
parent::__construct("validation: {$field} - {$reason}");
}
}
final class AgeValidator
{
public function validate(int $age): void
{
if ($age < 0 || $age > 150) {
throw new ValidationException(
field: 'age',
reason: 'must be between 0 and 150',
);
}
}
}
// Проверка типа через catch по классу (аналог errors.As)
try {
$validator->validate($age);
} catch (ValidationException $e) {
echo "поле {$e->field}: {$e->reason}\n";
}
from dataclasses import dataclass
@dataclass
class ValidationError(Exception):
field: str
message: str
def __str__(self) -> str:
return f"validation: {self.field} - {self.message}"
# Использование
def validate_age(age: int) -> None:
if age < 0 or age > 150:
raise ValidationError(field="age", message="must be between 0 and 150")
# Проверка типа через except (аналог errors.As)
try:
validate_age(age)
except ValidationError as ve:
print(f"поле {ve.field}: {ve.message}")
ℹ️ errors.Is vs errors.As
errors.Is(err, target)- проверяет конкретное значение (sentinel).errors.As(err, &target)- проверяет тип и извлекает данные. Оба умеют ходить по цепочке оборачивания (%w).
Wrapping: оборачивание ошибок через %w
fmt.Errorf с глаголом %w оборачивает ошибку, сохраняя всю цепочку:
// Слой repository
func (r *UserRepo) GetByID(ctx context.Context, id int) (*User, error) {
var user User
err := r.db.WithContext(ctx).First(&user, id).Error
if err != nil {
return nil, fmt.Errorf("user_repo.GetByID(%d): %w", id, err)
}
return &user, nil
}
// Слой use case
func (uc *ProfileUC) GetProfile(ctx context.Context, id int) (*Profile, error) {
user, err := uc.userRepo.GetByID(ctx, id)
if err != nil {
return nil, fmt.Errorf("get profile: %w", err)
}
return toProfile(user), nil
}
// В логе:
// get profile: user_repo.GetByID(42): record not found
<?php
declare(strict_types=1);
// PHP-эквивалент wrapping через previous-параметр. Цепочка строится так же:
final class UserRepository
{
public function __construct(private readonly PDO $db) {}
public function getById(int $id): User
{
try {
$stmt = $this->db->prepare('SELECT * FROM users WHERE id = :id');
$stmt->execute(['id' => $id]);
$row = $stmt->fetch(PDO::FETCH_ASSOC);
} catch (PDOException $e) {
throw new RuntimeException(
"user_repo.getById({$id})",
previous: $e,
);
}
if ($row === false) {
throw new NotFoundException("user {$id} not found");
}
return User::fromRow($row);
}
}
final class ProfileUseCase
{
public function __construct(private readonly UserRepository $users) {}
public function getProfile(int $id): Profile
{
// Ничего не ловим и не оборачиваем: обёртка в RuntimeException
// сломала бы catch (NotFoundException $e) в контроллере.
// Тип исключения - контракт, контекст дают trace и previous.
return Profile::fromUser($this->users->getById($id));
}
}
// При сбое БД Monolog раскрутит цепочку через ->getPrevious():
// RuntimeException: user_repo.getById(42) -> PDOException: SQLSTATE[...]
class StorageError(Exception):
"""Сбой хранилища, выраженный на языке приложения, а не драйвера."""
# Слой repository (psycopg) - граница слоя: исключение драйвера
# переводим в своё доменное, чтобы use case не импортировал psycopg
class UserRepo:
def __init__(self, conn: psycopg.Connection) -> None:
self._conn = conn
def get_by_id(self, user_id: int) -> User:
try:
row = self._conn.execute(
"SELECT id, email FROM users WHERE id = %s", (user_id,)
).fetchone()
except psycopg.Error as e:
# `from e` - не аналог errors.Is: ловят по типу нового исключения
# (except StorageError), а psycopg.Error остаётся только в __cause__
# для traceback
raise StorageError(f"user_repo.get_by_id({user_id})") from e
if row is None:
raise NotFoundError(f"user {user_id} not found")
return User(*row)
# Слой use case: ничего не ловим и не оборачиваем. Обёртка в чужой тип
# (RuntimeError("get profile") from e) сломала бы except NotFoundError
# в хендлере - тип исключения и есть контракт, контекст даёт traceback
class ProfileUC:
def __init__(self, user_repo: UserRepo) -> None:
self._user_repo = user_repo
def get_profile(self, user_id: int) -> Profile:
user = self._user_repo.get_by_id(user_id)
return to_profile(user)
# В логе (logging.exception) traceback идёт через get_profile -> get_by_id:
# NotFoundError: user 42 not found
# При сбое БД - цепочка __cause__ от причины к следствию:
# psycopg.OperationalError: connection ... failed
# The above exception was the direct cause of the following exception:
# StorageError: user_repo.get_by_id(42)
Каждый слой добавляет свой контекст. В результате ошибка читается как стек вызовов - от бизнес-операции до конкретной причины.
Когда какой глагол:
──────────────────────────────────────────
%w - оборачивай, когда вызывающий код
может проверить тип через Is/As
%v - когда хочешь скрыть внутреннюю
реализацию (на границе API)
panic vs error
error panic
───────────────────────────────── ─────────────────────────────────
Ожидаемая ситуация Баг в программе
«Файл не найден» «Индекс за пределами массива»
Вызывающий код обрабатывает Программа падает (или recover)
Штатный поток Только init() и Must*-функции
// error: ожидаемая ситуация - файл может не существовать
func LoadConfig(path string) (*Config, error) {
data, err := os.ReadFile(path)
if err != nil {
return nil, fmt.Errorf("load config %s: %w", path, err)
}
var cfg Config
if err := json.Unmarshal(data, &cfg); err != nil {
return nil, fmt.Errorf("parse config: %w", err)
}
return &cfg, nil
}
// panic: нарушен инвариант, который не должен нарушаться при старте
func MustParseTemplate(name string) *template.Template {
t, err := template.ParseFiles(name)
if err != nil {
panic(fmt.Sprintf("parse template %s: %v", name, err))
}
return t
}
<?php
declare(strict_types=1);
// Recoverable: \Exception для ожидаемых ситуаций
final class ConfigLoader
{
public function load(string $path): Config
{
$data = @file_get_contents($path);
if ($data === false) {
throw new RuntimeException("load config {$path} failed");
}
try {
$decoded = json_decode($data, associative: true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
throw new RuntimeException('parse config', previous: $e);
}
return Config::fromArray($decoded);
}
}
// Unrecoverable: \Error для нарушенных инвариантов на старте
final class TemplateRegistry
{
public static function mustLoad(string $name): Twig\TemplateWrapper
{
try {
return self::twig()->load($name);
} catch (Throwable $e) {
// \Error не должен ловиться обычным catch(\Exception),
// что и подразумевается для «программа должна упасть»
throw new Error("parse template {$name} at boot", previous: $e);
}
}
}
import json
from pathlib import Path
from string import Template
class ConfigError(Exception):
"""Конфиг не загружен: файла нет или он битый."""
def load_config(path: str) -> Config:
"""Ожидаемая ситуация - файл может не существовать.
Обычное исключение, вызывающий код его обработает. Сбои ОС и парсера
переводим в своё ConfigError: `from e` - не аналог errors.Is, ловят
по типу нового исключения, а исходное остаётся в __cause__.
"""
try:
data = Path(path).read_text()
except OSError as e:
raise ConfigError(f"load config {path}") from e
try:
raw = json.loads(data)
except json.JSONDecodeError as e:
raise ConfigError(f"parse config {path}") from e
return Config(**raw)
# Аналог panic: нарушен инвариант, который не должен нарушаться при старте.
# SystemExit не ловится обычным except Exception - процесс упадёт на запуске
def must_parse_template(name: str) -> Template:
try:
return Template(Path(name).read_text())
except OSError as e:
raise SystemExit(f"parse template {name}: {e}") from e
⚠️ panic - только для Must-функций и init
Используй
panicвinit()иMust*-обёртках при старте приложения. В runtime-коде - всегдаerror. Библиотека, которая паникует на штатных ошибках, - плохая библиотека: клиент ждётerror, а получает падение процесса. А если паникует реализация интерфейса, контракт которого обещаетerror, это ещё и нарушение LSP.
Антипаттерны обработки ошибок
Глотание ошибки
// Плохо: ошибка исчезла бесследно
result, _ := doSomething()
// Хорошо: обработай или прокинь
result, err := doSomething()
if err != nil {
return fmt.Errorf("do something: %w", err)
}
<?php
declare(strict_types=1);
// Плохо: silence operator @ или пустой catch
$result = @doSomething(); // подавляет любые warnings/errors
try {
$result = doSomething();
} catch (Throwable $e) {
// тихо проглатываем - ничего не залогировано, ничего не возвращено
}
// Хорошо: либо обработай конкретно, либо пробрось наверх
try {
$result = doSomething();
} catch (NotFoundException $e) {
return null; // явно решили, что для этого кейса null - валидный исход
} catch (Throwable $e) {
throw new RuntimeException('do something', previous: $e);
}
# Плохо: ошибка исчезла бесследно
try:
result = do_something()
except Exception:
pass # тихо проглатываем - ничего не залогировано, ничего не возвращено
# Хорошо: либо обработай конкретно, либо пробрось наверх
try:
result = do_something()
except NotFoundError:
result = None # явно решили, что для этого кейса None - валидный исход
# Остальное не ловим вовсе: оно уйдёт наверх как есть, своего типа
Логирование + возврат (дубликаты в логах)
// Плохо: ошибка залогирована И возвращена
if err != nil {
log.Printf("error: %v", err)
return err // вызывающий тоже залогирует → дубликат
}
// Хорошо: нижние слои только возвращают, верхний - логирует
if err != nil {
return fmt.Errorf("operation X: %w", err)
}
<?php
declare(strict_types=1);
// Плохо: лог + re-throw в одном месте, верхний слой логирует ещё раз
final class BadRepository
{
public function __construct(private readonly LoggerInterface $logger) {}
public function save(Entity $e): void
{
try {
$this->doSave($e);
} catch (Throwable $err) {
$this->logger->error('save failed', ['err' => $err->getMessage()]);
throw $err; // дубликат в логах от верхнего exception handler
}
}
}
// Хорошо: нижние слои только wrap + throw, лог на границе HTTP-контроллера
final class GoodRepository
{
public function save(Entity $e): void
{
try {
$this->doSave($e);
} catch (Throwable $err) {
throw new RuntimeException('save entity', previous: $err);
}
}
}
// Логирование делает Symfony ExceptionListener один раз - с полным trace
import logging
logger = logging.getLogger(__name__)
# Плохо: ошибка залогирована И проброшена
try:
do_operation()
except Exception:
logger.exception("operation failed")
raise # вызывающий тоже залогирует - дубликат
# Хорошо: нижний слой не ловит - исключение уходит наверх как есть
def operation_x() -> None:
do_operation()
# Верхний слой (обработчик запроса) логирует один раз, с полным traceback
try:
operation_x()
except Exception:
logger.exception("operation X failed")
Обобщённые сообщения
// Плохо: как сказать врачу «мне плохо»
return errors.New("something went wrong")
// Хорошо: конкретика
return fmt.Errorf("create order for user %d: item %d out of stock",
userID, itemID)
<?php
declare(strict_types=1);
// Плохо: текст без идентификаторов - дебажить нечем
throw new RuntimeException('something went wrong');
// Хорошо: typed exception + конкретные id
final class OutOfStockException extends DomainException
{
public function __construct(
public readonly int $userId,
public readonly int $itemId,
) {
parent::__construct(
"create order for user {$userId}: item {$itemId} out of stock"
);
}
}
throw new OutOfStockException(userId: $userId, itemId: $itemId);
# Плохо: как сказать врачу «мне плохо»
raise RuntimeError("something went wrong")
# Хорошо: свой тип + конкретные id
class OutOfStockError(Exception):
def __init__(self, user_id: int, item_id: int) -> None:
super().__init__(
f"create order for user {user_id}: item {item_id} out of stock"
)
self.user_id = user_id
self.item_id = item_id
raise OutOfStockError(user_id=user_id, item_id=item_id)
Мини-задание
- Найди в проекте
_ = ...- замени на явную обработку - Проверь, что ошибки логируются с контекстом (id, endpoint, операция)
- Создай один sentinel error и один custom error type в своём проекте
- Убедись, что на границе API внутренние детали ошибок не утекают клиенту