Короткие правила проектирования обработки ошибок в большом Python‑проекте.
1) Когда использовать исключения, когда — возвращать объекты ошибки
- Исключения:
- Для непредвиденных/необычных ошибок (I/O, сетевые сбои, баги, нарушения инвариантов).
- Когда нужно прервать выполнение по всей стековой цепочке и дать верхнему уровню решить (логирование, ретрай, фолбэк).
- Библиотеки: предпочитайте исключения — они естественны для Python и легко отлавливаются по типу.
- Не используйте исключения в горячих циклах/частых путях как нормальную ветвь управления (перформанс/читаемость).
- Возврат объектов ошибки / Result‑тип:
- Для ожидаемых ошибок, которые являются частью нормального потока (валидация, бизнес‑правила, частичные результаты в батче).
- Когда нужно аккумулировать ошибки (batch processing) или вернуть одновременно данные + мета (успех/ошибка).
- Когда API ориентировано на функциональный стиль или на других языках с explicit error values.
- Полезно в высокопроизводительных местах, где исключения дорогие.
- Практическое правило: внутри библиотек — бросайте типизированные исключения; на границах (например, handler HTTP, CLI) — трансформируйте исключения в коды/объекты/HTTP‑ответы.
2) Дизайн исключений
- Сделайте базовый тип для проекта, например `class ProjectError(Exception): ...`, и конкретные подклассы (`NotFoundError`, `ValidationError`, `TransientError`).
- Разделяйте ошибки по семантике (transient vs permanent). Это помогает для ретраев и обработки.
- Не ловите `Exception`/`BaseException` без явной причины; ловите конкретные типы.
- Добавляйте полезный контекст (атрибуты, message, cause). Используйте `raise ... from ...` для цепочек.
3) Где и как логировать (уровни и практики)
- Уровни: DEBUG, INFO, WARNING, ERROR, CRITICAL — стандартный смысл:
- DEBUG — подробности для разработчика (внутренние состояния).
- INFO — нормальные, важные события работы.
- WARNING — потенциальные проблемы, восстановление возможно.
- ERROR — необработанная ошибка, действие не выполнено.
- CRITICAL — падение сервиса или крайне серьёзное состояние.
- Правило «логировать один раз»:
- Логируйте ошибку там, где вы её окончательно обрабатываете/отбрасываете (т.е. не будете дальше пробрасывать). Не логировать на каждом промежуточном `except`, чтобы не дублировать трассировки.
- При повторном логировании добавляйте только контекст, не full traceback, или используйте `exc_info=False`/передавайте `stack_info` осознанно.
- Используйте `logger.exception()` внутри `except` когда нужно логировать traceback.
- Структурированное логирование: добавляйте поле correlation_id, operation, user_id и т.п. для трассировки.
- Для бибилотек: по умолчанию не логируйте ERROR; оставьте логирование потребителю (профиль: DEBUG/INFO только для опции).
4) Гарантия освобождения ресурсов при множественных точках выхода
- Всегда предпочтительнее контекстные менеджеры (`with`) — гарантируют enter/exit независимо от исключений/return/quit.
- Синхронный: `with open(...) as f: ...`
- Асинхронный: `async with ...`
- Для нескольких или динамических ресурсов используйте `contextlib.ExitStack`:
- позволяет регистрировать много контекстов и гарантирует корректный `__exit__` в обратном порядке.
- Если контекстный менеджер невозможен — используйте `try/finally` вокруг блока с любым количеством `return`/`raise`.
- Примеры:
- ExitStack:
- from contextlib import ExitStack
- with ExitStack() as stack:
res1 = stack.enter_context(open(...))
res2 = stack.enter_context(lock.acquire_context())
...
- try/finally:
- resource.acquire()
try:
... return ...
finally:
resource.release()
- Для сложной последовательности освобождения (несколько этапов), делайте явный cleanup API (метод `close()`/`shutdown()`), и вызывайте его в `finally` или регистрируйте в `ExitStack`.
- Избегайте надежности на финализаторы (`__del__`) для критичных освобождений — они ненадёжны при завершении интерпретатора.
- Для фоновых задач/пулов используйте явное graceful shutdown, сигналы и await завершения задач.
5) Практические паттерны интеграции
- Граница библиотека → приложение:
- библиотека: raise конкретные исключения;
- приложение: catch specific exceptions, логирует once, конвертирует в user‑facing error/HTTP code/exit code.
- Batch processing:
- Возвращайте list of Result или (successes, errors) для продолжения обработки и последующей агрегации логов/метрик.
- Async/await:
- Используйте `async with`, ловите исключения на уровне таск‑менеджера; при параллельных задачах собирайте исключения через `asyncio.gather(..., return_exceptions=True)` если нужно агрегировать.
- Retry:
- Работайте с transient errors по типу и используйте backoff; не ретрайте на permanent errors.
6) Проверки и тесты
- Тестируйте поведение и контракт ошибок (какие исключения бросаются, какие значения возвращаются).
- Проверяйте, что ресурсы освобождаются (mock/spy release) при ошибках и return.
Краткий свод:
- Исключения — для ошибок, прерывающих поток; объекты ошибок — для ожидаемых ошибок/агрегации/производительности.
- Логируйте один раз в месте окончательной обработки, используйте уровни по смыслу и структурированные поля.
- Всегда освобождайте ресурсы через контекстные менеджеры/ExitStack/try‑finally; избегайте __del__ для критичных действий.