Зачем нужны коды ошибок?
- Мы предоставляем API, чтобы оказать некую услугу, если у нас по какой-либо причине это сделать не удается, мы должны сообщить потребителю API, что же пошло не так, и помочь достичь желаемого, например, показав ссылку на документацию, где будут описаны случаи, когда такая ошибка возникает, и что можно предпринять на своей стороне чтобы эту ошибку устранить. Как итог – разработчики реже обращаются к команде с вопросами и все счастливы.
- Также это помогает с мониторингом - собираем в виде метрики все коды ошибок и смотрим, каких кодов ошибок больше всего. Каких-то кодов ошибок в нормальное время быть не должно вообще, какие-то могут быть в незначительном объёме. А вот любые всплески могут говорить о том, что у нас не все хорошо. Вероятно плохой релиз, баги.. иными словами инцидент. Даже если всплесков нет, можно завести техдолг задачу или баг на исследование причины этих ошибок и устранение.
- Коды ошибок можно записывать в скоупы лога, чтобы смотреть флоу который привел к ошибке, искать пострадавших и т.п.
Для упрощения внедрения кодов ошибок в приложение, у меня есть библиотека на гитхабе с подробным описанием, которую я использую на работе во всех сервисах.
Коды ошибок, которые может вернуть API можно документировать в такой таблице (см в комментариях)
Чтобы проще ориентироваться в источнике ошибки, каждому сервису (домену) необходимо завести свой префикс 2-3 символа.
Нумерацию начинаем с нуля, дополняя до 5 цифр (будет всего 7-8 символов на код ошибки).
Таким образом каждый сервис сможет завести до 100к ошибок. Что вполне достаточно чтобы заводить код ошибки на каждый if
В проекте book library применяются коды ошибок, можно посмотреть как это работает
- Мы предоставляем API, чтобы оказать некую услугу, если у нас по какой-либо причине это сделать не удается, мы должны сообщить потребителю API, что же пошло не так, и помочь достичь желаемого, например, показав ссылку на документацию, где будут описаны случаи, когда такая ошибка возникает, и что можно предпринять на своей стороне чтобы эту ошибку устранить. Как итог – разработчики реже обращаются к команде с вопросами и все счастливы.
- Также это помогает с мониторингом - собираем в виде метрики все коды ошибок и смотрим, каких кодов ошибок больше всего. Каких-то кодов ошибок в нормальное время быть не должно вообще, какие-то могут быть в незначительном объёме. А вот любые всплески могут говорить о том, что у нас не все хорошо. Вероятно плохой релиз, баги.. иными словами инцидент. Даже если всплесков нет, можно завести техдолг задачу или баг на исследование причины этих ошибок и устранение.
- Коды ошибок можно записывать в скоупы лога, чтобы смотреть флоу который привел к ошибке, искать пострадавших и т.п.
Для упрощения внедрения кодов ошибок в приложение, у меня есть библиотека на гитхабе с подробным описанием, которую я использую на работе во всех сервисах.
Коды ошибок, которые может вернуть API можно документировать в такой таблице (см в комментариях)
Чтобы проще ориентироваться в источнике ошибки, каждому сервису (домену) необходимо завести свой префикс 2-3 символа.
Нумерацию начинаем с нуля, дополняя до 5 цифр (будет всего 7-8 символов на код ошибки).
Таким образом каждый сервис сможет завести до 100к ошибок. Что вполне достаточно чтобы заводить код ошибки на каждый if
В проекте book library применяются коды ошибок, можно посмотреть как это работает