Коды ошибок API являются предысторией – попробуйте вместо этого

1656552734 kody oshibok api yavlyayutsya predystoriej – poprobujte vmesto etogo

Предостерегающая сказка

Однажды девушка наблюдала за мамой, которая разворачивала только что купленный кусок говядины для запекания. Мать вырезала конечности мяса.

«Мама, почему ты это делаешь?» – спросила молодая девушка.

«Это дает лучший вкус», — ответила мать, ставя блюдо в печь.

«Как это так?»

«Я не помню, иди спроси свою бабушку, она научила меня всяким таким подсказкам».

Ребенку стало интересно, и он побежал в соседнюю хату своей бабушки.

«Бабушка, а ты знаешь, почему разрезание бортов в ростбифе делает его лучше?»

«Это должно быть с течением сока», — ответила бабушка.

«Разве мы не можем вместо этого пробить отверстия вилкой?»

«Моя мама всегда их так готовила, и она, безусловно, была отличным поваром».

Ребенок был не только любознательным, но и настойчивым, и побежал в дом, где жил его старший. Она рассказала, что ей рассказали мать и бабушка и повторила свой вопрос.

Старший рассмеялся.

«Я всегда обрезал кончики своего ростбифа, но только потому, что моя духовка была аааааа маловата для целого».

Эта маленькая сказка, существующая в бесконечных вариациях, делает немаловажный момент о человеческой жизни. Старые повадки тяжело умирают, даже если они не имели смысла десятилетиями (если вообще были). И информатика, хоть и развивается быстрыми темпами, достаточно склонна к такому типу вредных традиций.

ISagFl1mcQBDqHbbHGrgUZDMmwy9E7FQOtjV

Обработка ошибок

Возьмем, к примеру, обработку ошибок. Мы глубоко привыкли к кодам статуса HTTP, к небольшим ошибкам Unix, к длинным кодам ошибок Windows… и наши API наполнены пользовательскими номерами, указывающими на проблемы с вводами, либо с операционными ошибками SQL, либо с разрешениями доступа…

Первые языки программирования низкого уровня – включая C и Fortran – имели очень рудиментарные типы данных. Вот почему они обрабатывали ошибки как простые целые числа, которые могли сравнивать, переключать регистр, искать индексы массива и безболезненно передавать. И вот почему они в конечном счете использовали 0 (логическое значение False), чтобы обозначить все успехи, и ненулевые целые числа (boolean True), чтобы обозначить ошибки – что-то не слишком интуитивно понятное для простых смертных.

Но чего мы ожидаем ошибок в наших повседневных современных языках высокого уровня? Чтобы они были:

  • явныйпоэтому мы знаем, что они означают, не спрашивая каждый раз всю сеть
  • глубоко иерархическиечтобы мы могли уточнить случаи ошибок, не нарушая текущее программное обеспечение, и вернуться к общим методам лечения, когда встречаются слишком специфические ошибки
  • контекстуализированныйчтобы дополнительные данные могли сопровождать ошибку, а также подробно описывать, что именно пошло не так и почему

Таким образом, исключения реализуются во многих современных языках. Есть иерархии классов с (надеюсь) понятными значениями. Каждый из них имеет разные атрибуты экземпляров в разных ветвях этих иерархий, например, имена файлов, названия полей и ошибки ОС происхождения. И эти экземпляры влекут множество информации, включая обратные отслеживания и их локальные переменные для каждого кадра.

Но когда придет время, чтобы ошибка пересекла границы этого конкретного процесса, этого конкретного языка? Коды ошибок являются одними из худших средств поддержки для этого.

Что означает «Ошибка 0x29273363833»? Вы понятия не имеете. Вы не можете разделить эту ошибку на более точные случаи. Если вы хотите получить больше контекстной информации, вам придется получить ее в другом месте.

И вы мало представляете, каким может быть ближайший родительский код ошибки. Правда, некоторые системы отстаивают элементарное альтернативное поведение – например, если вы столкнулись с неизвестной ошибкой HTTP 478, вы должны обрабатывать ее как HTTP 400. Но она все еще слишком груба для многих случаев, и когда вы использовали все номера класса ошибок, вам не повезло.

Итак, что я предлагаю?

Просто сопоставьте типы исключений с их ближайшими JSON-совместимыми представлениями.
Каковы… последовательности идентификаторов.

Дамы и господа, я представляю вам кучу статусные слизи:

  • [“Exception”, “LookupError”, “KeyError”]
  • «ошибка|функциональный|недействительный_вход|отсутствует_значение»
  • “ошибка|технические|подключение|mysql.database_unreachable”
  • [“success”]
  • [“success”, “instance_found_in_cache”]

Как видите, не имеет большого значения, используем ли мы списки или строки; даже термин «слизняк» не следует воспринимать слишком жестко, иметь в них подчеркивание или прописные буквы безвредно.

The важный вынос сообщение состоят в том, что эти улитки:

  • достаточно откровенно
  • достаточно легко сопоставить с исключениями, касающимися языка
  • достаточно легко сопоставить в диспетчере обработки ошибок.

Точки должны быть зарезервированы, чтобы квалифицировать и, таким образом, различать исключения с одинаковыми названиями, предоставленные разными пакетами. Примером является cuteforms.Invalid против validator.Invalid.

Приятным моментом является то, что слизи статуса могут использоваться для различения случаев успеха, как семейство «HTTP 2XX» отстаивало это для Интернета.

Итак, вот первый момент, который я хотел сказать: используйте сообщение о статусе, чтобы объявить результаты операции.

Обработка ошибок является основой надежности программного обеспечения и приятного использования, поэтому она заслуживает не только типов данных на уровне сборки.. Давайте просто прекратим использовать плохую диспетчеризацию ошибок на основе целых чисел, на единичных пробках или – хуже всего – на булевых значениях.

swBxJBfvHeKOw87J-k1doVYZAi0FYdJGPl6N
Все-таки лучше обрабатывать ошибки, чем «Возникшая ошибка, пожалуйста, проверьте журналы»…

Второй момент, который я хотел сказать об обработке ошибок: быть амбициозным.

Многие протоколы определяют кастрированные структуры ошибок – «если мне достаточно, то достаточно и другим». И в конечном итоге разработчики добавляют свою систему обработки ошибок. Иногда ответы SUCCESS начального протокола наполнены собственными структурами ошибок, когда ответы ERROR не покидают места для настройки (смотря на вас, XML-RPC).

Так что если вам однажды придется указать собственный формат ошибки — что всегда жалко, но иногда неизбежно — думать масштабно.

Чего мы ждем от формата ответа?

  • Наверное нам нужны статусные слизи, чтобы точно увидеть, какой вид успеха или ошибки произошел.
  • Нам также понадобятся переведенные сообщения для отображения интерфейса.
  • Скорее всего, нам также нужны непереводимые сообщения, поскольку их гораздо удобнее искать в исходных кодах или переводить на стороне интерфейса.
  • Нам нужно место для деревьев данных, относящихся к статусу, чтобы вся соответствующая информация могла быть предоставлена ​​машинной обработкой.
  • Нам, вероятно, также нужна поддержка множественных или рекурсивных структур данных, например, когда несколько полей веб-формы имеют собственную причину для отклонения.
  • Возможно, нам придется передать частичные успехи, например, когда не все данные аккаунта пользователя можно получить из каталогов. Возможно, нам придется передать и частичные ошибки, например, когда не удалось получить достоверного ответа, но некоторые кэшированные данные возвращаются на случай, если это поможет вам.

Вот пример (почти) универсальной структуры StatusPack:

{
status_slugs : список слаг для успешной/ложной диспетчеризации, обязательное поле
данные: дерево данных с контекстной информацией (результаты, недействительные поля ввода…)
traceback : только для режима разработчика, может включать кадры с локальными переменными
nested_statuses: необязательный список структур StatusPack
message_translated: строка для отображения
message_untranslated: строка или [string template, parameters] пора
}

Эта структура должна включать случаи использования, упомянутые выше, благодаря пластичности, предоставленной полем «nested_statuses».

Если иметь дело с микросервисыобъединив эти пакеты статуса в цепочку и правильно отобразив их на стороне пользователя. особенно отслеживание — может сэкономить вам дни для исследования журналов.

И если вы хотите скрыть свои ошибки, тогда хорошо. Но не нужно указывать коды ошибок самостоятельно. Просто создавайте хэши вашего status_slugs и автоматически создайте весь список доступных ошибок путем самоанализа вашей кодовой базы.

IjhQTfo7JkC9BOqM1fDtlEfpWs9nNIv0ipHk
То ощущение, когда ваш код безупречно обрабатывает все виды ошибок пользователей и сети

Последний момент, на котором я подчеркиваю: будьте добры к потребителям API.

Убедитесь, что ваши потребители знать когда возникает ошибка. Убедитесь, что ваши потребители также знать что делать, особенно программно, в этом случае.

  • Бесшумные ошибки — это прихожая ада. Удаление несуществующей учетной записи должны вернуть ошибку. Но введите мягкий параметр strict=False для таких операций, чтобы пользователи могли совершать неважные вызовы, не смущая себя ошибками.
  • Наличие ValueError в поле формы, которое прислали пользователи (ошибка ввода), или в переменной, о которой они ничего не знают (ошибка сервера), – это совершенно разные случаи. Они должны закончиться как разные статусные пулы. Когда ваш API действует как реле между пользователями и другими API, этот анализ может быть очень трудно выполнить, особенно если удаленные API имеют плохие отчеты об ошибках. Но все же попробуйте.
  • В своей документации четко укажите значение классов ошибок и то, какие действия можно ожидать от потребителей. Обычно технические ошибки означают «если вы повторите попытку позже, это может сработать». С другой стороны, функциональные ошибки означают, что «ваши рабочие процессы или ввод неправильны, слепая повторная попытка не поможет». Вашу иерархию статусных улиток, возможно, нужно будет точно настроить с любовью и вниманием в течение нескольких лет.

Эти две идеи status slugs и StatusPack структуры безусловно, не воплощение обработки ошибок, но они являются уверенным шагом вперед с точки зрения точности и возможности развития.

Я хотел бы услышать другие поля ошибок или другие стратегии обработки, которые могли придумать разработчики API. Пожалуйста, поделитесь своими инновациями и извлеченными тяжелым трудом уроками!

Отредактировано 07.09.2018: Исправьте опечатки и уточните идею, лежащую в основе термина «улитка».

Отредактировано 22.06.2019: Уточните поле «данные» StatusPack

Добавить комментарий

Ваш адрес email не будет опубликован.