Контракты ·
Как описать ошибки и идемпотентность API
Сделать поведение интеграции предсказуемым при валидации, повторах и частичных сбоях.
Кратко: за 2 минуты
Сделать поведение интеграции предсказуемым при валидации, повторах и частичных сбоях. Результат работы — Error Catalog.
Когда применять
Урок относится к этапу «Контракты». Зафиксировать границы взаимодействия систем и однозначные критерии приемки. Задачу выполняют до реализации или согласования зависимого решения, чтобы команда опиралась на проверенные факты и однозначные договоренности.
Что это дает
Правильно выполненная работа снижает стоимость переделок, делает решение проверяемым и дает участникам единый источник информации. Практический результат фиксируется в артефакте «Error Catalog».
Пошагово: как выполнить
- Классифицируйте бизнес- и технические ошибки
- Опишите код, сообщение и recoverability
- Зафиксируйте retry и idempotency policy
Критерии приемки
- Коды стабильны и документированы
- Клиент понимает следующее действие
- Повтор запроса безопасен там, где требуется
Типичные ошибки
- Возвращать одну ошибку на все случаи
- Использовать текст сообщения как контракт
Инструменты
Пример
Плохой пример
Возвращать одну ошибку на все случаи
Хороший пример
Учебный пример. Для отсутствующего обязательного поля предусмотрены статус и стабильный код ошибки. Повтор без изменения данных не рекомендуется; для временного отказа отдельно описаны допустимые повторы.
Шаблон
Каталог ошибочных ответов
Скачать рабочий лист этого урока
Выбрать рабочий шаблонРабочий артефакт
Рабочий артефакт
Каталог ошибочных ответов
Учебный пример. Для отсутствующего обязательного поля предусмотрены статус и стабильный код ошибки. Повтор без изменения данных не рекомендуется; для временного отказа отдельно описаны допустимые повторы.
- Методы
- Ошибки
- Сценарии
- Версии
Контроль качества
Спецификация интеграции
Коды стабильны и документированы
После релизов, изменения требований, обновления целей и появления новых рисков.
Контекст, проблему, доказательство, владельца, срок и критерий приемки.
Перед отметкой выполнено: Коды стабильны и документированы
Как применять
Начинайте с влияния на пользователя, продукт и команду. Затем проверьте реализуемость, критерии качества и формат доказательства результата. Хороший пункт чеклиста объясняет, какую проблему закрываем, как выполняем работу и по каким признакам считаем ее завершенной.
Короткие ответы
Частые вопросы
Зачем выполнять пункт «Как описать ошибки и идемпотентность API»?
Правильно выполненная работа снижает стоимость переделок, делает решение проверяемым и дает участникам единый источник информации. Практический результат фиксируется в артефакте «Error Catalog».
С чего начать выполнение?
Классифицируйте бизнес- и технические ошибки
Как понять, что пункт выполнен?
Коды стабильны и документированы
Какая ошибка чаще всего мешает результату?
Возвращать одну ошибку на все случаи
Режим обучения
Тест по теме
Проверка понимания
Ответьте на вопросы по материалу и получите итоговый отчет: что понято хорошо, а что стоит перечитать.
Для углубленного изучения
Редакция Ariol · Версия 2 · Обновлено
Независимая экспертная проверка не заявлена.
Что обновлено
- — Обновлено: Название, Шаблон результата, Пример, Плохой пример, Заголовок поиска, Описание поиска, Поисковые фразы.
Материал предназначен для обучения. Адаптируйте рекомендации к внутренним регламентам компании и условиям проекта.
Предложить исправление через контакты Ariol