Best practices for entity sharing between Maven projects: modularization and dependency management

This article explores ways to efficiently share entity classes in Maven projects. The core strategy is to encapsulate entities as independent Maven modules and introduce them into other projects through dependency management mechanisms. The article elaborates on the `mvn clean install` process in a local development environment, as well as the solution of using warehouse tools such as Artifactory for dependency management in team collaboration or production environments. It also briefly mentions alternative ways of directly importing JARs, aiming to provide a clear and professional guide to entity sharing.

In modern software development, especially in microservice architecture or large monolithic applications, it is a common requirement for multiple Maven projects to share the same set of domain entity (Entity) classes. For example, a core business model may be referenced by multiple services, APIs, or client modules. Directly copying and pasting code is not only inefficient, but also difficult to maintain and can easily lead to inconsistent data models. This article will introduce in detail how to share entity classes between projects in a professional and maintainable way through Maven's modular features.

1. Core strategy: Create independent Maven entity modules

The most recommended and most consistent method with Maven philosophy is to encapsulate the entity class into an independent Maven module. This module will only contain entity definitions, enumerations, constants and other data structures, not business logic, and will be released as a JAR package for other projects to rely on.

1.1 Module structure design

Suppose we have a project_a, which contains entity classes under the com.myproject.model package. In order to share these entities, we transform project_a into a parent project (Parent Project) and separate a new submodule from it, for example named entity-model.

 my-parent-project/
├─ entity-model/ <h4> 1.2 Configure parent project pom.xml</h4><p> First, configure the outermost pom.xml as the parent project, its packaging type should be pom, and declare all submodules.</p><pre class="brush:php;toolbar:false"> <!-- my-parent-project/pom.xml -->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelversion>4.0.0</modelversion>
    <groupid>com.myproject</groupid>
    <artifactid>my-parent-project</artifactid>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging> <!-- The packaging type of the parent project is pom -->

    <modules>
        <module>entity-model</module>
        <module>project_a</module>
        <module>project_b</module> <!-- If project_b is also a submodule of the parent project-->
    </modules>

    <!-- dependencyManagement and pluginManagement can be defined here -->
</project>

1.3 Configure entity module pom.xml

The pom.xml of the entity-model module will define its own coordinates and set its packaging type to jar. All entity classes that need to be shared will be placed in the src/main/java directory of this module.

 <!-- my-parent-project/entity-model/pom.xml -->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelversion>4.0.0</modelversion>

    <parent>
        <groupid>com.myproject</groupid>
        <artifactid>my-parent-project</artifactid>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactid>entity-model</artifactid>
    <packaging>jar</packaging> <!-- The entity module packaging type is jar -->

    <!-- Here you can add libraries that entity classes may depend on, such as Lombok, JPA annotations, etc. -->
    <dependencies>
        <dependency>
            <groupid>org.projectlombok</groupid>
            <artifactid>lombok</artifactid>
            <version>1.18.20</version> <!-- Please use the latest version -->
            <scope>provided</scope>
        </dependency>
        <!-- If the entity uses JPA annotations, they also need to be introduced -->
        <dependency>
            <groupid>jakarta.persistence</groupid>
            <artifactid>jakarta.persistence-api</artifactid>
            <version>2.2.3</version> <!-- or higher version-->
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

1.4 Using entity modules in other projects

Any project that needs to use these entity classes (such as project_b or project_a) can simply add a dependency on the entity-model module in its pom.xml.

 <!-- my-parent-project/project_b/pom.xml -->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelversion>4.0.0</modelversion>

    <parent>
        <groupid>com.myproject</groupid>
        <artifactid>my-parent-project</artifactid>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactid>project_b</artifactid>
    <packaging>jar</packaging>

    <dependencies>
        <!--Introducing entity module dependencies-->
        <dependency>
            <groupid>com.myproject</groupid>
            <artifactid>entity-model</artifactid>
            <version>${project.version}</version> <!-- Use parent project version -->
        </dependency>
        <!--Other project dependencies-->
    </dependencies>
</project>

2. Module construction and release

2.1 Local development environment

When developing locally, you can run the mvn clean install command in the parent project root directory. Maven will build all modules in module dependency order:

1. First build the entity-model module and generate entity-model-1.0.0-SNAPSHOT.jar.
2. Install the JAR package to the local Maven repository (usually located at ~/.m2/repository).
3. Then build project_a and project_b, which will find and use the entity-model JAR package from the local warehouse.

In this way, project_b can import the entity classes under the com.myproject.model package just like any other third-party library.

2.2 Remote warehouse management

In team collaboration or production environments, we usually don't rely directly on the local .m2 repository. At this time, the JAR package of the entity-model module needs to be deployed to a shared remote Maven repository, such as Artifactory , Nexus , etc.

1. Configure settings.xml: Configure the authentication information of the remote warehouse in Maven's settings.xml file.
2. Configure the parent project pom.xml or entity-model/pom.xml: add the distributionManagement section to point to the URL of the remote warehouse.

 <!-- my-parent-project/pom.xml or entity-model/pom.xml -->
<distributionmanagement>
    <repository>
        <id>my-releases</id>
        <name>MyCompany Releases</name>
        <url>http://your-artifactory-url/artifactory/libs-release</url>
    </repository>
    <snapshotrepository>
        <id>my-snapshots</id>
        <name>MyCompany Snapshots</name>
        <url>http://your-artifactory-url/artifactory/libs-snapshot</url>
    </snapshotrepository>
</distributionmanagement>

3. Deployment module: Run the mvn clean deploy command, and Maven will deploy the entity-model JAR package and its pom.xml to the remote warehouse.
4. References from other projects: Other independent projects (even if they are not in the same parent project) only need to declare a dependency on entity-model in their pom.xml, and Maven will download it from the configured remote repository.

3. Alternative: Directly import the JAR file

In addition to modularization, another way is to directly introduce the compiled JAR file of entity-model as an external dependency.

• Manually import into the project lib directory: Copy the JAR file to project_b's lib directory and manually add it to the build path. This method is not recommended because it bypasses Maven's dependency management mechanism and is difficult to version control and automate.
• Maven system scope dependency: You can use system scope in pom.xml to reference JARs in the local file system.

 <dependency>
    <groupid>com.myproject</groupid>
    <artifactid>entity-model</artifactid>
    <version>1.0.0</version>
    <scope>system</scope>
    <systempath>${project.basedir}/lib/entity-model-1.0.0.jar</systempath>
</dependency>

Consequences and reasons for deprecation: Using system scope dependencies is also not recommended for regular projects. It makes the build less portable since systemPath is a hardcoded local path. When the project is built on different development environments or CI/CD servers, you need to ensure that the JAR files are located in the same specified path, otherwise the build will fail. Additionally, it cannot take advantage of Maven's transitive dependency management or easily obtain updates from remote repositories.

4. Precautions and Best Practices

• Version management: Use semantic versioning (Semantic Versioning) for entity modules to clearly express API compatibility. In a parent-child module structure, submodules usually inherit the version of the parent module.
• Module granularity: Entity modules should be kept "pure" and only contain data model-related classes (such as POJOs, DTOs, enumerations, interfaces, etc.), and avoid introducing business logic or service layer code to reduce unnecessary dependencies and couplings.
• Dependency isolation: Ensure that the entity module has as few dependencies as possible and only contains those libraries necessary for the entity definition itself (such as JPA annotations, Lombok, etc.).
• Continuous integration/deployment (CI/CD): Integrate the construction and deployment of entity modules into the CI/CD process to ensure that each code submission can be automatically built, tested and deployed to the remote warehouse to provide the latest and available entity version.
• Avoid circular dependencies: Ensure that the dependencies between modules are one-way and avoid the situation where A depends on B and B also depends on A.

Summarize

Encapsulating entity classes into independent Maven modules and sharing them through the dependency management mechanism is the best practice to achieve entity reuse between Maven projects. This method not only provides a clear structure and convenient version control, but also effectively utilizes Maven's dependency management capabilities. Especially when combined with remote warehouses, it can greatly improve team collaboration efficiency and project maintainability. While alternatives to directly importing JARs exist, they often result in increased build complexity and reduced portability and should be avoided in most cases.

The above is the detailed content of Best practices for entity sharing between Maven projects: modularization and dependency management. For more information, please follow other related articles on the PHP Chinese website!