#coding-style #standards #web-standards
#стиль кодирования #стандарты #веб-стандарты
Вопрос:
В настоящее время я пишу API / несколько клиентов для шахматных игр.
Разработчики должны получить доступ к API через один скрипт (xhrframework.php ) и отправьте действия через GET . Возможно, что они допускают некоторые ошибки при отправке действий (не отправлен PHPSESSID, нет действительного PHPSESSID, перемещение было недопустимым, сейчас не их очередь, …).
Итак, я подумал о возможностях отображения ошибок. Мне пришло в голову несколько идей, как сообщить программисту, что он допустил ошибку:
- через сообщение об ошибке на понятном английском
- : Ясно, что должна означать ошибка
- : Может быть добавлена информация о том, как исправить эту ошибку
- -: Сообщение может измениться, поскольку мой английский не очень хорош
- -: Длина сообщения довольно сильно отличается — это может быть важно для программистов на C
- через константу сообщения об ошибке ab на английском языке — что-то вроде WRONG_PHPSESSID, MISSING_PHPSESSID, INVALID_MOVE, NOT_YOUR_TURN, …
- : Это понятно для человека
- 0: Почти уверен, что сообщение не изменится
- -: Длина сообщения может немного отличаться
- с помощью кода ошибки с одной таблицей в документации, где программист может найти значение кода ошибки
- : Код ошибки был бы постоянным
- : Длина каждого кода ошибки может быть одинаковой
- -: Это загадочно
Я думаю, что третье решение может быть хорошей идеей, поскольку xhrframework.php должен быть доступен только программисту, который, вполне возможно, уже ознакомился с документацией API.
Теперь я хотел бы знать, существует ли стандарт для сообщений об ошибках Web-API. Как другие (например, Google Maps API) решили это? Должен ли я просто вывести пустую страницу с содержимым «ОШИБКА: 004» или без заполнения «ОШИБКА: 4»?
Какие ошибки должны получать какие номера? Имеет ли смысл группировать ошибки по их номерам, например, все ошибки, начинающиеся с 1, были ошибками аутентификации, все ошибки с двумя ошибками игровой логики? Было бы лучше начать с ошибки 1 и использовать каждое число?
Google Maps API
Если я выполняю неправильный вызов JS-API Карт Google, он возвращает Java-Script с сообщением на чистом немецком языке (поскольку я живу в Германии, я полагаю).
API статических карт Google возвращает сообщение в виде текста на понятном английском языке, если я совершаю неправильный вызов.
Комментарии:
1. я знаю только это: en.wikipedia.org/wiki/HRESULT
2. Спасибо, Фло. Поскольку я не программирую на компьютере с Windows, это мне не очень помогает, но это дало мне представление о том, как я мог бы структурировать пользовательское сообщение об ошибке. Я раньше не думал о добавлении серьезности к своему коду ошибки.
3. Или, для половины мира, не использующей MS, у нас есть [ en.wikipedia.org/wiki/Errno.h ]
Ответ №1:
Большинство служб API используют систему кодов ошибок HTTP RFC2817 с диапазонами кодов ошибок для разных типов ошибок:
1xx: Informational - Request received, continuing process
2xx: Success - The action was successfully received, understood, and accepted
3xx: Redirection - Further action must be taken in order to complete the request
4xx: Client Error - The request contains bad syntax or cannot be fulfilled
5xx: Server Error - The server failed to fulfil an apparently valid request
В контексте API вы бы в основном использовали значения 4xx для обозначения условий ошибки, связанных с проверкой запросов. 49x обычно используются для условий ошибки безопасности.
Комментарии:
1. Это только для запроса, верно? Таким образом, запрос может быть успешным (2xx), но все еще может быть ошибка. В этом случае я бы последовал ответу @Nicholas Wilson
2. Вы могли бы использовать ту же схему нумерации для обработки ошибок. Итак, вы приняли запрос, но при обработке запроса вы столкнулись с ошибкой. Затем вы обрабатываете запрос о статусе запроса, который затем возвращает ошибку обработки.
Ответ №2:
Стандарта нет, и почему он должен быть? Программистам, использующим ваш интерфейс, уже приходится изучать это, что, по-видимому, является чем-то пользовательским, поэтому необходимость написания пользовательского кода обработки ошибок является лишь частью пакета.
Я бы посоветовал вам составить разумный формат, которого вы будете придерживаться. Вы могли бы использовать лучшее из каждого мира и включать несколько фрагментов информации в то, что вы возвращаете, возможно, примерно в этих строках:
[one of "ERROR" or "WARNING" or "MESSAGE"]
[error code with no spaces, eg "BAD_MOVE"]
[optional human readable string]
Таким образом, если изобретен новый тип ошибки, который старые клиенты не понимают, они все равно могут распознать, что возврат начинается с «ОШИБКА», и знать, что что-то пошло не так; путем синтаксического анализа кода ошибки (не используйте целые числа, это пустая трата времени каждого), они могут предпринять соответствующие действия, если программист принял во внимание ошибку. Наконец, если вы добавляете понятную строку для выбранных ошибок, это упрощает представление чего-то приятного пользователю или полезного для отладки.