Monorepositorio con Java: organización del código en la práctica

Introducción: ¿por qué un monorepositorio en proyectos Java?

Con el crecimiento de la complejidad de las aplicaciones Java, los equipos a menudo se enfrentan a un dilema: almacenar todo el código en un solo repositorio (monorepositorio) o dividirlo en múltiples repositorios de microservicios (polirepositorio). La práctica muestra que el monorepositorio es especialmente efectivo para proyectos con lógica de negocio, bibliotecas y configuraciones compartidas. En Java, permite gestionar de forma centralizada las dependencias, versiones y compilaciones, simplificando la refactorización y la integración.

En este artículo, analizaremos cómo organizar el código Java en un monorepositorio en la práctica: desde la estructura de carpetas hasta la configuración de CI/CD. Aprenderá cómo evitar errores típicos y acelerar el desarrollo.

1. Estructura del monorepositorio para Java

El principio clave del monorepositorio es la modularidad. En Java, esto se implementa a través de proyectos multimódulo (multi-module project). Cada módulo es responsable de su propia área de responsabilidad: bibliotecas comunes, servicios, utilidades.

Ejemplo de una estructura típica:

my-java-monorepo/├── build.gradle          # Archivo de compilación raíz├── settings.gradle       # Conecta todos los módulos├── gradle.properties     # Versiones comunes de dependencias├── common-lib/           # Biblioteca común (DTO, utilidades)│   ├── build.gradle│   └── src/├── service-auth/         # Servicio de autenticación│   ├── build.gradle│   └── src/├── service-payment/      # Servicio de pagos│   ├── build.gradle│   └── src/└── integration-tests/    # Pruebas de integración    ├── build.gradle    └── src/

Para la gestión de versiones, es conveniente externalizar las dependencias comunes al archivo raíz build.gradle o pom.xml (para Maven). En Gradle, esto se hace a través del bloque subprojects:

subprojects {    apply plugin: 'java'    group = 'com.pythonlib'    version = '1.0.0'

    repositories {        mavenCentral()    }

    dependencies {        testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'    }}

Esta estructura permite agregar fácilmente nuevos servicios sin copiar configuraciones y garantiza que todos los módulos utilicen las mismas versiones de las bibliotecas.

2. Gestión de dependencias y versiones

Uno de los principales problemas del monorepositorio es el conflicto de versiones. En Java, para resolverlo se utilizan BOM (Bill of Materials) o una descripción centralizada de dependencias. Veamos un ejemplo en Gradle usando java-platform.

Creemos un módulo platform que defina todas las dependencias externas:

// platform/build.gradleplugins {    id 'java-platform'}

javaPlatform {    allowDependencies()}

dependencies {    constraints {        api 'com.fasterxml.jackson.core:jackson-databind:2.15.2'        api 'org.springframework.boot:spring-boot-starter-web:3.1.5'        api 'org.slf4j:slf4j-api:2.0.9'    }}

Ahora, en cada servicio, simplemente podemos hacer referencia a la plataforma:

// service-auth/build.gradledependencies {    implementation platform(project(':platform'))    implementation 'com.fasterxml.jackson.core:jackson-databind'    implementation 'org.springframework.boot:spring-boot-starter-web'}

Esto garantiza que todos los módulos utilicen las mismas versiones. Al actualizar la versión en platform, los cambios se aplican automáticamente a todos los servicios.

Consejo: para Maven, use <dependencyManagement> en el pom.xml raíz. Funciona de manera similar.

3. CI/CD para el monorepositorio

La organización de la integración continua en un monorepositorio requiere un enfoque especial. No se pueden compilar todos los módulos en cada commit, ya que esto ralentizaría el pipeline. La solución óptima es la compilación incremental basada en los cambios.

Ejemplo en GitHub Actions usando paths:

name: Java CIon: