Миграция существующего кода на модули Java

Вам не обязательно переходить на модульность при миграции на Java 9+. Приложение на classpath работает без изменений — всё становится одним большим безымянным модулем. Миграция — это необязательный шаг, который имеет смысл, когда вы хотите строгой инкапсуляции, пользовательского рантайма jlink или более чёткого графа зависимостей. Главное — делать это постепенно, поскольку три вида модулей — именованные, автоматические и безымянные — позволяют модульному и немодульному коду сосуществовать.

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

Сначала: просто запустите приложение на Java 9+ (без модулей)

Прежде чем добавлять module-info.java, перекомпилируйте и запустите существующее приложение на новом JDK, разместив всё на classpath. Вероятные ошибки не имеют ничего общего с вашими модулями — они связаны с теперь уже модульным JDK:

Удалённые модули Java EE — java.xml.bind (JAXB), java.activation, CORBA и другие были удалены из JDK. Добавьте их обратно в виде обычных зависимостей.
Инкапсулированные внутренние API — sun.misc.Unsafe и подобные классы больше недоступны. Флаги --add-exports / --add-opens служат аварийным выходом на время удаления этих вызовов.
Разделённые пакеты — два JAR-файла, содержащие одинаковый пакет, конфликтуют на пути к модулям (но не на classpath).

Сначала добейтесь успешного запуска приложения на classpath. Только потом начинайте модуляризацию.

Миграция снизу вверх (bottom-up)

Предпочтительная стратегия, когда вы контролируете всю кодовую базу:

Начните с листовых библиотек — модулей, которые ни от чего вашего не зависят.
Добавьте каждой из них module-info.java и переместите на путь к модулям.
Зависящие от них модули теперь могут объявить requires. Работайте вверх по дереву зависимостей к точке входа приложения.

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

Миграция сверху вниз (top-down)

Когда вы не контролируете библиотеки (JAR-файлы сторонних разработчиков без дескрипторов), идите обратным путём:

Сначала модуляризируйте собственный код верхнего уровня.
Разместите немодульные JAR-файлы сторонних разработчиков на пути к модулям, где они станут автоматическими модулями.
Объявите requires по их автоматическому имени (из имени JAR-файла или Automatic-Module-Name).
Когда каждая библиотека поставит настоящий module-info, замените автоматическую зависимость на именованную — изменений в вашем requires не потребуется.

Автоматические модули — это строительные леса, делающие подход top-down возможным: они позволяют именованному коду зависеть от JAR-файлов, которые пока не являются модульными.

Инструменты и подводные камни

jdeps анализирует реальные зависимости JAR-файла и даже может сгенерировать первоначальный module-info.java (jdeps --generate-module-info). Начните с этого, а не пишите директивы вручную.
Automatic-Module-Name — если вы публикуете библиотеку, добавьте эту запись манифеста до написания полного дескриптора. Это фиксирует стабильное имя модуля, чтобы пользователи автоматических модулей не сломались, когда вы позже переименуете JAR-файл.
Разделённые пакеты необходимо объединять. Путь к модулям запрещает двум модулям владеть одним пакетом; classpath это допускал. Это наиболее распространённое препятствие при миграции.
opens для рефлексии. Фреймворки, использующие рефлексию над вашими классами (Jackson, JPA, Spring), требуют opens, иначе во время выполнения вы получите InaccessibleObjectException, даже если компиляция прошла успешно.

Внимание

Разделённые пакеты — это ошибка, которая удивляет людей чаще всего. На classpath два JAR-файла, содержащие классы в com.example.util, просто объединялись; на пути к модулям резолвер отклоняет их с ошибкой «module reads package ... from both». Не существует флага, который делает это допустимым — необходимо объединить дублирующийся пакет в один модуль (или переименовать один из них). Проверьте наличие разделённых пакетов с помощью jdeps до того, как начнёте писать дескрипторы.

Практический пример: исследование графа зависимостей, как делает jdeps

Планирование миграции начинается с вопроса «что от чего зависит». Эта программа читает дескрипторы модулей загрузочного слоя во время выполнения — ту же информацию requires, которую предоставляет jdeps — и также определяет, работает ли она сама как именованный модуль или на classpath, что служит конкретной проверкой того, насколько далеко продвинулась миграция.

java— editable, runs on the server

import java.lang.module.ModuleDescriptor;
import java.util.stream.Collectors;

public class ModulesMigrationDemo {
  public static void main(String[] args) {
    // Where am I in the migration? Classpath => unnamed; module path => named.
    Module self = ModulesMigrationDemo.class.getModule();
    System.out.println("running as: "
        + (self.isNamed() ? "NAMED module " + self.getName()
                          : "UNNAMED module (classpath)"));

// jdeps-style: list what a JDK module 'requires'
    inspect("java.sql");
    inspect("java.desktop");

// Find every boot module that (transitively named) requires java.base -
    // i.e. effectively all of them, demonstrating the implicit dependency
    long total = ModuleLayer.boot().modules().size();
    System.out.println("\ntotal modules resolved at startup: " + total);
  }

static void inspect(String moduleName) {
    ModuleLayer.boot().findModule(moduleName).ifPresent(m -> {
      ModuleDescriptor d = m.getDescriptor();
      String deps = d.requires().stream()
          .map(r -> r.name()
              + (r.modifiers().contains(ModuleDescriptor.Requires.Modifier.TRANSITIVE)
                  ? " (transitive)" : ""))
          .collect(Collectors.joining(", "));
      System.out.println("\n" + moduleName + " requires:");
      System.out.println("  " + deps);
    });
  }
}

Что следует вынести из запуска:

Программа сообщила, что работает как UNNAMED модуль — именно то, чего и следует ожидать от кода на classpath, и сигнал во время выполнения, что эта кодовая база ещё не модуляризирована. Повторный запуск после добавления module-info и перемещения на путь к модулям изменит это на NAMED, давая конкретную проверку «дошли ли мы до цели» в процессе миграции.
inspect("java.sql") вывел реальный список requires, включая транзитивную зависимость в стиле java.transaction.xa или java.logging. Это та же информация, которую предоставляет jdeps — знание реальных зависимостей модуля является первым шагом при написании его module-info.java, и дескриптор уже содержит эти данные.
Некоторые requires выводили (transitive). Это зависимости, которые модуль реэкспортирует; когда вы объявляете requires java.sql, вы автоматически читаете и его транзитивные зависимости. Выявление таких зависимостей подсказывает, какие строки requires transitive нужно скопировать при модуляризации кода, который оборачивает подобный модуль.
findModule вернул Optional, подчёркивая, что модуль может попросту отсутствовать в конкретном рантайме — образ, урезанный jlink, может полностью исключить java.desktop. Планы миграции должны учитывать, какие модули реально присутствуют в целевом рантайме.
Каждый модуль в конечном счёте зависит от java.base, и он никогда не фигурирует в списке requires, потому что это зависимость неявная. Общее количество загрузочных модулей показывает, что JDK — это граф, который можно запрашивать программно, — фундамент, на котором такие инструменты, как jdeps и jlink, строят анализ и сжатие приложений.

Разумный порядок миграции, резюме

Запустите на classpath на новом JDK; исправьте ошибки, связанные с удалёнными модулями и внутренними API.
Используйте jdeps для составления карты зависимостей и поиска разделённых пакетов.
Добавьте Automatic-Module-Name во все публикуемые вами библиотеки.
Модуляризируйте снизу вверх, если вы владеете деревом, или сверху вниз (опираясь на автоматические модули), если нет.
Добавьте opens там, где фреймворки используют рефлексию; проверяйте во время выполнения, а не только во время компиляции.

На этом часть про систему модулей платформы Java завершена: теперь вы знаете что такое модули, как объявить модуль, три вида модулей и как они сосуществуют, как сервисы разделяют модули и как перенести существующее приложение на путь к модулям без переписывания с нуля.

Практика

Ваша команда владеет всем исходным деревом приложения и хочет строгой инкапсуляции на всех уровнях. Библиотека A ни от чего вашего не зависит; библиотека B зависит от A; исполняемый модуль зависит от B. Какой порядок миграции сохраняет работоспособность каждой промежуточной сборки с наименьшим количеством автоматических обходных путей?

Снизу вверх: сначала модуляризировать A, затем B (которая теперь может объявить 'requires A'), затем исполняемый модуль — каждый именованный модуль требует только уже модуляризированный кодСверху вниз: сначала модуляризировать исполняемый модуль и оставить A и B на classpath как безымянные модули, которые исполняемый модуль может требовать через 'requires ALL-UNNAMED'Модуляризировать все три одновременно в одном коммите, поскольку частично модуляризированные сборки вообще не компилируютсяПорядок не имеет значения, поскольку именованные модули могут свободно требовать безымянный модуль в процессе миграции