Всем привет, меня зовут Сергей Прощаев. Я Tech Lead и руководитель направления Java / Kotlin разработки в FinTech и E‑commerce, а ещё преподаю на курсах по разработке и архитектуре в OTUS.

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

Сегодня я предлагаю вам самим стать ведущим разработчиком, которому поручили построить Maven‑монорепозиторий для пяти микросервисов. Под катом — черновик структуры от коллеги. В нём ровно пять ошибок. Проверьте, найдёте ли вы их за пять минут.

Задание: найдите 5 ошибок в проекте монорепозитория

Помню, как однажды на новом проекте мы так же сидели утром в понедельник и обсуждали, как из монолита сделать пять независимых Spring Boot‑сервисов: user-service, order-service, notification-service, product-service, api-gateway. У нас уже были готовые библиотеки: общие DTO, события для RabbitMQ, заготовка security. Всё должно лежать в одном репозитории. Требования звучали просто: сборка быстрая, версии не разъезжаются, библиотеки не пытаются запуститься как приложения, любой сервис можно поднять локально одной командой. И знаете, что мне тогда показали? Черновик вроде этого.

Один из разработчиков предложил такую структуру:

platform/
├── pom.xml                        ← родитель и агрегатор
├── libs/
│   ├── pom.xml                    ← агрегатор библиотек
│   ├── common-dto/
│   │   └── pom.xml                ← модуль общих DTO
│   └── common-events/
│       └── pom.xml                ← модуль событий
└── services/
    ├── pom.xml                    ← общий родитель для сервисов
    └── user-service/
        └── pom.xml                ← сервис пользователей

А вот ключевые фрагменты pom‑файлов (я упростил их для наглядности):

Корневой pom.xml (родитель и агрегатор, фрагмент):

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.14</version>
</parent>
<groupId>com.example</groupId>
<artifactId>platform</artifactId>
<version>1.0.0</version>
<packaging>pom</packaging>
<modules>
    <module>libs</module>
    <module>services</module>
</modules>
<!-- dependencyManagement отсутствует -->

Корневой файл проекта: наследует spring‑boot‑starter‑parent и объявляет модули libs и services.

libs/pom.xml (агрегатор библиотек):

<modules>
    <module>common-dto</module>
    <module>common-events</module>
</modules>
<!-- spring-boot-maven-plugin активирован -->

Агрегатор библиотек: перечисляет модули common‑dto и common‑events, содержит spring‑boot‑maven‑plugin.

libs/common‑dto/pom.xml (модуль общих DTO):

<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>common-events</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

Модуль общих DTO: зависит от common‑events.

libs/common‑events/pom.xml (модуль событий):

<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>common-dto</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

Модуль событий: зависит от common‑dto.

services/user‑service/pom.xml (сервис пользователей):

<parent>
    <groupId>com.example</groupId>
    <artifactId>platform</artifactId>
    <version>1.0.0</version>
</parent>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>3.5.14</version>
    </dependency>
</dependencies>

Сервис пользователей: наследует корневой platform, подключает spring‑boot‑starter‑web.

Могу себе представить, как кто‑то из вас сейчас подумает: «Ну, выглядит логично». Но сборка падает с «No main manifest attribute» при запуске модуля libs. А ещё при обновлении Spring Boot приходится менять версии во всех пяти сервисах руками. Теперь самое интересное.

Как считаете, какие ошибки есть в этом проекте?

A. Циклическая зависимость между common‑dto и common‑events
Б. Захардкоженные версии в дочерних pom.xml
В. spring‑boot‑maven‑plugin в модуле libs
Г. Отсутствие <dependencyManagement> в корневом pom
Д. Корневой pom смешивает роли агрегатора и родителя
Е. Всё перечисленное
Ж. Только A, Б и Г

Выберите вариант и проверьте себя дальше.

Разбор ошибок

Ошибка 1: Циклическая зависимость между common‑dto и common‑events

Я бы в этой ситуации первым делом посмотрел на граф зависимостей: common-dto ссылается на common-events, а тот — обратно на common-dto. Классический цикл. Maven может собрать такой проект, но поддерживать его становится крайне сложно. Помню, как в одном крупном open‑source проекте (из Apache‑экосистемы) подобную петлю вычищали почти неделю, вынося общие интерфейсы в отдельный модуль. Ответ — да, это ошибка (пункт A).

Ошибка 2: Отсутствие в корневом pom.xml

В корневом pom нет <dependencyManagement> — ни импорта BOM, ни явного перечисления версий. Следствием этого в нашем примере являются захардкоженные версии в user-service/pom.xml: мы видим <version>3.5.14</version> прямо внутри сервиса. Убери dependencyManagement — и каждый модуль будет вынужден указывать версии сам, а это верный путь к рассинхрону. Мне как‑то попалась история, когда NoSuchMethodError в проде возник именно из‑за того, что после обновления Spring Cloud в одном сервисе забыли поднять версию Netty. В моей практике я всегда предпочитаю BOM‑импорт: одна точка правды для всех. Ответ — да, ошибка (пункты Б и Г).

Ошибка 3: spring‑boot‑maven‑plugin в модуле libs

Помню, как однажды молодой коллега собирал общую библиотеку и получил «No main manifest attribute». Он потратил полдня, пока не понял: плагин Spring Boot пытается сделать из библиотеки исполняемый jar. В нашем черновике та же история — spring-boot-maven-plugin активен в libs/pom.xml. Я бы предпочёл вообще убрать его оттуда. Плагин нужен только в services/pom.xml, где живут настоящие приложения. Ответ — да, ошибка (пункт В).

Ошибка 4: Корневой pom одновременно агрегатор и родитель

Вот с этим я сталкивался лично на одном затяжном проекте. Корневой pom у нас был и родителем, и агрегатором. Когда понадобилось добавить ещё один сервис, мы либо наследовали всё подряд, либо начинали дублировать конфигурацию. В итоге рефакторинг занял несколько дней. В этом черновике та же ситуация: platform/pom.xml наследует spring-boot-starter-parent, содержит <modules> и напрямую служит родителем для user-service. Мой вариант, который я использую сейчас — разделять роли: агрегатор (сборка) отдельно, родитель (конфигурация) отдельно, например, в parent/pom.xml. Ответ — да, это ошибка (пункт Д).

Ошибка 5: Пропущен maven‑compiler‑plugin с параметром ‑parameters

Без <parameters>true</parameters> Spring и Jackson переходят к менее предсказуемым механизмам сопоставления параметров через аннотации и рефлексию без имён. Для себя я давно добавил это правило в шаблон родительского pom:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <parameters>true</parameters>
    </configuration>
</plugin>

Сколько раз это спасало от загадочных ошибок при маппинге — не сосчитать. В черновике этой настройки нет, а значит, есть риск неприятных сюрпризов.

Итог: правильный ответ — Е. Всё перечисленное. Все пять ошибок реально присутствуют.

Правильный подход: Best Practices для Maven‑монорепозитория

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

Разделение агрегатора и родителя

Первое, что я бы сделал, — вынес родительский pom в отдельный модуль parent. Тогда корневой pom останется чистым агрегатором. Сервисы будут наследовать от parent, а не от корня. Роли не смешиваются, конфигурация лежит в одном месте.

Единый источник версий

Родительский pom импортирует BOM Spring Cloud, а внутренние библиотеки — через <dependencyManagement> с ${project.version}. Все модули разделяют одну версию. Это CI Friendly Versions, и я предпочитаю именно такой подход.

<!-- parent/pom.xml -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>common-dto</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

Плагины — только там, где нужны

spring-boot-maven-plugin активируется исключительно в services/pom.xml. В родителе — только <pluginManagement> для единой конфигурации.

Частичная сборка и Maven Wrapper

Большинство команд по привычке собирают весь проект. А я бы посоветовал mvnw с флагом -pl -am:

./mvnw clean install -pl services/notification-service -am

Это собирает только нужный сервис и его зависимости. Проверено на себе: экономит кучу времени.

Изоляция локального запуска

И последнее: каждый сервис должен стартовать без Eureka и RabbitMQ — через optional:configserver: и eureka.client.enabled=false. Здесь Config Server используется как централизованный источник конфигурации, но его подключение должно быть опциональным для локальной разработки.

Схема правильной иерархии

Посмотрите на рисунок 2 — так выглядит правильная структура после исправления всех пяти ошибок.

Главное, что можно понять из этой схемы: корневой pom только собирает модули и не навязывает им свою конфигурацию. Всё, что связано с версиями и плагинами, живёт в отдельном parent/pom.xml. Библиотеки зависят друг от друга строго в одну сторону, сервисы наследуют от родителя, а не от корня. И каждый модуль чётко знает свою роль: одни — обычные jar, другие — исполняемые.

Диаграмма последовательности изменений в CI/CD

А теперь представьте, как одно изменение в общей библиотеке проходит через CI/CD (рис. 3).

Здесь видно главное преимущество монорепозитория: один коммит в common-events автоматически вызывает пересборку всех сервисов, которые от него зависят. Не нужно ходить по разным репозиториям и синхронизировать версии вручную — Maven сам проходит по цепочке зависимостей, пересобирает, тестирует и деплоит.

Что мы на самом деле проверяли

Умение спроектировать монорепозиторий — это не про Maven. Это про:

• Понимание границ между модулями и архитектуру зависимостей.

• Инженерную культуру: разделение агрегатора и родителя, единый источник версий.

• Практические навыки, которые экономят часы сборки.

Если выбрали вариант Е — вы готовы вести архитектуру сборки. Если Ж — на правильном пути, но смешение ролей и плагин в libs стоит перепроверить. Если только А, Б или Г — присмотритесь к открытым урокам OTUS по архитектуре, микросервисам и Java‑инфраструктуре:

• 1 июня, 20:00 — «Практика аутентификации и авторизации в микросервисной архитектуре».
  _{JWT, разграничение доступа, взаимодействие сервисов и безопасность auth‑сценариев.}

• 17 июня, 20:00 — «Архитектура информационных систем. Монолиты, SOA и микросервисы»
  _{Переход от монолита к микросервисам, границы сервисов и архитектурные компромиссы.}

Больше анонсов открытых уроков, материалов по Java, DevOps и архитектуре систем — в канале OTUS в MAX.