Практический Cookbook

Этот раздел собран как книга рецептов: берёте задачу, находите паттерн, адаптируете под свой плагин.

Сценарий 1. Экономика игрока (баланс, магазин, транзакции)

Цель

Сделать стабильную экономику: хранить баланс в БД, показывать GUI-магазин, безопасно списывать валюту.

Шаги

1. Создайте PlayerWallet сущность с @PrimaryKey UUID playerId.
2. На PlayerJoinEvent выполняйте upsert (создать при первом входе).
3. В GUI на кнопке покупки используйте pipeline:
   • загрузить баланс,
   • проверить достаточность,
   • списать,
   • выдать предмет,
   • записать лог операции.
4. Все ошибки пользователя выводите через i18n-ключи.

Важные детали

• Баланс храните в long/int, а не в double.
• При частых покупках добавьте индекс по player_id.
• Не делайте дорогие DB операции в каждом InventoryClickEvent без кеша.

Сценарий 2. Ранги и права доступа

Цель

Управлять рангами через БД и синхронизировать с командами.

Паттерн

• Таблица player_ranks.
• Команда /rank set <player> <rank> через Command API.
• Валидация аргументов через Validation API.
• На успешное изменение публикуйте событие в MessageBus (rank.updated).

Что даёт MessageBus

• Один модуль меняет ранг,
• другой модуль ловит событие и обновляет кэш/таблицы/GUI,
• без жёстких зависимостей между классами.

Сценарий 3. Ежедневные квесты

Цель

Запустить daily-контент с сохранением прогресса.

Паттерн запуска

1. На старте зарегистрируйте квесты в QuestManager.
2. На входе игрока: restorePlayer(uuid).
3. В листенерах событий Bukkit вызывайте recordKill/recordCraft/....
4. На завершение objective выдавайте награду и сохраняйте состояние.

Антипаттерны

• Хранить весь прогресс только в памяти.
• Обновлять БД синхронно на каждый шаг без батчинга.
• Жёстко зашивать тексты квестов в Java-коде.

Сценарий 4. Горячий reload без рестарта

Цель

Перезагружать конфиги/GUI/локализацию на живом сервере.

Базовая схема

• reload.register("configs", ...)
• reload.register("guis", ...)
• reload.register("i18n", ...)
• команда /plugin reload вызывает reloadAll().

Практика качества

• Каждый reload-блок должен быть идемпотентным.
• Ошибка в одном блоке не должна «ломать» остальные.
• Результат ReloadReport всегда логируйте.

Сценарий 5. Наблюдаемость и диагностика

Цель

Понять, где тормозит плагин и почему.

Минимальный набор

• counter: commands.executed
• counter: db.errors
• timer: db.query.latency
• gauge: online.players
• health-check: database.connection

Что смотреть первым при проблеме

1. Health статусы.
2. Ошибки в structured logs.
3. Спайки таймеров.
4. Только потом deep dive в код.

Сценарий 6. Мультиязычные сообщения

Цель

Один код, несколько языков без хаоса.

Паттерн

• Все строки пользователя только через i18n.message(...).
• В ключи закладывайте доменную структуру:
  • command.rank.no_permission
  • shop.purchase.success
  • db.connection.failed

Правила

• Ключи неизменяемые после релиза.
• Аргументы шаблонов именуйте понятно ({player}, {amount}).
• Фолбэк-локаль всегда должна содержать полный набор ключей.

Сценарий 7. Безопасная миграция схемы

Цель

Эволюционировать таблицы без потери данных.

Подход

• Используйте withAutoMigrations(plugin) для базовых изменений.
• Для критичных случаев поддерживайте ручные SQL миграции.
• Каждую миграцию делайте reversible, если возможно.

Чеклист

• Бэкап перед выкатом.
• Прогон на staging-копии прод-данных.
• Замер времени миграции.
• План rollback.

Сценарий 8. Большой GUI-каталог

Проблема

Десятки меню, сложно поддерживать.

Решение

• Древовидная структура menus/ по доменам:
  • menus/main/
  • menus/shop/
  • menus/admin/
• Единые нейминги id.
• Общие элементы через шаблонные секции.
• Чёткое разделение «витрина» и «действия».

Сценарий 9. Конфиги как контракт

Цель

Чтобы конфиги не «падали» неожиданно после правок.

Практика

• Наследование от BaseConfig + валидация на загрузке.
• Явные default-значения.
• Логирование всех отсутствующих обязательных ключей.
• Мягкий fallback для необязательных настроек.

Сценарий 10. Production-hardening

Минимум перед релизом

• Профилирование горячих мест.
• Тест на 50-100 одновременных игроков (локально/стенд).
• Прогон стресс-сценариев команд и GUI кликов.
• Проверка корректного shutdown (без «висячих» потоков/подключений).

Operational playbook

• Инцидент: рост ошибок БД.
  • переключиться в degraded mode,
  • отключить тяжёлые функции,
  • собрать диагностический dump.
• Инцидент: GUI не открывается.
  • reload GUI,
  • проверка YAML синтаксиса,
  • проверка action/condition регистрации.

Архитектурные принципы, которые окупаются

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

Финальный чеклист проекта

• DB слой: есть сущности, индексы, миграции, закрытие соединений.
• GUI слой: есть каталогизация файлов, переиспользование блоков, error logging.
• Commands: валидация, права, автокомплит.
• i18n: покрыты все пользовательские строки.
• Reload: безопасный pipeline и отчётность.
• Observability: базовые метрики/health/logging.

Если сделать этот минимум, ваш плагин на NextLib будет масштабироваться в разы спокойнее.