Monorepositório com Java: organização de código para iniciantes

Introdução: o que é um monorepositório e por que ele é útil para um desenvolvedor Java?

Imagine que você está escrevendo uma grande aplicação Java: um serviço web, uma biblioteca para trabalhar com bancos de dados e um módulo separado para logging. Tradicionalmente, cada componente é armazenado em seu próprio repositório Git. Mas existe outra abordagem — o monorepositório (monorepo). É uma estratégia onde todo o código do projeto (ou até mesmo de vários projetos relacionados) é armazenado em um único repositório.

Para desenvolvedores Java iniciantes, o monorepositório pode parecer incomum, mas ele oferece vantagens importantes:

• Versão única de dependências — todos os módulos usam as mesmas versões de bibliotecas, eliminando conflitos.
• Refatoração simplificada — alterações na API de um módulo são imediatamente visíveis em todos os módulos dependentes.
• Configurações compartilhadas — um único arquivo de configuração para linter, formatação e CI/CD.
• Início fácil — não é necessário configurar vários repositórios para um projeto pequeno.

Neste artigo, vamos explorar como organizar um monorepositório em Java usando ferramentas de build populares: Maven e Gradle. Você aprenderá como estruturar pastas, configurar uma build multimódulo e evitar erros comuns.

Parte principal

1. Estrutura do monorepositório: do simples ao complexo

Uma estrutura de pastas adequada é a base de um monorepositório bem-sucedido. Aqui está um modelo recomendado para um projeto Java:

my-monorepo/├── build.gradle           # Arquivo de build raiz (para Gradle)├── settings.gradle        # Lista de módulos├── pom.xml                # POM raiz (para Maven)├── README.md├── .gitignore├── libs/                  # Bibliotecas compartilhadas│   ├── common-utils/│   └── logging-framework/├── services/              # Microsserviços ou aplicações│   ├── user-service/│   └── payment-service/└── tools/                 # Utilitários e scripts    └── code-generator/

Cada módulo é um projeto Java independente com seu próprio pom.xml ou build.gradle. Os arquivos de configuração raiz gerenciam dependências e versões. Vamos detalhar ambas as opções.

2. Monorepositório com Maven: projeto multimódulo

O Maven suporta projetos multimódulo nativamente. Crie um pom.xml raiz especificando os módulos:

<project>    <modelVersion>4.0.0</modelVersion>    <groupId>com.example</groupId>    <artifactId>my-monorepo</artifactId>    <packaging>pom</packaging>    <version>1.0.0</version>        <modules>        <module>libs/common-utils</module>        <module>services/user-service</module>        <module>services/payment-service</module>    </modules>

    <dependencyManagement>        <dependencies>            <dependency>                <groupId>org.springframework.boot</groupId>                <artifactId>spring-boot-dependencies</artifactId>                <version>3.2.0</version>                <type>pom</type>                <scope>import</scope>            </dependency>        </dependencies>    </dependencyManagement></project>

No módulo common-utils (pasta libs/common-utils), crie seu próprio pom.xml referenciando o projeto pai:

<project>    <parent>        <groupId>com.example</groupId>        <artifactId>my-monorepo</artifactId>        <version>1.0.0</version>    </parent>    <artifactId>common-utils</artifactId>        <dependencies>        <dependency>