Чому строгий аналіз коду ламає збірку мобільного застосунку
Строгий аналіз коду ламає збірку не тому, що правила погані, а тому що їх вмикають поверх легасі. Команда додає в analysis_options.yaml набір рекомендованих лінтів, запускає flutter analyze — і отримує сотні попереджень на коді, який роками писався без перевірок.
CI-крок з аналізом стає червоним, релізна гілка не проходить, і перше, що робить команда, — вимикає правила, щоб рухатися далі.
Далі спрацьовує ефект храповика: правила вимкнені, попередження накопичуються, а нових порушень ніхто не бачить. Через кілька релізів аналізатор знову вмикають — і знову отримують лавину, тільки вже вдвічі більшу. Так строгий аналіз перетворюється на інструмент, який або блокує збірку, або не працює взагалі.
Корінь проблеми в тому, що строгий аналіз коду — це не бінарний перемикач, а режим із градацією. Частина правил ловить реальні дефекти: необроблені null, небезпечні приведення типів, забуті await в асинхронних викликах.
Інша частина — стилістика, яка не впливає на поведінку застосунку. Змішувати їх в одному прогоні й валити збірку на всьому одразу — означає губити сигнал серед шуму.
Робоча схема — розвести правила за рівнями: критичні помилки блокують збірку, попередження аналізатора збираються у звіт і не заважають релізу, стилістика виправляється поступово.
Тоді flutter analyze перестає бути джерелом падінь і стає інструментом контролю якості коду, який команда не вимикає при першому ж червоному прогоні. Нижче розбираємо, як налаштовується такий режим.
Що дає вибудувана конфігурація аналізатора
Строгий режим аналізатора — це не «галочка в конфігу», а набір правил, який команда свідомо посилює в міру зростання кодової бази.
На старті вмикаємо базовий набір лінтів і обов'язкову типізацію, потім додаємо правила на невикористані залежності, небезпечні приведення типів і забуті await.
Кожне посилення проходить через збірку — якщо правило ламає наявний код, воно або виправляється одразу, або йде у винятки з коментарем і терміном.
Перший вимірюваний ефект — час збірки. Мертвий код, дублі імпортів і циклічні залежності не проходять перевірку, тому в артефакт не потрапляє зайве.
На середньому проєкті це стабільно зрізає частину часу збірки й прибирає «плаваючі» падіння, які раніше ловилися тільки на пристрої.
Другий — частка відмов на етапі перевірки. Помилки типів, null-безпечність і необроблені винятки відсікаються до того, як код потрапить у рев'ю або на збірку.
Клас помилок, який раніше доходив до релізу — падіння на конкретних моделях пристроїв, некоректна робота зі станом, — закривається на рівні аналізу.
Третій — швидкість рев'ю. Коли стиль, типи й потенційні витоки перевіряє аналізатор, рев'юер витрачає час на логіку й архітектуру, а не на форматування. Це помітно скорочує цикл правок і знижує кількість повернень задачі.
Четвертий — стабільність релізу. Єдиний набір правил для всіх гілок і розробників прибирає розходження «у мене працює». Реліз збирається передбачувано, а відкат до попередньої версії не перетворюється на розбір причин.
П'ятий — передбачуваність підтримки. Новий інженер у команді отримує ті самі обмеження з першого дня, тому якість коду не залежить від того, хто саме пише модуль.
Підходи до налаштування Flutter Analyzer: порівняння режимів
Налаштування аналізатора — це вибір між швидкістю впровадження та суворістю контролю. Базовий набір правил виявляє очевидні помилки й майже не потребує супроводу, але пропускає небезпечні приведення типів і невикористаний код.
Розширений набір із кастомними лінтами закриває архітектурні домовленості команди, однак потребує часу на підтримку й навчання розробників.
Суворий режим із блокуванням збірки дає максимальну дисципліну: збірка падає на будь-якому порушенні, і в основну гілку не потрапляє код із технічним боргом. Зворотний бік — зростання кількості хибних спрацювань і спротив команди, якщо перейти до нього одним кроком.
Тому на практиці частіше обирають поетапне посилення: спочатку попередження, потім блокування за критичними правилами, і лише потім повний суворий режим.
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Базовий набір правил | Старт проєкту, невелика команда, швидкий вхід | Не виявляє архітектурні порушення, слабкий контроль типів |
| Розширений із кастомними лінтами | Зріла команда зі своїми домовленостями | Потребує підтримки лінтів, поріг входу для новачків |
| Суворий режим із блокуванням збірки | Критичний продукт, високі вимоги до якості | Хибні спрацювання гальмують релізи без тонкого налаштування |
| Поетапне посилення | Діючий проєкт із накопиченим боргом | Потрібен план переходу й контроль прогресу за етапами |
Вибір залежить від стану кодової бази: для нового проєкту розумно одразу закладати розширений набір, для працюючого — рухатися поетапно, фіксуючи борг і поступово переводячи правила з попереджень у блокуючі. Такий підхід знижує ризик, що суворий режим зупинить розробку в перший же день.
Як ми впроваджуємо строгий аналіз: етапи роботи
Починаємо з аудиту: дивимося поточний analysis_options.yaml, набір увімкнених правил, історію попереджень у репозиторії та те, як команда реагує на зауваження аналізатора.
Часто з'ясовується, що частину правил вимкнено «тимчасово» і вони залишилися такими на роки, а попередження ніхто не читає — отже, спочатку потрібно повернути довіру до інструменту, а не просто додати строгості.
- Аудит правил. Розбираємо, які перевірки вже працюють, які придушено через
// ignoreі чому. Рахуємо частку файлів із придушеннями — це показує реальні болючі точки кодової бази. - Проєктування конфігурації. Збираємо набір правил під проєкт: строгі перевірки типів, заборона неявних приведень, контроль невикористаного коду. Вмикаємо їх поетапно, щоб не обвалити збірку сотнями зауважень одразу.
- Налаштування винятків. Для згенерованого коду, сторонніх пакетів і legacy-модулів прописуємо точкові винятки замість глобальних вимкнень — так строгість зберігається там, де вона дає ефект.
- Інтеграція у збірку. Підключаємо аналізатор до локальної розробки та до перевірок у репозиторії: зауваження стають блокуючими для нових змін, але не ламають уже наявний код.
- Перевірка на реальних сценаріях. Проганяємо конфігурацію на актуальних гілках, дивимося частку хибних спрацювань і правимо пороги, поки сигнал не стане чистим.
- Передача команді. Фіксуємо правила в документації, показуємо, як читати звіт і як правильно придушувати перевірку, коли це справді потрібно.
Після впровадження нові помилки типів і потенційні падіння ловляться на етапі написання коду, а не в продакшені. Розбираємо, як це закривається на вашому проєкті.
Артефакти, які залишаються в команди після налаштування
Налаштування аналізатора — це не одноразова правка в редакторі, а набір файлів у репозиторії, які живуть разом із проєктом і переживають зміну розробників. Нижче — що саме залишається в команди на руках після того, як ми закриваємо задачу.
- Файли конфігурації аналізатора —
analysis_options.yamlу корені проєкту з підключеним набором правил і налаштуваннями строгого режиму. Файл версіонується разом із кодом: будь-яка зміна правил проходить через рев'ю і видна в історії. - Схема правил за рівнями строгості — розподіл на обов'язкові перевірки (помилки збірки), попередження та інформаційні підказки. Окремо фіксуємо, які правила увімкнені для нового коду і які тимчасово пом'якшені для успадкованого.
- Політика винятків — список файлів і каталогів, виведених з-під перевірок, із зазначенням причини та власника. Кожен виняток оформлено коментарем у конфігурації, а не мовчазним
ignoreу коді. - Регламент оновлення правил — порядок, за яким нові перевірки додаються: спочатку попередження, потім обов'язкова вимога. Це дає команді час розібрати накопичені зауваження без зупинки релізів.
- Документація для розробників — коротка інструкція: як запустити перевірку локально, як читати звіт, що робити при конфлікті правил і куди писати при спірному спрацюванні.
- Інтеграція в конвеєр збірки — налаштована перевірка на етапі збірки, яка не пропускає зміни з критичними зауваженнями. Поріг задано так, щоб збірка падала на реальних дефектах, а не на стилістиці.
- Базовий звіт за поточним станом — зріз по проєкту на момент передачі: скільки зауважень, які категорії переважають, що закривається в першу чергу.
Ці артефакти залишаються в репозиторії і не залежать від нас: команда може змінювати правила, додавати винятки та розширювати перевірки самостійно. Опишіть задачу — повернемося з оцінкою та планом, що з цього списку вже є у вас, а що ще належить зібрати.
Кейс: як суворий режим прискорив збірку та знизив кількість відмов
Клієнт прийшов із застосунком на Flutter, який збирався 22 хвилини на кожен коміт в основну гілку, а падіння в продакшені приходили пачками раз на тиждень.
Команда з шести розробників витрачала на очікування збірок майже день на тиждень, а черговий інженер — ще півдня на розбір завалених релізів.
Що було до впровадження
Аналізатор працював у м'якому режимі: попередження не блокували збірку, а частину правил взагалі було вимкнено, щоб «не заважати».
У результаті в кодову базу просочувалися необроблені винятки під час роботи з мережею та розбором відповідей сервера — саме вони давали більше половини падінь. Кожен такий дефект знаходили вже на пристрої користувача, а не на етапі перевірки.
Що змінили
Ми увімкнули суворий набір правил аналізатора і зафіксували його в конфігурації проєкту, щоб налаштування не розходилися між машинами розробників і складальним сервером.
Правила, що ловили необроблені винятки та потенційні звернення до порожніх значень, перевели в розряд блокувальних: збірка зупиняється, поки зауваження не усунено.
Окремо налаштували розбір попереджень за рівнями — те, що не впливає на надійність, залишили як підказки і не гальмуємо ними конвеєр.
Що стало після
Час збірки скоротився з 22 до 14 хвилин: частину важких перевірок перенесли на етап аналізу, і повторні прогони перестали перезбирати незмінені модулі.
Клас помилок із необробленими винятками зник із продакшену повністю — за три місяці після впровадження не прийшло жодного падіння цього типу. Частка дефектів, які ловляться до релізу, зросла приблизно вдвічі, а черговий інженер перестав розбирати аварійні релізи по вихідних.
Важливий момент: суворий режим працює, тільки якщо правила однакові в усіх і закріплені в репозиторії. Інакше налаштування живуть у головах, а не в проєкті, і через місяць усе повертається до початкового стану.
Чим відрізняється строгий режим аналізатора від звичайного набору правил?
Звичайний набір правил — це список рекомендацій, який аналізатор показує в редакторі та у звіті перевірки. Розробник бачить попередження, оцінює його і вирішує сам: виправити зараз, відкласти чи проігнорувати.
Формально код проходить, збірка збирається, реліз вирушає — попередження залишається висіти в черзі. Через місяць таких «відкладених» накопичуються сотні, і звіт перестає читати будь-хто, крім самого аналізатора.
Строгий режим змінює статус порушення: правило переводиться з підказки в умову, за якої збірка не збирається.
Різниця не в кількості правил, а в точці, де спрацьовує обмеження. Звичайний набір працює після факту — на рев'ю, на розборі, на наступному спринті, коли контекст уже втрачено.
Строгий режим спрацьовує до факту: конвеєр перевірок зупиняється на етапі аналізу, і код із порушенням фізично не потрапляє ні в основну гілку, ні в збірку для тестування. Це принципово інший клас зворотного зв'язку — не «потім розберемося», а «зараз не пройде».
Дисципліна команди тримається не на домовленостях, а на тому, що порушення не можна обійти непомітно. Коли правило блокує збірку, у розробника два шляхи: виправити або явно й обґрунтовано виключити випадок із позначкою в коді.
Друге видно на рев'ю і обговорюється — виключення стає усвідомленим рішенням, а не тихим ігноруванням. Так набір правил перестає бути побажанням і стає частиною контракту на якість коду.
Є й ціна: строгий режим вимагає, щоб правила були вивірені під проєкт. Занадто широкий набір блокує збірку на нешкідливих місцях, і команда починає шукати обхідні шляхи замість роботи.
Тому вмикаємо його поетапно — спочатку на новому коді, потім на змінюваних файлах, і лише потім на всій кодовій базі.
Технічні сумніви та відповіді щодо налаштування аналізатора
Налаштування аналізатора майже завжди впирається в одні й ті самі технічні питання: чи не зламає строгий режим наявний код, чи не сповільнить збірку, що робити з хибними спрацюваннями та як підтримувати правила в актуальному стані. Нижче — відповіді на кожне.
Сумісність: увімкнемо строгий режим — проєкт перестане збиратися?
Ні, якщо впроваджувати правила поетапно. Спочатку фіксуємо поточний стан як baseline і вмикаємо нові перевірки лише для змінюваних файлів, а не для всієї кодової бази одразу. Легасі-модулі залишаються в режимі попереджень, новий код пишеться вже за строгими правилами. Так строгий режим не блокує релізи, а борг скорочується в міру правок.
Як це впливає на швидкість збірки та роботу в редакторі?
Аналіз виконується інкрементально: перевіряються змінені файли, а не весь проєкт. На холодному прогоні час зростає незначно, у повсякденній роботі різниця непомітна.
Якщо проєкт великий, розносимо правила за рівнями — швидкі перевірки на кожне збереження, важкі (наприклад, аналіз зв'язності) виносимо в окремий крок перед збіркою.
Що робити з хибними спрацюваннями?
Кожне придушується точково: рядок з обґрунтуванням у коді або запис у конфігурації із зазначенням причини, а не вимкнення правила цілком.
Ми ведемо список винятків і періодично його ревізуємо — якщо правило дає шум на кількох місцях, частіше проблема в самому правилі або в архітектурі, а не в коді.
Як оновлюються правила і чи не зламає це проєкт?
Правила живуть у репозиторії разом з кодом, зміни проходять рев'ю. Оновлення версії аналізатора тестуємо на окремій гілці: дивимося, скільки нових зауважень з'явилося, і вирішуємо — виправити одразу чи внести в план. Так оновлення не перетворюється на несподіваний стоп для команди.
Обговоримо ваше завдання з налаштування Flutter Analyzer
Налаштування Flutter Analyzer починається не з правки конфігурації, а з розбору вашого проєкту: які правила вже увімкнені, де аналізатор мовчить, а де видає сотні попереджень, які команда звикла ігнорувати.
Від цього залежить, чи увійде строгий режим безболісно, чи перетвориться на джерело конфліктів у код-рев'ю.
Щоб повернутися з оцінкою та планом старту робіт, нам потрібно від вас небагато:
- репозиторій або його фрагмент із поточним
analysis_options.yaml; - список проблем, які вже заважають: хибні спрацювання, пропущені помилки, розбіжності між розробниками;
- як влаштований процес перевірки коду — що запускається локально, що в загальній збірці;
- які правила команда готова прийняти одразу, а які потребують перехідного періоду;
- версії актуальної гілки Flutter і Dart, щоб правила та лінтери були сумісні;
- хто з боку замовника ухвалює рішення щодо спірних правил.
Далі наші інженери пройдуть кроками: увімкнуть базовий набір правил, додадуть строгі перевірки типів і невикористаного коду, налаштують виключення для згенерованих файлів, розділять рівні строгості для нового та legacy-коду.
Після цього — прогін на реальній кодовій базі, щоб побачити, скільки зауважень з'явиться і які з них критичні.
За підсумками ви отримаєте оцінку трудовитрат, план поетапного увімкнення правил і розуміння, що зміниться в щоденній роботі команди. Опишіть завдання — повернемося з оцінкою та планом, обговоримо старт робіт і формат супроводу після впровадження.
