Close

15.07.2019

Как правильно делать действительно плохие (веб) сервисы?

 

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

Документация API

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

Хотя, возможно, лучшей документацией на систему является ее исходный код (самодокументированный по определению), и совсем не важно, что front-end разработчик может не знать каких-то элементарных вещей, типа go, c++, haskell.

Желательно, чтобы документация не содержала примеры.

Валидация

Валидация входных данных – неоправданная роскошь (добавляет накладные расходы), к тому же часто является побочным эффектом использования инструментов генерации документации, Вам это не нужно.

Ошибки

API сервис всегда должен отвечать http кодом 200, ведь сообщение успешно доставлено. Собственные же коды ошибок – такая же роскошь, как и валидация, достаточно возвращать code: -1 или не возвращать никогда.

Все-таки, если коды ошибок приложения существуют, то в них не должны быть какой то логики, лучше всего для этого подойдет uuid.

Правильная работа со временем

Для начала обсуждения необходимо навсегда запомнить следующие вещи:

  • Системное время всегда корректно
  • Часовой пояс никогда не меняется
  • Разница между часовыми поясами всегда 3600 секунд

 

Лучший способ хранить datetime в БД: 

  • Взять текущее время – t = now()
  • Конвертировать t в timestamp (который, к сожалению, является UTC временем по стандарту, нам это не подходит)
  • Компенсировать полученный timestamp t текущим часовым поясом (t = t + zone * 3600)
  • Сохранять t в БД в виде Integer field
  • Страдать

Критические ошибки приложения

Знак качества сервиса – падения при неверном использовании, это приучает сторонних пользователей быть аккуратными и уважать чужое API (помним, что валидация не нужна).

Каждое падение обязательно должно сопровождаться записью дампа памяти на диск, без этого вы не сможете собрать 100 Гб дампов памяти за выходные, пока ваш качественный сервис автономно падает.

Опциональные аргументы

Пользователи сервиса всегда должны явно указывать все параметры при вызове метода. Опциональность == неуверенность.

Экономия на структурах

API метод принимает входные данные, отдает результат, но что если объединить эти две структуры данных в одну? Получится невероятная экономия (как минимум человеческих ресурсов) – в два раза меньше структур!

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

Нестандартные протоколы

HTTP, JSON, RPC – как много обыденности в этих словах, для решения действительно важных задач лучше всего подойдет свой собственный бинарный протокол поверх TCP, тем более если речь пойдет о нагрузке в десятки, а то и сотни запросов в секунду.

Логирование

Каждый плохой веб-сервис обязан не писать никакие логи, даже print в stdout. Каждый вызов логирования – сложная работа программиста и накладные расходы по времени.

Бизнес логика

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

Надежность внешних сервисов

Разрыв соединения между сервисами – настолько маловероятное событие, что нет смысла обрабатывать такие ошибки. Если бекенд «потерял» связь с БД, он не должен:

  • Падать
  • Пытаться переподключиться
  • Отвечать на внешние запросы

Выводы

Написать действительно плохой сервис – легко, достаточно выполнять некоторые (или даже все) вышеперечисленные пункты.

Авторы: Иван Селиверстов, Александр Шилов

One Comment on “Как правильно делать действительно плохие (веб) сервисы?

Михаил
05.08.2019 в 20:15

я, кажется, знаю заказчика , про которого эти правила. а что вы не всё то написали ?

а как же структуры данных с полями a,b,c,d , которые каждый раз в разных запросах и ответах имеют разный смысл ? естественно все они необходимы всегда, даже если не нужны и пустые — унификация же очень важна, зачем разводить опциональность(==неуверенность).

еще можно ввести состояния не бекенде, которые можно менять запросами. (иногда соединения отваливаются и тыне знаешь поменял или нет, ну ничего — ещё раз запросим и снова поменяем, подумаешь два одинаковых уведомления кому-то придет, разве это проблема?)

Ответить

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

Ваш e-mail не будет опубликован. Обязательные поля помечены *