Архитектура · Средняя
Как спроектировать модель ошибок
Определить типы ошибок, формат ответа и правила логирования.
Кратко: за 2 минуты
Определить типы ошибок, формат ответа и правила логирования. На выходе: формат ошибок документирован.
Когда применять
Пункт относится к этапу «Архитектура». Его задача — определить границы решения и избежать случайного усложнения системы. Он нужен до передачи результата разработчикам, QA и команде эксплуатации: иначе команда рискует возвращать 500 на бизнес-ошибки.
Что это дает
Единая модель ошибок упрощает frontend-интеграцию, поддержку и диагностику production-инцидентов. Это помогает связать работу с общей целью: надежная, безопасная и поддерживаемая система. Практический эффект виден, когда формат ошибок документирован.
Пошагово: как выполнить
- Разделите validation, auth, business и system errors.
- Опишите формат error response.
- Не раскрывайте чувствительные детали во внешнем ответе.
Критерии приемки
- Формат ошибок документирован.
- Коды ошибок стабильны.
- Логи содержат диагностический контекст.
Типичные ошибки
- Возвращать 500 на бизнес-ошибки.
- Показывать stack trace пользователю.
- Делать разные форматы ошибок в разных эндпоинтах.
Инструменты
Пример
Плохой пример
Возвращать 500 на бизнес-ошибки.
Хороший пример
Учебный пример. Для неверного количества API возвращает стабильный код VALIDATION_ERROR, имя поля и request ID. Клиент принимает решение по коду, а не по русскому тексту; стек исключения остается в защищенном журнале.
Шаблон
Каталог кодов ошибок
Скачать рабочий лист этого урока
Выбрать рабочий шаблонРабочий артефакт
Architecture note
Каталог кодов ошибок
Учебный пример. Для неверного количества API возвращает стабильный код VALIDATION_ERROR, имя поля и request ID. Клиент принимает решение по коду, а не по русскому тексту; стек исключения остается в защищенном журнале.
- Bounded context
- Dependencies
- Domain entities
- Risk areas
Контроль качества
Карта границ сервиса
Формат ошибок документирован.
После изменения контрактов, релизов, инцидентов, роста нагрузки и пересмотра архитектурных решений.
Контракт, ограничения, сценарии отказа, метрики, владельца сервиса и критерии готовности.
Перед отметкой выполнено: Формат ошибок документирован.
Как применять
Начинайте с границ ответственности и пользовательского сценария, который обслуживает система. Затем проверьте контракт, данные, отказоустойчивость, безопасность и наблюдаемость. Хороший backend-пункт фиксирует, что именно меняется, как это проверить и какие метрики покажут стабильность решения.
Короткие ответы
Частые вопросы
Зачем выполнять пункт «Как спроектировать модель ошибок»?
Единая модель ошибок упрощает frontend-интеграцию, поддержку и диагностику production-инцидентов. Это помогает связать работу с общей целью: надежная, безопасная и поддерживаемая система. Практический эффект виден, когда формат ошибок документирован.
С чего начать выполнение?
Разделите validation, auth, business и system errors.
Как понять, что пункт выполнен?
Формат ошибок документирован.
Какая ошибка чаще всего мешает результату?
Возвращать 500 на бизнес-ошибки.
Режим обучения
Тест по теме
Проверка понимания
Ответьте на вопросы по материалу и получите итоговый отчет: что понято хорошо, а что стоит перечитать.
Для углубленного изучения
Редакция Ariol · Версия 2 · Обновлено
Независимая экспертная проверка не заявлена.
Что обновлено
- — Обновлено: Название, Шаблон результата, Пример, Плохой пример, Заголовок поиска, Описание поиска, Поисковые фразы.
Материал предназначен для обучения. Адаптируйте рекомендации к внутренним регламентам компании и условиям проекта.
Предложить исправление через контакты Ariol