Рефакторинг запутанной структуры кода без сбоев в продакшене

Что на самом деле значит «запутанная» структура кода

Запутанная структура кода — это не просто «много файлов». Это когда расположение файлов перестаёт соответствовать тому, как работает продукт. Невозможно понять, где должно происходить изменение, и поэтому любая правка кажется рискованной.

В реальных репозиториях это обычно проявляется как смешение обязанностей: UI напрямую общается с базой данных, проверки аутентификации разбросаны по страницам, а папки utils тихо держат половину бизнес‑логики. Ещё один распространённый симптом — циклические импорты (A импортирует B, B импортирует A). Они могут вызывать странное поведение во время выполнения и подталкивать людей к костылям просто чтобы приложение запустилось.

Тишайшая проблема — это именование. Вы увидите три способа назвать одно и то же (userService, users.service, user_manager), или папки с бессмысленными именами (misc, temp, old2). Люди дублируют код, потому что не могут найти подходящее место, и беспорядок растёт.

Проблемы структуры вы чувствуете в ежедневной работе больше, чем на архитектурных диаграммах:

• Небольшие изменения занимают часы, потому что вы гоняетесь за зависимостями по всему репо.
• Баги повторяются, потому что фиксы попадают в одно место, а настоящая логика — в другое.
• Релизы пугают, потому что одна «мелкая» правка может сломать что‑то несвязанное.

Очистка оправдана, когда структура — основное, что замедляет вас или вызывает лишние баги. Если продукт стабилен, изменения редки и команда понимает текущую раскладку, большой рефактор может подождать. Чаще всего лучший подход — «трогать и убирать»: улучшать структуру только в той области, где вы уже меняете код.

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

Поставьте цели и правила перед тем, как трогать код

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

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

Согласуйте правила до первого коммита:

• Неприкосновенное: публичные API, схема базы данных, маршруты и ключевые UI‑пути, которые нельзя менять.
• Область: что входит в рамки работ, а что пока запретно.
• Временной лимит: чёткий предел (например, 2–3 дня) перед пересмотром плана.
• Проверки: какие проверки должны быть зелёными (тесты, линт, сборка и короткий smoke‑тест).
• Что значит «готово»: «эти папки очищены и документированы», а не «всё репо стало идеальным».

Пример: вы унаследовали приложение, сгенерированное AI, где аутентификация работает «большую часть времени», маршруты дублируются, а файлы живут в случайных местах. Ваши правила могут быть: не менять поток логина, cookie сессии и таблицы БД на этой неделе. Цель — просто собрать всё, что связано с auth, в один модуль и поместить файлы в одну папку с консистентными именами. Это даёт победу, которую можно отправить в прод без новой загадочной ошибки.

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

Быстрая карта текущей структуры (30–60 минут)

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

Начните с точек входа: где система «просыпается» и начинает работать. У многих приложений их несколько: веб‑сервер, планировщик задач, обработчик очередей, CLI‑скрипт и иногда миграционный раннер.

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

Держите простую карту под рукой во время работы:

• 3–6 точек входа (что запускается первым и как)
• 5–10 часто меняющихся файлов или папок (куда постоянно попадают изменения)
• 3–5 зависимых «горячих точек» (импортируемые многими модулями)
• Одно предложение про назначение каждой топ‑левел папки (даже если формулировка некрасивая)

Горячая точка зависимостей — это место, где рефакторы умирают. Признак — один файл utils, который содержит хелперы для аутентификации, форматирования дат, код работы с БД и API‑клиентов. Если он импортируется везде, то каждое изменение рискованно.

Карта должна быть честной, а не красивой. «src/helpers: случайные вещи, которым не нашли место» — это полезная запись. Позже вы превратите её в план.

Определите границы папок, которые снижают связанность

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

Выберите модель папок, которую сможете объяснить в одно предложение

Поставьте самую простую модель, которая совпадает с мышлением команды:

• По фиче: всё для «billing» лежит вместе (UI, логика, данные).
• По слоям: ui/, domain/, data/ отдельно, а фичи внутри них.
• Гибрид: верхний уровень — папки по фичам, внутри — ui/, domain/, data/.

Любая из этих моделей может работать. Важно, чтобы на вопрос «куда положить файл?» был очевидный ответ.

Напишите простые правила, что куда помещать

Определите границы простым повседневным языком. Например:

• UI: компоненты, экраны, формы и логика отображения.
• Domain: бизнес‑правила и решения (расчёт цены, проверки прав).
• Data access: API‑клиенты, запросы к БД и слой персистенции.

Добавьте короткий список «не пересекать», чтобы случайно не создать новую связанность:

• UI не импортирует напрямую слой доступа к данным.
• Domain не импортирует UI.
• Никаких прямых SQL‑вызовов вне слоя доступа к данным.
• Секреты из окружения читаются только из одного config‑модуля.
• Никакая фича не лезет в внутренности другой фичи.

Простой сценарий: если экран оформления заказа нуждается в итоговой сумме, он должен вызывать функцию домена (например, calculateTotal). Эта функция может обращаться к data access через небольшой интерфейс, а не через голый SQL или прямой API‑клиент.

Наконец, решите за владение: назначьте ревьюера (или небольшую группу) для каждой области, чтобы нарушения границ ловились раньше.

Правила именования и простые правила, которые сохраняют порядок

Рефакторы часто терпят неудачу по банальной причине: люди не знают, куда положить новый файл, и беспорядок снова растёт. Правила именования звучат придирчиво, но они снимают ежедневные решения и прекращают «разрешение на одно исключение». Выбирайте правила, которые команда действительно будет выполнять. Если правило требует спора каждый раз — оно слишком сложное.

Несколько базовых вещей, которые стоит записать:

• Имена файлов и папок: выберите kebab‑case (user-profile.ts) или camelCase (userProfile.ts) и придерживайтесь одного стиля.
• Единственное или множественное: используйте, например, единственное для модулей (invoice/), множественное — только для коллекций (invoices/).
• Экспорт: отдавайте предпочтение именованным экспортам для общего кода; избегайте default‑экспортов без явной причины.
• Index‑файлы: либо запретите их, либо ограничьте их роль переэкспортом публичного API, чтобы импорты были предсказуемыми.
• Одна концепция — один файл: если файл вырос больше, чем на экран или два, разбейте его по ответственности.

Небольшой «золотой пример» папки полезнее длинной документации. Держите его маленьким и близким к тому, что вы чаще всего строите:

features/
  auth/
    api.ts
    routes.ts
    components/
      LoginForm.tsx
    index.ts

Когда кто‑то добавляет новый экран аутентификации, он может скопировать шаблон, не раздумывая.

Одно лёгкое правило для нового кода поможет рефакту прилипнуть, даже если уборка ещё не закончена:

• Новые файлы следуют новым правилам именования и живут в новых папках.
• «Трогай — убирай»: если вы меняете файл, переместите его в нужное место или исправьте имя.
• Никаких новых «ящиков для хлама» вроде misc.

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

Пошагово: безопасно извлечь один модуль

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

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

Последовательность безопасного извлечения

Начните с записи обещания нового модуля в одном предложении: что он делает и чего не делает. Затем:

• Защитите поведение интерфейсом. Один экспортируемый метод или класс обычно достаточно. Внутренности пока могут быть уродливыми; сделайте простой внешний API.
• Делайте небольшие коммиты. Обновляйте импорты по ходу. Если нужно переименовать вещи, делайте это после перемещения, чтобы диффы были читабельными.
• Проверяйте после каждого шага. Запускайте приложение и тесты. Если тестов нет — выполните короткую ручную проверку одного потока, который его использует.
• Удаляйте старый код последним. Только после того, как докажете, что от него никто не зависит (поиск импортов, проверка логов, подтверждение, что дубликатов нет).
• Добавьте пару сфокусированных тестов на границе. Обычно достаточно одного «счастливого пути», одного пограничного случая и одного случая ошибки.

Пример: вы видите три файла, которые чуть по‑разному отвечают на вопрос «пользователь залогинен?». Создайте модуль authSession с getSession() и requireUser(). Сначала эти функции вызывают старый код. Потом по мере переноса логика внутри модуля уезжает туда, вы обновляете вызывающие места по одному и добавляете 2–3 теста, которые фиксируют ожидаемое поведение.

Извлечение также обнажает скрытые связи: глобалы, смешанные обязанности, секреты в случайных файлах и «временные» хелперы, ставшие постоянными.

Как деплоить рефактор, используя инкрементальные PR

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

Держите PR маленьким и «скучным»

Стремитесь к одному типу изменения на PR: переместить одну папку, переименовать группу файлов или извлечь один модуль. Если хочется «ещё пару исправлений пока я тут», запишите их и сделайте отдельно.

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

Когда структура устаканится, делайте поведенческие изменения в отдельных PR (фиксы логики, изменения формы данных, обработка ошибок). Смешивание структуры и поведения — это путь к загадочным багам.

Пишите описания PR, которые помогают ревьюерам проверить изменения

Упростите ревью, добавив в описание:

• Что изменилось (одно предложение)
• Риск (что может сломаться и где)
• Как проверить (короткий ручной тест и ключевые автоматические проверки)
• План отката (обычно «revert this PR»)

Пример: «Перенёс код, связанный с auth, в modules/auth и обновил импорты. Риск: маршруты логина. Проверить: регистрация, вход, выход, обновление сессии.»

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

Сохраняйте поведение стабильным пока меняете структуру

Цель проста: приложение должно вести себя так же для пользователей. Большинство рефакторов терпят неудачу из‑за незаметных изменений поведения.

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

• Регистрация, вход, выход (и сброс пароля)
• Создание основного объекта в приложении (заказ, пост, проект, тикет)
• Обновление и удаление этого объекта
• Одно действие с деньгами (чек‑аут, счёт, смена подписки), если есть
• Одно сообщение (email, нотификация, webhook), если есть

Тесты — это страховочные тросы, не проект в себе. Если покрытие слабо, напишите 2–5 высокоценностных тестов вокруг перечисленных потоков и остановитесь. Пара end‑to‑end или интеграционных тестов поймает больше ошибок рефакторинга, чем десятки мелких unit‑тестов.

Следите за бесшумными провалами. Аутентификация может сломаться без явных ошибок (cookie, storage сессий, пути редиректа). Платёжные и email‑сценарии могут «успешно» завершаться, но колбэки не срабатывать. Очереди могут терять задачи, если имена задач или пути импортов меняются в процессе извлечения.

Делайте ошибки видимыми быстро. Убедитесь, что логи и ошибки собираются в одном месте и содержат достаточно контекста (ID пользователя, ID запроса, имя задачи). Во время рефактора добавьте несколько целевых лог‑строк вокруг критичных границ (auth, биллинг, исходящие письма), а после стабилизации уберите их.

Частые ловушки, которые сводят рефакторы на нет

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

Ловушка «оно ведь собирается»

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

Более безопасный паттерн — держать стабильные точки входа (например, index‑файл на модуль, который определяет публичный API) и менять внутренние пути за этой границей.

Также избегайте создания нового «ящика для хлама» как быстрого патча. Свежая папка misc через неделю превратится в то же самое. Если что‑то не имеет четкого места, считайте это сигналом, что границы неясны.

Скрытые «черные ходы» между модулями

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

Обычные «черные ходы» — кросс‑импорты (модуль A тихо импортирует B) и общие глобальные объекты (config, singletons, изменяемые кэши), которые позволяют коду лезть через границы.

Траппы, которые обычно портят качество ревью:

• Одновременное переименование многих файлов и символов вместе с перемещением папок
• Смешивание рефакторинга с новыми фичами
• Оставление и старого, и нового API «временно» и никогда не удалять старый путь
• Огромный PR, который ревьюеры могут только бегло просмотреть
• Невнимательное изменение поведения (например, изменение порядка middleware при переносе auth‑кода)

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

Быстрый чек‑лист для каждого PR по рефакторингу

Маленькие PR — это способ реорганизовать структуру без превращения продакшна в поле догадок.

До открытия PR

Если вы не можете объяснить изменение в двух предложениях, PR, вероятно, слишком большой.

• Ограничьте объём одной проблемой границы, одним набором переименований или одним перемещением модуля.
• Перечислите точки входа, которые можете затронуть (маршруты, CLI, фоновые задания, импорты из других пакетов).
• Запишите план отката (обычно «revert this PR»; иногда — совместимая экспорт‑прослойка на один релиз).
• Запустите линт и тесты локально и запишите 2–3 дымовые проверки.
• Проверьте, что поведение не изменилось, если только заголовок PR не говорит иное.

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

После открытия и слияния PR

Сделайте быструю проверку перед следующим шагом:

• Убедитесь, что не появились циклические импорты (сборка и проверка зависимостей обычно это покажут).
• Удалите временные папки, созданные при переносе, или переименуйте их в финальные.
• Убедитесь, что команда согласовала, куда теперь идут новые файлы (короткий комментарий в PR обычно достаточно).
• Обновите простые заметки: короткий README в папке или комментарий о назначении папки.
• Подтвердите, что PR не изменил публичные API молча (экспорты, пути файлов, которые импортируют другие пакеты).

Следующие шаги: сохраняйте инерцию (и знайте, когда просить помощи)

Выберите одну маленькую реальную фичу и используйте её как путь доказательства. Если вы работаете с AI‑сгенерированным прототипом, часто пригодна следующая «вертикаль»: вытащить проверки auth из UI‑компонентов, собрать доступ к данным в один модуль и оставить UI только за отрисовкой.

Сначала рефакторьте одну вертикаль: например, «Вход → загрузить аккаунт → показать дашборд», сделайте её предсказуемой и надёжной. Вынесите проверки auth в одно место, сгруппируйте data access, а UI оставьте за отображением. Отложите большие дискуссии (переименование топ‑папок, смена фреймворка, идеальная доменная модель) на потом, когда будет инерция и страховочная сеть.

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

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

Если код пришёл из инструментов вроде Lovable, Bolt, v0, Cursor или Replit и вы тратите больше времени на распутывание, чем на разработку, FixMyMess (fixmymess.ai) может провести бесплатный аудит кода и указать самые рискованные зоны и безопасный порядок исправлений до того, как вы начнёте перемещать всё подряд.