Установка

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

1. Выберите стратегию подключения

Есть два базовых сценария:

1. compileOnly/provided — если библиотека доступна в runtime окружении отдельно.
2. implementation + shading — если вы хотите поставлять всё внутри вашего плагина.

В большинстве случаев для плагинов удобнее implementation и аккуратная сборка итогового jar.

2. Подключение через Gradle (Kotlin DSL)

repositories {
    mavenCentral()
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.chi2l3s:next-lib:1.0.8")
}

Если используете compileOnly, убедитесь, что NextLib точно есть в runtime на сервере.

3. Подключение через Gradle (Groovy DSL)

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.chi2l3s:next-lib:1.0.8'
}

4. Подключение через Maven

<repositories>
  <repository>
    <id>jitpack</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.github.chi2l3s</groupId>
    <artifactId>next-lib</artifactId>
    <version>1.0.8</version>
  </dependency>
</dependencies>

5. JDBC драйверы (обязательно для Dynamic Database)

Без драйвера при DatabaseManager.register(...) вы получите ошибку Missing JDBC driver for ....

Рекомендуемые зависимости

dependencies {
    implementation 'mysql:mysql-connector-java:8.0.33'
    implementation 'org.postgresql:postgresql:42.7.3'
    implementation 'org.xerial:sqlite-jdbc:3.46.0.0'
}

Подключайте только те драйверы, которые реально используете.

6. Что выбрать: SQLite, MySQL, PostgreSQL

• SQLite:
  • плюсы: простой старт, один файл, минимум DevOps;
  • минусы: ограниченное масштабирование под высокую конкуренцию.
• MySQL/PostgreSQL:
  • плюсы: лучше под нагрузкой, удобнее админка, индексы/аналитика;
  • минусы: нужна отдельная инфраструктура.

7. plugin.yml и команды

CommandRegistry не создаёт команды автоматически. Команда должна существовать в plugin.yml.

name: MyPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
api-version: '1.16'

commands:
  myplugin:
    description: Main command
    usage: /myplugin

8. Минимальный bootstrap-проверочный код

@Override
public void onEnable() {
    NextLibContext context = NextLibContext.bootstrap(this);

    DatabaseManager manager = new DatabaseManager();
    DatabaseConfig cfg = DatabaseConfig.builder(DatabaseType.SQLITE)
        .file(getDataFolder() + "/database.db")
        .build();

    manager.register("main", cfg);

    getLogger().info("NextLib bootstrap ok");
}

Если этот код запускается без ошибок, базовая интеграция корректна.

9. Проверка после установки (чеклист)

1. Сервер стартует без stacktrace.
2. В логах нет Missing JDBC driver.
3. Папка плагина и i18n создана.
4. БД-файл (SQLite) или подключение (MySQL/PostgreSQL) работает.
5. Команда из plugin.yml зарегистрирована.

10. Частые ошибки установки

Ошибка: всё компилируется, но на сервере ClassNotFoundException

Причина: зависимость не попала в runtime jar.

Решение: проверить стратегию compileOnly vs implementation и shading-конфигурацию.

Ошибка: Failed to configure HikariCP pool

Причина: неверные параметры подключения/пула.

Решение: начать с минимального конфига и добавлять параметры по одному.

Ошибка: команда не работает

Причина: команда не объявлена в plugin.yml.

Решение: проверить commands секцию и имя в registerCommand.

11. Рекомендации по build-процессу

• фиксируйте версию NextLib явно (1.0.8), не используйте плавающие версии;
• держите JDBC версии совместимыми с вашей Java;
• в CI выполняйте минимум: lint + test startup scenario.

12. Что делать после установки

1. Быстрый старт
2. Dynamic Database
3. GUI API
4. Troubleshooting

После этого пути у вас будет рабочий фундамент без скрытых установочных ловушек.