Идемпо… что? Улучшаем API

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

Начало статьи Стажёр Вася и его истории об идемпотентности API очень метко характеризует этот термин:
Звучит сложно, говорят о ней редко, но это касается всех приложений, использующих API в своей работе.

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

Автор на примере приложения Такси и всего одной кнопки "Заказать такси" рассказывает о множестве подвохов, которые поджидают разработчика.

Из-за затупа с базой пользователь дважды нажал кнопку Заказать и приехало две машины.
Что ж, на фронте начали блокировать кнопку Заказать, пока не придет ответ с сервера.

Оказалось, этого не достаточно. Из-за проблем с сетью по таймауту возникла ошибка и клиентское приложение разблокировало кнопку Заказать. Но кто бы мог подумать... проблема проблемой, но до сервера запрос дошёл и даже выполнился. По итогу имеем снова две машины. Эту проблему поправили уже на беке, добавив пару if.

Проблема решена, можно заканчивать статью. А потом тарам-пам-пам... классика. Менеджер изменил бизнес требования и старое решение уже не подходит.

Тут-то автор и подходит к сути статьи. Ключ идемпотентности, что за зверь такой, как он поможет решить обозначенную проблему. Но не всё так просто, поэтому далее в статье раскрываются ещё несколько тонких моментов.

Когда я первый раз прочитал эту статью в далёком 19 году, то был в искреннем восторге, насколько доступно и на понятных примерах можно раскрыть тему. А классический пример с заказчиком: от "нам это не нужно абсолютно точно" до "срооооочно нужна эта фича" — просто вишенка на торте.
#skills

Зелёные потоки в Python

Переключение между потоками — процесс очень затратный по времени, как мы уже разбирали. Для решения этой проблемы были придуманы зелёные потоки (green threads, они же coroutines или корутины), у которых вместо честного переключения потоков операционной системой реализуется виртуальное переключение потоков в пользовательском пространстве. Для IO-bound задач, где бутылочным горлышком являются медленные операции ввода-вывода, в том числе сетевого, зелёные потоки являются спасением. Для CPU-bound задач, где надо много физически вычислять на процессоре и нет простоев зелёные потоки не нужны.

Предлагаем прочитать статью Асинхронный python без головной боли (часть вторая). Начинается статья с наглядного примера асинхронности из жизни. Часто у начинающих разработчиков можно наблюдать ошибку, когда вместо подписки на событие, например, изменения файла, реализуется "жужжалка", которая в бесконечном цикле дёргает метаданные файла, загружая CPU на 100%.

Дальше на примере показывается async-await с разными нюансами, в том числе с необходимостью асинхронных функций. Потом показывается взаимосвязь корутин и генераторов, асинхронные контекстные менеджеры и приложение, которое асинхронно что-то делает с сервисом погоды.

Во второй части речь про event loop, про пример с API gateway, дополнение сервиса погоды переводчиком, асинхронным логгированием и базой.
#python

Практичный SSH (с картинками)

Статья A visual guide to SSH tunnels (перевод) рассказывает о практическом применении SSH-туннелей в различных интересных конфигурациях. О базовом устройстве SSH под капотом мы писали ранее.

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

Если вам нужно:
– получить доступ к удалённому ресурсу, размещенному в частной сети

– открыть доступ к локальному серверу разработки через публичную сеть

– получить доступ к Git-репозиторию в частной сети, к которой нет доступа из интернета, но есть выделенный сервер из этой сети, который смотрит наружу

Эти и некоторые другие сценарии подробно раскрываются в статье.

Завершается статья набором настроек, которые позволят сделать SSH-туннели более надежным в случае разрыва соединения по таймауту или в случае сетевого сбоя.
#skills

Доработать нельзя переписать

Где поставить запятую в заголовке?

Стратегия "Доработать нельзя, переписать" свойственна молодым и неопытным разработчикам. Проще выкинуть старый код и написать новый, хороший и правильный.

Более опытные разработчики скажут "Доработать, нельзя переписать". Они знают цену кода, который уже кто-то написал и отладил. Предыдущий автор уже через боль и страдания создал работающее решение. Костыли в этом коде появились не просто так.

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

В классической статье Грабли, на которые не стоит наступать (оригинал) Джоел Спольски рассуждает о вопросе выше. Он вспоминает о браузере Netscape, который умер в результате переписывания. Одной из причин желания всё переписать Джоел видит сложность чтения кода. С этим тяжело не согласиться. Остальные детали в статье.

Наш опыт. При работе со старым проектом сопротивляйтесь желанию выкинуть и переписать. Безопасно переписывать можно, если вложения трудозатрат в проект меньше пары человеко-месяцев. Для более крупных проектов нужны вменяемые основания для выбрасывания имеющейся кодовой базы. Десять раз подумайте.

Мы уже рекомендовали другие статьи Спольски: Верблюды и резиновые уточки и закон дырявых абстракций.
#devfm #procode

Давай-давай, пиши документацию

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

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

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

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

— Установка и запуск. В этой части указываем набор команд, которые необходимо выполнить, чтобы запустить проект.
Подробность описания должна быть такая, чтобы при первом знакомстве с проектом разработчик скопировал из ридми команды и без матерных выражений запустил проект.

И, конечно, мы всё запускаем в докере. О важности докера у нас есть отдельный пост.

В этом же разделе также важно описать, как запускать тесты. Очень важно.

— Переменные окружения и опции. Сложный проект требует настройки, поэтому обязательно указываем набор переменных окружения, которые нужны в проекте, с описанием их назначения и дефолтными значениями.

— В разделе "другое" пишем о каких-то специфичных для проекта моментах. К таким особенностям может относится, например, накатывание миграций.

Последнее в нашем списке хорошо задокументированного проекта — тесты. Тесты являются самой актуальной документацией. В ридми можно забыть что-то поправить, а запуск тестов всегда показывает реальное поведение программы. Именно поэтому в ридми важно указывать, как запускать тесты.

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

И ещё мысль по поводу документации:
Считаем вредным советом или требованием писать документацию в каких-то сторонних системах, таких как конфлюенс (да, порой и такое требуют). Практика показала, что поддержание документации в актуальном виде в стороннем сервисе, мягко говоря, не работает. Очень сложно убедить и даже заставить разработчика поддерживать доку где-то в сторонней приблуде. С ридми проще — можно писать, не отходя от кассы. И контролировать легче, проверяя изменение доки в merge request.
#devfm #procode

Понимание джойнов сломано

Если в гугле ввести "join sql" и перейти в раздел картинок, можно увидеть повсеместные диаграммы Венна, цель которых – визуально пояснить суть разных видов join-ов.

В своей статье автор делает сенсационное заявление и идёт против системы. Он пытается объяснить, почему использование таких понятных всем кружочков неправильно объясняет работу join-ов.

Считаем эту статья важной, так как, одной стороны, да, действительно, привычные кружочки дают наглядное представление о join-ах, но на практике важны детали, которые в кружочках опускаются.

Как говорится, критикуешь — предлагай, поэтому в следующей статье автор предлагает свой вариант визуализации join-ов. Не сказал бы, что предложенный вариант прям сильно наглядный, однако более точный.
#skills #database

Backup: декабрь. Топ постов за месяц

1. Читаем документацию на примере FastAPI
2. Подборка базовых материалов для python-разработчиков на 2022 год
3. Kubernetes в небольших проектах
4. Регулярные выражения в Python от простого к сложному
5. Ищем свой пароль в файле размером 37 Гб на Python. В комментариях разгорелась дискуссия, заменит ли ChatGPT джунов
6. Хватит пересылать пароли в открытом виде
7. FastAPI best practices
8. Идемпо… что? Улучшаем API
9. Зелёные потоки в Python
10. Давай-давай, пиши документацию

#backup

Топ постов за год 🔝

1. Делаем код мягким и шелковистым

2. Преодолеваем постоянное откладывание дел

3. Стрим по созданию небольшого проекта на gitlab с тестами

4. Зачем вам нужен докер?

5. Завышать ли опыт в резюме?

6. Как я научился воспринимать английский на слух

7. Что я увидел в своих собеседованиях

8. Корчеватель ломает науку

9. Какие знания нужны разработчику?

10. Вопросы для junior python developer

11. Зачем WSGI в Python?

12. Проектируем сервис: поиск организаций по картам

#backup

Вспоминая git

В статье Top 30 Git Commands You Should Know To Master Git CLI собран набор часто используемых команд для работы с гитом. Некоторые из них достаточно очевидные, но со списком точно стоит ознакомиться.

Мы на практике часто используем команды:
7. посмотреть лог коммитов с изменениями
9. просмотреть изменения перед коммитом
11. переименовать файлы
13. внести изменения в последний коммит
15. откатить произвольный коммит
20. просмотреть лог коммитов в виде графа
24. просмотреть подробности об удаленном репозитории: push url, fetch url, какие ветки есть, какая ветка head
29. удалить ветку в удалённом репозитории

Хочется обратить внимание на вредность второго пункта. Автор рассказывает о способе сохранения своих учетных данных. Но это неправильный путь. Правильный путь — работать с удаленным репозиторием, применяя ssh-ключи. Не парольный способ. И если вдруг не настроена двухфакторка — её тоже стоит прикрутить.

От себя хочется добавить ещё одну полезную команду git stash. А если столкнулись со сложным случаем, то мы рекомендуем использовать sublime merge.

В копилку часто используемых команд добавим создание локальной ветки из удалённой
git checkout -t origin/some-branch
#skills

Кажется, ваше приложение сейчас пятисотит

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

Работает ли само приложение?
Не упала ли база?
А все ли странички в веб-приложении доступны?
Не просрочился ли сертификат?

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

Простая, как дверь и достаточно многофункциональная штука для проверки статуса ваших приложений, то есть классический health check.

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

Функционал, конечно, намного шире, чем в нашем коротком описании. Поэтому стоит ознакомиться с документацией в ридми проекта. Читается легко и сразу становится понятно, как работать с этой махарайкой.
#skills

Принципы, которыми стоит руководствоваться

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

Эти принципы даются с высоты Solution Architect. Мы выделили принципы, применимые для любого специалиста и которые сами постоянно применяем на практике.

Идти нужно от проблемы
Если для проблемы есть типовое решение — применяйте его. Не нужно пытаться что-то изобретать и применять какую-то новомодную штуку.

Наш совет — всегда осторожно относиться к внедрению новых технологий. Про внедрение новой технологии был отличный пост. Есть исключение — пет-проекты, где мы рекомендуем брать всё самое новое и интересное.

Решайте конкретную проблему
Всегда старайтесь узнать цель разрабатываемой системы, максимально дотошно допытывайтесь до требований. В статье хорошо проиллюстрирован этот тезис.

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

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

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

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

Многое, о чём говорит автор — знакомо и понятно. В статье есть еще несколько советов, а приятное изложение благоволит к прочтению :)
#sudo #edu

Авторизация через OAuth и OIDC

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

Иногда возникает необходимость самому реализовать авторизацию через сторонние сервисы (single sign-on). В каких-то случаях подобную функциональность из коробки предоставляет фреймворк, а вам нужно только правильно всё настроить. Но в задачах, связанных с безопасностью, важно знать, что происходит под капотом, и ничего не должно делаться на ощупь.

В замечательной статье An Illustrated Guide to OAuth and OpenID Connect по полочкам раскладывается эта тема. OAuth, OpenID Connect, кто на ком стоял, из каких шагов состоит и для чего каждый используется.

Также есть видео на понятном, неспешном английском.

Статья дает базовые знания, чтобы в голове появилась чёткая картинка об этих технологиях. Если необходимо погрузиться в тему, то в конце приводятся ссылки на другие, более глубокие статьи.

Мы считаем, что если разрабатываемая система позволяет не накручивать свою авторизацию, то не нужно этого делать. Не потому, что своё сложнее, а чтобы избавиться от проблемы и беспокойства хранения чувствительной информации пользователей, логинов, паролей в своем сервисе. Вспомните о десятках крупных утечек данных этого года и подумайте.
#skills #security

Пятничное развлекательное

Один день в неделю у нас "культурный код". Мы делимся интересным вне технических постов. Сегодня у нас "Жизнь" Конвея.

Это игра без игроков, созданная в 1970 году. Задаёшь начальное состояние и наблюдаешь. Правила просты:
— в каждой клетке либо есть жизнь, либо нет
— в пустой (мёртвой) клетке, с которой соседствуют три живые клетки, зарождается жизнь
— клетка живёт в компании 2-3 живых соседок. Если соседей меньше 2, то клетка умирает от одиночества. Если соседей больше 3, то клетка умирает от перенаселённости

Такие правила позволяют создавать удивительные вещи. Например, планер (glider) неизменно движется. Выше вы видите ружьё Госпера — это бесконечно растущая конфигурация, которая создаёт новые планеры, двигающиеся вниз-вправо. Есть неизменные фигуры — Райский сад и другие.

Эрик Реймонд (автор Собор и базар) предложил сделать планер эмблемой хакеров.

Игра жизнь встречается даже в пасхалках Google, о чём мы писали. Симулятор смотрите тут.

#fun

Кино на выходные

Посмотрел тут Не беспокойся, дорогая (2022) с Оливией Уайлд в качестве актёра и режиссёра. Что же, рейтинг в 6.6 на кинопоиске и 5.9 на imdb — это ещё завышенная оценка. Абсолютно бездарный фильм с кучей ружей Бондарчука, когда показывают деталь типа зомби-танцовщиц, которая никак дальше не используется и не развивается. После просмотра совершенно не о чем подумать и нечего обсудить. Смотреть не рекомендую.

С теплом вспоминал Тринадцатый этаж (1999), о котором мы давненько писали в подборке интересных фильмов. Фильм не очень динамичный по современным меркам, но в нём схожие вопросы поднимаются куда глубже, чем в поделке 2022 года. Блин, по ощущениям, треть хронометража в "Не беспокойся" показывают процесс уборки дома. Увлекательнее смотреть, как растёт трава.

Посмотрите Тринадцатый этаж, он того стоит. Или те фильмы подборки, что ещё не видели.

#fun #films

ООП на простых примерах

В 40-минутном видео аккуратно объясняют три кита объектно-ориентированного программирования. Примеры даны на TypeScript, но понятны любому разработчику. Автор аккуратно иллюстрирует необходимость ООП, рассказывает про инкапсуляцию, наследование и полиморфизм. Покрыты даже относительно сложные вещи вроде параметрического и ad-hoc полиморфизма.

На трёх китах ООП автор не заканчивает. Вторая половина ролика повествует о композиции и агрегации на примере автомобиля с двигателем и колёсами, об абстрактных классах и интерфейсах, и даже немного о дженериках. Завершает изложение реализация паттернов Dependency Injection и Singleton. При этом Singleton во многих случаях является антипаттерном и мы не рекомендуем его применять.

Обратите внимание, как автор умело использует IDE для автогенерации сеттеров и геттеров. Не забывайте, что IDE — ваш добрый друг, который много чего умеет.

Про нюансы getattr и setattr в питоне мы делали отдельные посты.

#sudo #youtube #procode

Индексы в PostgreSQL

До поры, до времени базами данных можно просто пользоваться, не особо вникая в детали работы. Но однажды что-то где-то начинает подтупливать. Тут-то и приходится разбираться.

У нас уже был заход про EXPLAIN. Теперь перейдем к более серьезным вещам, которые нужны при работе с реляционными базами, в частности, PostgreSQL — индексы.

Первая статья из цикла знакомит с особенностями применения индексов в PostgreSQL. Эти знания помогут лучше понимать и обосновывать, для чего и когда использовать индексы.

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

Для освоения статьи требуется полная сосредоточенность и погружение, понадобится неоднократно гуглить. В общем, чтиво как раз на воскресный денек :)

На этой статье можно не останавливаться. Далее в цикле нас знакомят с нюансами использования конкретных типов индексов: Hash, B-tree, GiST, SP-GiST, GIN и RUM, BRIN и Bloom.

Многие практически значимые детали, приведенные в статьях часто спрашиваются на собеседовании разработчиков уровня middle.
#skills #database