Чек-лист проверки зависимостей перед добавлением новой библиотеки

Почему важна ещё одна библиотека

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

Каждый пакет добавляет код, который ваша команда не писала, не тестировала и не до конца понимает. Этот код всё равно работает в вашем приложении, обращается к данным и может ломаться так, что теперь именно вашей команде придётся искать причину.

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

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

Работа не заканчивается и после npm install или добавления пакета в lockfile. Поддерживающие проект люди выпускают новые версии, появляются ошибки, меняются API, а проблемы безопасности всплывают спустя месяцы. Ваша команда получает эту нагрузку на поддержку в тот самый момент, когда библиотека попадает в продакшен.

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

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

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

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

Начните с потребности

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

Сделайте это предложение узким и проверяемым. «Нам нужно обрабатывать CSV-файлы до 10 МБ на сервере» — понятно. «Нам нужно лучше работать с данными» — нет. Если потребность размыта, выбор библиотеки тоже будет размытым.

Потом проверьте, что у вас уже есть. Команды часто добавляют пакет ради работы, которую язык, браузер, фреймворк или стандартная библиотека уже выполняют достаточно хорошо. Это постоянно случается с форматированием дат, HTTP-запросами, UUID, небольшими утилитами и простой проверкой данных.

Сравните несколько реальных вариантов, прежде чем кто-то что-то одобрит:

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

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

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

Зафиксируйте решение, пока оно свежее. Запишите, кто его проверил, какие варианты вы сравнивали и почему команда сказала «да» или «нет». Короткой заметки в pull request достаточно. Через полгода она сэкономит время, когда кто-то спросит, зачем этот пакет вообще нужен.

Проверьте, кто его поддерживает

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

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

Откройте вкладку с issue и прочитайте несколько страниц, а не только цифры. Ищите сообщения о дырах в безопасности, сломанных установках, утечках памяти и конфликтах версий. Обратите внимание на вопросы без ответа, которые висят месяцами. Это часто говорит больше, чем аккуратный README.

Один поддерживающий человек — не автоматический отказ. Это риск, который нужно назвать прямо. Если один человек ведёт каждый релиз, каждый просмотр кода и каждый вопрос поддержки, ваша команда зависит от того, останется ли у него интерес и время. Для маленькой вспомогательной библиотеки это может быть нормально. Для чего-то глубоко встроенного в стек — обычно нет.

Заметки к релизам помогают увидеть ещё один паттерн: неожиданные поломки. Если каждый второй релиз меняет API, переименовывает параметры или без предупреждения прекращает поддержку, стоимость будущего обновления быстро растёт. Хороший чек-лист проверки зависимостей должен считать это риском поддержки, а не мелким раздражением.

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

Проверьте лицензию на соответствие вашим правилам

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

Большинству команд нужен короткий внутренний набор правил. Он может быть совсем простым: разрешено, разрешено после проверки и запрещено. MIT, BSD или Apache 2.0 часто проходят без особых сложностей. GPL или AGPL требуют более внимательного разбора, потому что могут повлиять на то, как вы распространяете ПО или сетевые сервисы.

Читайте не только название лицензии. Некоторые пакеты добавляют условия в README, отдельный файл NOTICE или коммерческое дополнение. Именно там команды и попадаются. Библиотека может быть бесплатной для личного использования, но не для коммерческой работы. Другая может требовать указания авторства в документации продукта или на экранах приложения.

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

• шрифтами
• иконками или изображениями
• примерами данных
• файлами моделей
• медиа-кодеками

У этих файлов могут быть другие условия, чем у кода вокруг них.

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

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

Посчитайте, сколько пакетов он тянет за собой

Библиотека редко приходит одна. Вы устанавливаете один пакет, а он может потянуть за собой ещё 15, 40 или 120 через транзитивные зависимости. Это быстро меняет картину проверки, потому что теперь ваша команда отвечает за риск всей этой цепочки.

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

Прежде чем кто-то поставит её в основную ветку, посмотрите на дерево зависимостей. Большинство менеджеров пакетов умеют показать, что придёт вместе с установкой, а манифест пакета часто выдаёт структуру стека.

Что обычно заслуживает более внимательного взгляда

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

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

Дубли — ещё одна тихая цена. У вас уже может быть одна библиотека для дат, один валидатор схем или один HTTP-клиент. Добавьте новую библиотеку с собственными фаворитами, и у вас появится два способа делать одну и ту же работу.

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

Хороший чек-лист проверки зависимостей должен воспринимать количество пакетов как индикатор будущей работы. Если библиотека решает маленькую проблему, но добавляет большое дерево, запишите число и сравните его с более простым вариантом или короткой внутренней обёрткой. Эта проверка на пять минут может сэкономить дни на очистке потом.

Измерьте размер и стоимость работы в рантайме

Библиотека может выглядеть маленькой в README и всё равно заметно ударить по приложению после установки. Проверяйте размер установленного пакета, а не маркетинговую цифру. Потом смотрите, что попадает в финальную сборку, потому что это часто совсем разные вещи.

Проводите тест на реальной сборке, а не на игрушечном примере. Добавьте пакет в настоящее приложение, соберите production-версию и сравните результат до и после. Так вы поймёте, действительно ли код отбрасывается при tree-shaking или побочные эффекты подтягивают больше, чем вы ожидали.

Короткий аудит размера бандла должен ответить на четыре простых вопроса:

• На сколько килобайт вырос финальный бандл?
• Загружается ли пакет при старте или только когда пользователь доходит до одного экрана?
• Растёт ли использование памяти после импорта или первого использования?
• Замедляет ли он холодный старт в serverless-среде или на мобильных устройствах?

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

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

Следите за побочными эффектами в настройках пакета. Если библиотека помечает файлы как содержащие побочные эффекты, ваш инструмент сборки может оставить код, который вы никогда не вызываете. Если она поставляется только в CommonJS, tree shaking может работать хуже, чем со сборкой в ESM.

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

Сначала посчитайте цену выхода, потом соглашайтесь

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

Хороший чек-лист проверки зависимостей должен задавать один простой вопрос: если эта библиотека начнёт создавать проблемы, насколько трудно будет её убрать? Если честный ответ — «больно», считайте это частью стоимости уже сейчас, а не потом.

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

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

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

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

• преобразование сохранённых данных
• переписывание тестов и фикстур
• изменение API-адаптеров
• обновление документации и привычек команды

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

Простой пример из небольшой команды

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

Они прогоняют короткий чек-лист проверки зависимостей и сравнивают три варианта:

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

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

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

Для реализации команда вводит одно правило: спрятать пакет за маленькой локальной утилитой. Приложение вызывает formatReportDate(), а не библиотеку везде подряд. Если в следующем году пакет перестанут поддерживать, изменится один файл, а не тридцать.

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

Частые ошибки при проверке

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

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

• Звёзды — слабый сигнал. У пакета может быть огромный счётчик на GitHub, но при этом устаревшие релизы, открытые проблемы безопасности и один уставший поддерживающий человек, который тащит всё на себе.
• Проверку лицензии часто оставляют на слишком поздно. Потом юристы или закупки вмешиваются прямо перед запуском, и команде приходится срочно менять код.
• Dev-зависимости игнорируют, потому что они не попадают к пользователям. Но они всё равно запускаются в CI, замедляют каждый конвейер и могут сломать сборку после небольшого обновления.
• Команды часто берут большой пакет ради одной маленькой утилиты. Полная библиотека дат для форматирования двух временных меток или огромный пакет утилит ради одной функции — обычно плохая сделка.
• Никто не планирует выход. Если функция меняется, библиотека остаётся и превращается в балласт, потому что никто не обернул её и не описал, как её убрать.

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

Исправление — не в большем количестве процессов. Оно в лучших вопросах. Проверьте поддержку, проверьте лицензию, посчитайте, что придёт вместе с пакетом, и перед мерджем задайте один прямой вопрос: если нам понадобится убрать это позже, насколько больно это будет?

Быстрые проверки перед мерджем

Новый пакет может выглядеть безобидно в pull request и всё равно создать месяцы лишней работы. Перед мерджем каждый раз проверяйте одни и те же пять вещей. Короткий чек-лист проверки зависимостей лучше длинной ветки комментариев.

• Сформулируйте точную проблему, которую решает библиотека, кто отвечает за это решение и почему ваш текущий код или инструменты уже не подходят.
• Подтвердите, что лицензия соответствует вашей политике. Если команде нужно одобрение юристов, остановите мердж, пока не получите его.
• Посчитайте транзитивные зависимости, а не только пакет, который вы ставите напрямую. Небольшое дерево легче отслеживать, обновлять и удалять.
• Измерьте стоимость в реальном приложении. Проверьте рост бандла, время запуска, использование памяти и любую дополнительную нагрузку на CPU или сеть.
• Добавьте в pull request одну заметку о выходе: как вы замените библиотеку позже, какой код от неё зависит и что может сделать удаление болезненным.

Небольшой пример помогает. Допустим, команда добавляет библиотеку для дат ради одной задачи форматирования. Сам пакет кажется маленьким, но он тянет локальные данные, добавляет 70 КБ в клиентский бандл и затрагивает код в шести файлах. Это не значит «отклонить». Это значит, что команде стоит записать, почему такой компромисс приемлем, или выбрать более лёгкий вариант.

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

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

Что делать дальше

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

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

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

Вам не нужно много:

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

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

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

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