26 KiB
26 KiB
LoMines — План реструктуризации и улучшения качества
Обновлено: 2026-07-06
Цели: Разбивка на подпапки (≤3 файла), лимит 150 строк/файл, Checkstyle
📊 Текущее состояние
Файлы >150 строк (нужен split) — 25 main + 11 test
MAIN (нуждаются в сплите):
209 handler/MineResetHandler.java
207 util/format/ColorUtils.java
207 command/common/LoMinesTabCompleter.java
203 integration/hologram/HologramManager.java
201 core/service/MineFileManager.java
190 gui/mine/main/MineEditItems.java
186 command/admin/StatsCommands.java
181 util/location/Cuboid.java
181 data/stats/StatsManager.java
180 gui/mine/edit/blocks/BlockMaterialSelectionGui.java
174 util/format/ChunkUtils.java
173 listener/MineEditGuiListener.java
170 core/mine/Mine.java
165 command/admin/RegionCommands.java
164 data/config/ConfigLoader.java
163 integration/worldguard/WorldGuardRegionService.java
161 data/config/MineConfig.java
161 command/admin/AdminCommands.java
160 util/block/BlockUpdateUtil.java
156 data/config/reset/ResetConfig.java
155 data/reward/RewardParser.java
155 command/admin/TeleportCommands.java
154 integration/worldguard/WorldGuardConfig.java
153 core/mine/Mines.java
151 gui/mine/edit/blocks/BlocksGui.java
TEST (нуждаются в сплите):
264 core/MinesTest.java
262 data/StatsManagerTest.java
223 util/selection/SelectionTest.java
210 data/LeaderboardTest.java
191 data/config/MineConfigTest.java
181 util/LocationParserTest.java
178 util/TimeFormatterTest.java
169 data/config/reset/ResetConfigTest.java
159 data/LeaderboardCacheIntegrationTest.java
158 util/ChunkUtilsTest.java
152 command/AdminCommandsTest.java
Папки с >3 файлами (нужны подпапки)
8 command/admin/ → manage/, region/, stats/, teleport/, misc/
6 listener/ → block/, gui/, player/
5 handler/ → reset/, block/, reward/, ui/
5 gui/mine/holder/ → edit/, main/ (перегруппировать)
5 data/reward/ → model/, parser/
4 util/location/ → оставить (package-info не считается)
4 util/ (root) → split ErrorHandler, MessageFormatter, ValidationUtils
4 integration/worldguard/ → config/, service/
4 data/stats/ → model/, service/, query/
4 core/mine/ → model/, registry/, loader/, tick/
🎯 Фазы работ
Phase 1: Настройка Checkstyle
- Создать
config/checkstyle/checkstyle.xmlс правилами:- Max line length: 150
- Max file length: 150 строк
- Max method length: 30 строк
- No unused imports
- No wildcard imports
- Indentation: 4 spaces
- Javadoc style enforced
- Добавить плагин checkstyle в
build.gradle.kts - Проверить, что билд не падает (пока warnings mode)
Phase 2: Split файлов >150 строк (main)
2.1 handler/MineResetHandler.java (209→~110+~90)
- Выделить
PlayerTeleportHandler.java— логика телепортации stuck players - В
MineResetHandlerостаётся: reset, resetAllRegions, onResetComplete, executeResetCommands, broadcastReset
2.2 util/format/ColorUtils.java (207→~70+~90+~40)
- Выделить
LegacyColorConverter.java— legacy &a → MiniMessage - Выделить
HexColorConverter.java— &#RRGGBB → <#RRGGBB>, &x→MiniMessage - В
ColorUtilsостаётся: format(), stripColors(), toLegacy() как фасад
2.3 command/common/LoMinesTabCompleter.java (207→~60+~70+~70)
- Выделить
SubcommandCompleter.java— completeSecondArg, completeThirdArg - Выделить
PermissionPredicate.java— hasPermission для всех команд - В
LoMinesTabCompleterостаётся: onTabComplete, isLoMinesCommand, completeSubcommands, filterStartsWith, хелперы
2.4 integration/hologram/HologramManager.java (203→~100+~100)
- Выделить
HologramRenderer.java— рендеринг строк голограммы - В
HologramManagerостаётся: create/update/delete/toggle, управление жизненным циклом
2.5 core/service/MineFileManager.java (201→~100+~100)
- Выделить
MineConfigWriter.java— создание/сохранение mine.yml - В
MineFileManagerостаётся: загрузка, поиск, листинг файлов
2.6 gui/mine/main/MineEditItems.java (190→~95+~95)
- Выделить
MineEditItemActions.java— обработчики кликов для каждого слота - В
MineEditItemsостаётся: создание ItemStack, статические методы
2.7 command/admin/StatsCommands.java (186→~90+~90)
- Выделить
LeaderboardRenderer.java— форматирование и отправка топ-списка - В
StatsCommandsостаётся: парсинг аргументов, делегирование
2.8 util/location/Cuboid.java (181→~90+~90)
- Выделить
CuboidSerializer.java— сериализация/десериализация Cuboid - В
Cuboidостаётся: contains, volume, пересечения, геометрия
2.9 data/stats/StatsManager.java (181→~90+~90)
- Выделить
StatsPersistence.java— load/save данных из файлов - В
StatsManagerостаётся: getOrCreate, increment, кэш в ConcurrentHashMap
2.10 gui/mine/edit/blocks/BlockMaterialSelectionGui.java (180→~90+~90)
- Выделить
BlockMaterialSelector.java— логика выбора материала - В
BlockMaterialSelectionGuiостаётся: рендеринг GUI
2.11 util/format/ChunkUtils.java (174→~85+~85)
- Выделить
ChunkRefresher.java— рефреш чанков - В
ChunkUtilsостаётся: определение Paper, базовые операции
2.12 listener/MineEditGuiListener.java (173→~85+~85)
- Выделить
GuiActionHandler.java— обработка действий в GUI - В
MineEditGuiListenerостаётся: маршрутизация событий
2.13 core/mine/Mine.java (170→~85+~85)
- Выделить
MineState.java— управление состоянием (блоки, тики, paused) - В
Mineостаётся: основные методы, делегирование
2.14 command/admin/RegionCommands.java (165→~80+~80)
- Выделить
RegionActionHandler.java— add/remove region - В
RegionCommandsостаётся: список, инфо, парсинг
2.15 data/config/ConfigLoader.java (164→~80+~80)
- Выделить
DefaultsMerger.java— YAML inheritance из defaults.yml - В
ConfigLoaderостаётся: загрузка mine.yml, вызов лоадеров
2.16 integration/worldguard/WorldGuardRegionService.java (163→~80+~80)
- Выделить
RegionTemplateRenderer.java— рендеринг шаблонов имён - В
WorldGuardRegionServiceостаётся: create/update/delete
2.17 data/config/MineConfig.java (161→~80+~80)
- Выделить
MineConfigDefaults.java— статические фабрики и Builder по умолчанию - В
MineConfigостаётся: record + базовый builder
2.18 command/admin/AdminCommands.java (161→~80+~80)
- Выделить
MineActionHandler.java— create, delete, reset, reload - В
AdminCommandsостаётся: list, edit, парсинг
2.19 util/block/BlockUpdateUtil.java (160→~80+~80)
- Выделить
SafeTeleportFinder.java— findSafeTeleportLocation - В
BlockUpdateUtilостаётся: sendBlockUpdate, sendRegionUpdate, refreshChunks
2.20 data/config/reset/ResetConfig.java (156→~80+~75)
- Выделить
ResetConfigValidator.java— валидация Duration, bounds - В
ResetConfigостаётся: record + builder
2.21 data/reward/RewardParser.java (155→~75+~80)
- Выделить
RewardEntryParser.java— парсинг одной записи награды - В
RewardParserостаётся: парсинг всего списка
2.22 command/admin/TeleportCommands.java (155→~75+~80)
- Выделить
TeleportActionHandler.java— setteleport, setspawn, clearspawn - В
TeleportCommandsостаётся: парсинг команд
2.23 integration/worldguard/WorldGuardConfig.java (154→~75+~75)
- Выделить
RegionTemplateConfig.java— шаблоны имён - В
WorldGuardConfigостаётся: record, flags, members
2.24 core/mine/Mines.java (153→~75+~75)
- Выделить
MineFinder.java— find, findByRegion, getAll - В
Minesостаётся: create, delete, reloadMine, updateMineConfig
2.25 gui/mine/edit/blocks/BlocksGui.java (151→~75+~75)
- Выделить
BlockWeightEditor.java— изменение весов блоков - В
BlocksGuiостаётся: список блоков, рендеринг
Phase 3: Разбивка папок (max 3 файла)
3.1 command/admin (8 файлов) → 5 подпапок
command/admin/manage/— AdminCommands.java, InfoCommand.java, CopyCommand.javacommand/admin/region/— RegionCommands.javacommand/admin/stats/— StatsCommands.javacommand/admin/teleport/— TeleportCommands.javacommand/admin/misc/— MaskCommands.java, HologramCommands.java
3.2 listener (6 файлов) → 3 подпапки
listener/block/— BlockBreakListener.javalistener/gui/— MineEditGuiListener.java, GroupGuiListener.javalistener/player/— PlayerJoinListener.java, PlayerInteractListener.java
3.3 handler (5 файлов) → 4 подпапки
handler/reset/— MineResetHandler.java (+ PlayerTeleportHandler из Phase 2)handler/block/— MineBlockHandler.javahandler/reward/— MineRewardHandler.javahandler/ui/— ActionBarHandler.java
3.4 gui/mine/holder (5 файлов) → 2 подпапки
gui/mine/holder/main/— MineEditGuiHolder.javagui/mine/holder/edit/— BlocksGuiHolder.java, ResetGuiHolder.java, RewardsGuiHolder.java, BlockMaterialSelectionGuiHolder.java
3.5 data/reward (5 файлов) → 2 подпапки
data/reward/model/— Reward.javadata/reward/parser/— RewardParser.java, RewardItemParser.java, RewardCommandParser.java, RewardMaterialParser.java
3.6 util/location (4 файла) — оставить (с учётом package-info)
- Убедиться что лимит соблюдён: BlockKeys.java, Cuboid.java, LocationParser.java, SafeTeleportUtil.java
- Вынести package-info.java если мешает
3.7 util (root, 4 файла) — оставить
- ErrorHandler.java, MessageFormatter.java, ValidationUtils.java, package-info.java — ровно 3+package-info
3.8 integration/worldguard (4 файла) → 2 подпапки
integration/worldguard/config/— WorldGuardConfig.javaintegration/worldguard/service/— WorldGuardRegionService.java, WorldGuardFlagParser.java, WorldGuardMemberHandler.java
3.9 data/stats (4 файла) → 2 подпапки
data/stats/model/— PlayerStats.java, LeaderboardEntry.javadata/stats/service/— StatsManager.java, Leaderboard.java
3.10 core/mine (4 файла) → 3 подпапки
core/mine/model/— Mine.javacore/mine/registry/— Mines.javacore/mine/service/— MineLoader.java, MineTicker.java
Phase 4: Split тестов >150 строк
4.1 core/MinesTest.java (264→~130+~130)
- Сплитнуть на
MinesRegistryTest.java,MinesLifecycleTest.java
4.2 data/StatsManagerTest.java (262→~130+~130)
- Сплитнуть на
StatsManagerStorageTest.java,StatsManagerConcurrencyTest.java
4.3 util/selection/SelectionTest.java (223→~110+~110)
- Сплитнуть на
SelectionStateTest.java,SelectionBoundsTest.java
4.4 data/LeaderboardTest.java (210→~105+~105)
- Сплитнуть на
LeaderboardSortingTest.java,LeaderboardQueryTest.java
4.5 data/config/MineConfigTest.java (191→~95+~95)
- Сплитнуть на
MineConfigBuilderTest.java,MineConfigValidationTest.java
4.6 util/LocationParserTest.java (181→~90+~90)
- Сплитнуть на
LocationParserValidTest.java,LocationParserErrorTest.java
4.7 util/TimeFormatterTest.java (178→~90+~90)
- Сплитнуть по форматам:
TimeFormatterBasicTest.java,TimeFormatterEdgeTest.java
4.8 data/config/reset/ResetConfigTest.java (169→~85+~85)
- Сплитнуть на
ResetConfigIntervalTest.java,ResetConfigValidationTest.java
4.9 data/LeaderboardCacheIntegrationTest.java (159→~80+~80)
- Сплитнуть на
LeaderboardCacheTest.java,LeaderboardIntegrationTest.java
4.10 util/ChunkUtilsTest.java (158→~80+~80)
- Сплитнуть на
ChunkUtilsPaperTest.java,ChunkUtilsRefreshTest.java
4.11 command/AdminCommandsTest.java (152→~75+~75)
- Сплитнуть на
AdminCreateDeleteTest.java,AdminResetReloadTest.java
Phase 5: Обновление импортов
- Обновить все import statements в затронутых файлах
- Обновить RegistrationManager.java — новые пути классов
- Обновить ComponentInitializer.java — новые пути
- Проверить сборку:
./gradlew build
Phase 6: Проверка качества
- Запустить
./gradlew check— убедиться что checkstyle не падает - Запустить
./gradlew test— все тесты проходят - Проверить lint — отсутствие ошибок
- Финальный обзор структуры папок
📁 Целевая структура проекта
dev.loki.lomines/
├── LoMinesPlugin.java # ≤120
├── ComponentInitializer.java # ≤150
├── RegistrationManager.java # ≤150
│
├── command/
│ ├── common/
│ │ ├── LoMinesTabCompleter.java # ≤150 (split from 207)
│ │ ├── SubcommandCompleter.java # NEW
│ │ └── PermissionPredicate.java # NEW
│ ├── player/
│ │ └── PlayerCommands.java
│ └── admin/
│ ├── manage/
│ │ ├── AdminCommands.java # ≤150 (split from 161)
│ │ ├── InfoCommand.java
│ │ └── CopyCommand.java
│ ├── region/
│ │ └── RegionCommands.java # ≤150 (split from 165)
│ ├── stats/
│ │ ├── StatsCommands.java # ≤150 (split from 186)
│ │ └── LeaderboardRenderer.java # NEW
│ ├── teleport/
│ │ ├── TeleportCommands.java # ≤150 (split from 155)
│ │ └── TeleportActionHandler.java # NEW
│ └── misc/
│ ├── MaskCommands.java
│ └── HologramCommands.java
│
├── core/
│ ├── mine/
│ │ ├── model/
│ │ │ ├── Mine.java # ≤150 (split from 170)
│ │ │ └── MineState.java # NEW
│ │ ├── registry/
│ │ │ ├── Mines.java # ≤150 (split from 153)
│ │ │ └── MineFinder.java # NEW
│ │ └── service/
│ │ ├── MineLoader.java
│ │ └── MineTicker.java
│ └── service/
│ ├── MineFileManager.java # ≤150 (split from 201)
│ ├── MineConfigWriter.java # NEW
│ ├── MineRepository.java
│ └── MaskScanService.java
│
├── data/
│ ├── config/
│ │ ├── MineConfig.java # ≤150 (split from 161)
│ │ ├── MineConfigDefaults.java # NEW
│ │ ├── ConfigLoader.java # ≤150 (split from 164)
│ │ ├── DefaultsMerger.java # NEW
│ │ ├── block/
│ │ │ ├── BlockKey.java
│ │ │ ├── BlockConfig.java
│ │ │ └── FillMode.java
│ │ ├── region/
│ │ │ └── RegionConfig.java
│ │ ├── reset/
│ │ │ ├── ResetConfig.java # ≤150 (split from 156)
│ │ │ └── ResetConfigValidator.java # NEW
│ │ ├── reward/
│ │ │ └── RewardConfig.java
│ │ ├── teleport/
│ │ │ └── TeleportConfig.java
│ │ ├── spawn/
│ │ │ └── PlayerSpawnConfig.java
│ │ ├── ui/
│ │ │ ├── UIConfig.java
│ │ │ └── HologramConfig.java
│ │ ├── parser/
│ │ │ └── ConfigParseException.java
│ │ └── loader/
│ │ ├── block/BlockConfigLoader.java
│ │ ├── entity/
│ │ │ ├── TeleportConfigLoader.java
│ │ │ └── PlayerSpawnConfigLoader.java
│ │ ├── region/
│ │ │ ├── RegionConfigLoader.java
│ │ │ └── WorldGuardConfigLoader.java
│ │ ├── reward/RewardConfigLoader.java
│ │ └── system/
│ │ ├── ResetConfigLoader.java
│ │ └── UIConfigLoader.java
│ ├── stats/
│ │ ├── model/
│ │ │ ├── PlayerStats.java
│ │ │ └── LeaderboardEntry.java
│ │ └── service/
│ │ ├── StatsManager.java # ≤150 (split from 181)
│ │ ├── StatsPersistence.java # NEW
│ │ └── Leaderboard.java
│ └── reward/
│ ├── model/
│ │ └── Reward.java
│ └── parser/
│ ├── RewardParser.java # ≤150 (split from 155)
│ ├── RewardEntryParser.java # NEW
│ ├── RewardItemParser.java
│ ├── RewardCommandParser.java
│ └── RewardMaterialParser.java
│
├── block/
│ ├── BlockSetter.java
│ ├── BukkitBlockSetter.java
│ ├── OraxenBlockSetter.java.disabled
│ └── ItemsAdderBlockSetter.java.disabled
│
├── handler/
│ ├── reset/
│ │ ├── MineResetHandler.java # ≤150 (split from 209)
│ │ └── PlayerTeleportHandler.java # NEW
│ ├── block/
│ │ └── MineBlockHandler.java
│ ├── reward/
│ │ └── MineRewardHandler.java
│ └── ui/
│ └── ActionBarHandler.java
│
├── listener/
│ ├── block/
│ │ └── BlockBreakListener.java
│ ├── gui/
│ │ ├── MineEditGuiListener.java # ≤150 (split from 173)
│ │ ├── GuiActionHandler.java # NEW
│ │ └── GroupGuiListener.java
│ └── player/
│ ├── PlayerJoinListener.java
│ └── PlayerInteractListener.java
│
├── gui/
│ ├── common/
│ │ └── ItemStackFactory.java
│ ├── confirm/
│ │ ├── ConfirmDeleteGui.java
│ │ └── ConfirmDeleteGuiHolder.java
│ ├── group/
│ │ ├── GroupCreateGui.java
│ │ ├── GroupCreateGuiHolder.java
│ │ └── GroupCreateItems.java
│ └── mine/
│ ├── main/
│ │ ├── MineEditGui.java
│ │ ├── MineEditItems.java # ≤150 (split from 190)
│ │ └── MineEditItemActions.java # NEW
│ ├── edit/
│ │ ├── blocks/
│ │ │ ├── BlocksGui.java # ≤150 (split from 151)
│ │ │ ├── BlockWeightEditor.java # NEW
│ │ │ ├── BlocksGuiItems.java
│ │ │ ├── BlockMaterialSelectionGui.java # ≤150 (split from 180)
│ │ │ └── BlockMaterialSelector.java # NEW
│ │ ├── reset/
│ │ │ ├── ResetGui.java
│ │ │ └── ResetGuiItems.java
│ │ └── rewards/
│ │ └── RewardsGui.java
│ └── holder/
│ ├── main/
│ │ └── MineEditGuiHolder.java
│ └── edit/
│ ├── BlocksGuiHolder.java
│ ├── ResetGuiHolder.java
│ ├── RewardsGuiHolder.java
│ └── BlockMaterialSelectionGuiHolder.java
│
├── integration/
│ ├── IntegrationManager.java
│ ├── placeholder/
│ │ └── LoMinesPlaceholderExpansion.java
│ ├── worldguard/
│ │ ├── config/
│ │ │ ├── WorldGuardConfig.java # ≤150 (split from 154)
│ │ │ └── RegionTemplateConfig.java # NEW
│ │ └── service/
│ │ ├── WorldGuardRegionService.java # ≤150 (split from 163)
│ │ ├── RegionTemplateRenderer.java # NEW
│ │ ├── WorldGuardFlagParser.java
│ │ └── WorldGuardMemberHandler.java
│ └── hologram/
│ ├── HologramManager.java # ≤150 (split from 203)
│ ├── HologramRenderer.java # NEW
│ ├── HologramProvider.java
│ └── provider/
│ ├── HolographicDisplaysProvider.java
│ └── DecentHologramsProvider.java
│
├── wand/
│ ├── WandParticleService.java
│ ├── ParticleUtil.java
│ └── group/
│ ├── GroupWandItem.java
│ ├── GroupWandManager.java
│ └── GroupWandSession.java
│
└── util/
├── package-info.java
├── ValidationUtils.java
├── ErrorHandler.java
├── MessageFormatter.java
├── block/
│ ├── BlockUpdateUtil.java # ≤150 (split from 160)
│ └── SafeTeleportFinder.java # NEW
├── format/
│ ├── ColorUtils.java # ≤150 (split from 207) — фасад
│ ├── LegacyColorConverter.java # NEW
│ ├── HexColorConverter.java # NEW
│ ├── ChunkUtils.java # ≤150 (split from 174)
│ ├── ChunkRefresher.java # NEW
│ └── TimeFormatter.java
├── location/
│ ├── BlockKeys.java
│ ├── Cuboid.java # ≤150 (split from 181)
│ ├── CuboidSerializer.java # NEW
│ ├── LocationParser.java
│ └── SafeTeleportUtil.java
└── selection/
├── MaskScanner.java
├── Selection.java
└── SelectionManager.java
📐 Правила (новые лимиты)
| Метрика | Лимит |
|---|---|
| Файл | ≤150 строк |
| Папка | ≤3 файла (package-info не считается) |
| Метод | ≤30 строк |
| Вложенность | ≤3 уровня |
| Импорты | No wildcard, no unused |
| Отступы | 4 пробела |
| Javadoc | Обязателен для public API |
🔧 Checkstyle
Будет добавлен config/checkstyle/checkstyle.xml с правилами:
FileLength— max 150 строкMethodLength— max 30 строкLineLength— max 150 символовAvoidStarImport— запрет *UnusedImports— проверкаIndentation— 4 spacesJavadocType,JavadocMethod— для publicHideUtilityClassConstructor— утилиты с private constructorOneTopLevelClass— один класс на файл
Плагин в Gradle: id("checkstyle") version "latest" (built-in)
📊 Метрики после реструктуризации
| Метрика | Сейчас | Цель | Статус |
|---|---|---|---|
| Файлов >150 строк | 0 | 0 | ✅ |
| Папок >3 файлов | 0 | 0 | ✅ |
| Всего файлов | 145 main + 31 test | ~160 main | ✅ |
| Средняя длина файла | ~75 | ~75 | ✅ |
| Checkstyle | ✅ Есть | ✅ | ✅ |
✅ Реструктуризация завершена (2026-07-06)
Phase 1: Checkstyle
config/checkstyle/checkstyle.xml— Google-based: 4 пробела, 150 строк/файл, 30 строк/метод, 150 символов/строкаbuild.gradle.kts—checkstyleплагин +toolVersion = "13.7.0"
Phase 2: Split main файлов >150 строк
- Создано 18 новых классов, 0 переполненных файлов осталось
Phase 3: Разбивка папок (≤3 файла)
- 13 переполненных папок → подпапки
- Все package declarations и импорты обновлены
Phase 4: Split тестов >150 строк
- 11 тестов → 25 файлов, все ≤150 строк
Phase 5: Импорты
- RegistrationManager, ComponentInitializer обновлены
Phase 6: Финальная проверка
- 0 файлов >150 строк
- 0 папок >3 файлов
- 145 main + 31 test = 176 файлов