Khoá JSM: Buổi 3 - ENTERPRISE PROJECT STRUCTURING & ADVANCED DEPENDENCY MANAGEMENT VỚI APACHE MAVEN

 

Mục tiêu: Nắm vững cơ chế vận hành chuyên sâu của Apache Maven, làm chủ kỹ thuật quản lý dự án Multi-Module theo kiến trúc Onion/Hexagonal, xử lý triệt để Dependency Hell và tối ưu hóa quy trình Build/Packaging cho môi trường Microservices Enterprise.

PHẦN 1: LÝ THUYẾT CHI TIẾT (60 PHÚT)

1. Maven Lifecycle & Build Phase Internals (15 phút)

Apache Maven không chỉ đơn thuần là một công cụ tải thư viện (Dependency Downloader), mà là một hệ thống quản lý vòng đời dự án dựa trên khai báo (Declarative Build Automation System). Nền tảng của Maven dựa trên các Build Lifecycle. Maven định nghĩa 3 vòng đời độc lập:
  1. default: Quản lý quy trình biên dịch, đóng gói và phát hành ứng dụng.
  2. clean: Dọn dẹp các artifact được tạo ra từ lần build trước.
  3. site: Tạo tài liệu kỹ thuật và báo cáo (Documentation) cho dự án.

Deep Dive vào default Lifecycle

Mỗi Lifecycle gồm nhiều Phases (giai đoạn) sắp xếp theo thứ tự nghiêm ngặt. Khi bạn gọi một phase, Maven sẽ tự động thực thi tất cả các phase đứng trước nó trong cùng lifecycle.
  • validate: Kiểm tra tính hợp lệ của dự án và các thông tin khai báo trong pom.xml.
  • compile: Biên dịch mã nguồn Java (src/main/java) thành Java Bytecode (.class) lưu trong thư mục target/classes.
  • test-compile: Biên dịch mã nguồn kiểm thử (src/test/java).
  • test: Thực thi các bộ Unit Test (sử dụng JUnit/Testcontainers).
  • package: Đóng gói mã nguồn đã biên dịch thành định dạng lưu trữ như JAR, WAR, hoặc EAR.
  • verify: Chạy các bài kiểm thử tích hợp (Integration Tests) để đảm bảo tiêu chuẩn chất lượng.
  • install: Đưa file artifact (JAR/WAR) vào Maven Local Repository (~/.m2/repository) để các project khác trên cùng máy local có thể tham chiếu.
  • deploy: Tải file artifact lên Nexus Repository Manager hoặc JFrog Artifactory phục vụ CI/CD và chia sẻ trong toàn doanh nghiệp.

Cơ chế Binding giữa Plugin Goals và Lifecycle Phases

Bản thân Maven Lifecycle là một khung (framework) rỗng. Công việc thực tế được thực hiện bởi các Maven Plugins. Mỗi plugin chứa các Goals (mục tiêu). Maven liên kết (bind) các plugin goals này vào các lifecycle phases.
  • Ví dụ: Phase compile mặc định liên kết với goal compiler:compile của maven-compiler-plugin. Phase test liên kết với surefire:test của maven-surefire-plugin.

2. Quản lý Multi-Module Project trong Kiến trúc Enterprise (15 phút)

Trong các hệ thống phần mềm lớn hoặc Microservices, việc gộp toàn bộ mã nguồn vào một project đơn lẻ (Monolithic Repo Layout) sẽ tạo ra "Big Ball of Mud". Tách dự án thành Multi-Module Project giúp chia nhỏ trách nhiệm, áp dụng triệt để nguyên lý Clean Architecture / Hexagonal Architecture và tăng tốc độ build nhờ khả năng Parallel Build (mvn compile -T 1C).

Cấu trúc cây thư mục chuẩn Enterprise

Plaintext
enterprise-root-app/
├── pom.xml                     (Parent POM - Packaging: pom)
├── domain-module/
│   ├── pom.xml                 (Domain Logic & Entities - Packaging: jar)
│   └── src/main/java/
├── infrastructure-module/
│   ├── pom.xml                 (DB Repositories, External APIs - Packaging: jar)
│   └── src/main/java/
└── api-module/
    ├── pom.xml                 (REST Controllers, Spring Boot Main - Packaging: jar)
    └── src/main/java/

Mối quan hệ giữa Root POM và Sub-modules

  • pom.xml ở Root Project: Khai báo <packaging>pom</packaging> và danh sách các module con trong thẻ <modules>.
XML
<groupId>com.enterprise.app</groupId>
<artifactId>enterprise-root-app</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>

<modules>
    <module>domain-module</module>
    <module>infrastructure-module</module>
    <module>api-module</module>
</modules>

Định hướng phụ thuộc (Dependency Direction Rules)

Để giữ kiến trúc sạch, các module phải tuân thủ luồng phụ thuộc một chiều nghiêm ngặt:
  • domain-module: Đứng độc lập, không phụ thuộc vào bất kỳ module nào khác và không phụ thuộc vào Spring Framework hay Database Drivers.
  • infrastructure-module: Phụ thuộc vào domain-module (triển khai các interfaces do domain định nghĩa).
  • api-module: Phụ thuộc vào cả infrastructure-module và domain-module để khởi chạy Spring Boot Application và expose REST API.

3. Advanced Dependency Management & Handling Conflicts (15 phút)

Dependency Transitivity (Phụ thuộc bắc cầu)

Khi bạn khai báo phụ thuộc vào Thư viện A, và Thư viện A lại phụ thuộc vào Thư viện B, Maven sẽ tự động tải Thư viện B vào project của bạn. Đây là Transitive Dependency.

Dependency Conflict Resolution (Giải quyết xung đột phiên bản)

Vấn đề xuất hiện khi Project phụ thuộc vào A (cần B v1.0) và C (cần B v2.0). Maven giải quyết xung đột dựa trên 2 nguyên tắc cơ bản:
  1. Nearest Definition First (Ưu tiên khoảng cách ngắn nhất):
    • Project -> A -> B (v1.0) [Khoảng cách: 2]
    • Project -> B (v2.0) [Khoảng cách: 1]
    • $\rightarrow$ Maven sẽ chọn B (v2.0).
  2. First Declaration Wins (Khai báo trước thắng):
    • Nếu khoảng cách bằng nhau (Project -> A -> B v1.0 và Project -> C -> B v2.0), phiên bản thuộc thư viện được khai báo trước trong pom.xml sẽ được chọn.

Chẩn đoán lỗi với mvn dependency:tree

Khi gặp lỗi NoSuchMethodError hoặc ClassNotFoundException ở Runtime do xung đột thư viện, kĩ sư Senior sử dụng công cụ lệnh CLI:

Bash
# In toàn bộ cây phụ thuộc
mvn dependency:tree

# Lọc riêng thư viện đang bị xung đột (Ví dụ: Jackson Databind)
mvn dependency:tree -Dincludes=com.fasterxml.jackson.core:jackson-databind

Kỹ thuật Loại bỏ Transitive Dependency (<exclusions>)

Nếu một thư viện bắc cầu gây xung đột hoặc lỗi bảo mật (Vulnerability), ta chủ động loại bỏ nó:

XML
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <!-- Loại bỏ Tomcat truyền thống để dùng Undertow hoặc Jetty -->
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Phân biệt <dependencies> vs <dependencyManagement>

  • <dependencies>: Khai báo trực tiếp dependency. Bất kỳ module con nào kế thừa Parent POM cũng sẽ bắt buộc bị buộc nạp dependency này.
  • <dependencyManagement>: Định nghĩa trước "Bản thiết kế" phiên bản (Version, Exclusions) cho các thư viện, nhưng không trực tiếp tải về. Module con muốn dùng chỉ cần khai báo <groupId> và <artifactId>, không cần ghi <version>.

Khái niệm BOM (Bill of Materials)

BOM là một pom.xml đặc biệt chỉ chứa khối <dependencyManagement> để gom nhóm phiên bản chuẩn của hàng trăm thư viện tương thích với nhau (Ví dụ: spring-boot-dependencies, spring-cloud-dependencies).

Tích hợp BOM vào dự án thông qua scope import:

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

4. Maven Core Plugins Deep Dive (15 phút)

a. maven-compiler-plugin

Chịu trách nhiệm biên dịch mã nguồn Java. Cần cấu hình chính xác Java Release version và chỉ định annotation processors (như MapStruct, Lombok):

XML
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.13.0</version>
    <configuration>
        <release>25</release> <!-- Sử dụng Java 25 -->
        <parameters>true</parameters> <!-- Lưu tên tham số method phục vụ Reflection/Spring -->
    </configuration>
</plugin>

b. maven-surefire-plugin

Chịu trách nhiệm thực thi Unit Tests trong pha test. Cho phép lọc test cases, cấu hình chạy song song (Parallel execution) để tối ưu thời gian CI/CD:

XML
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.2.5</version>
    <configuration>
        <includes>
            <include>**/*Test.java</include>
            <include>**/*Spec.java</include>
        </includes>
        <parallel>methods</parallel>
        <threadCount>4</threadCount>
    </configuration>
</plugin>

c. spring-boot-maven-plugin

Plugin chiến lược của Spring Boot, giúp:
  1. Đóng gói ứng dụng thành Fat JAR / Executable JAR chứa toàn bộ dependencies cùng Embedded Server (Tomcat/Netty).
  2. Tự động tìm kiếm hàm main() để cấu hình Main-Class trong META-INF/MANIFEST.MF.
  3. Hỗ trợ tạo OCI-compliant Container Images thông qua Cloud Native Buildpacks (mvn spring-boot:build-image).

PHẦN 2: THỰC HÀNH HANDS-ON (60 PHÚT)

Đề bài thực hành: Khởi tạo Cấu trúc Dự án Multi-Module chuẩn Enterprise Architecture

Chúng ta sẽ xây dựng từ đầu cấu trúc hệ thống E-Commerce Microservice chia làm 3 module độc lập tuân thủ Clean Architecture:
  1. parent-pom: Root project đóng vai trò quản lý chung.
  2. domain-module: Chứa Entities, Value Objects, Domain Interfaces (Không dính Spring Boot Framework).
  3. infrastructure-module: Chứa Spring Data JPA Repositories, Database Configurations, External Adapters.
  4. api-module: Chứa REST Controllers, Application Entry point (@SpringBootApplication), Spring Security.

BƯỚC 1: Khởi tạo Root parent-pom/pom.xml

Tạo thư mục dự án ecommerce-platform và tạo file pom.xml gốc:

XML
<?xml version="1.0" encoding="UTF-8"?>
<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.enterprise.ecommerce</groupId>
    <artifactId>ecommerce-platform</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <name>E-Commerce Platform (Root)</name>
    <description>Enterprise Multi-Module Architecture with Spring Boot 4 &amp; Java 25</description>

    <modules>
        <module>domain-module</module>
        <module>infrastructure-module</module>
        <module>api-module</module>
    </modules>

    <properties>
        <java.version>25</java.version>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        
        <!-- Versions Management -->
        <spring.boot.version>3.3.0</spring.boot.version>
        <mapstruct.version>1.5.5.Final</mapstruct.version>
        <lombok.version>1.18.32</lombok.version>
    </properties>

    ...
</project>


BƯỚC 2: Khởi tạo domain-module (Pure Java Module)

Tạo thư mục domain-module và file pom.xml:

XML
<?xml version="1.0" encoding="UTF-8"?>
<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.enterprise.ecommerce</groupId>
        <artifactId>ecommerce-platform</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>domain-module</artifactId>
    <packaging>jar</packaging>

    <name>E-Commerce :: Domain Module</name>

    <!-- Module này giữ nguyên bản, không chứa Spring Boot Starters -->
    <dependencies>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>


Viết mã nguồn mẫu cho Domain Model:

Thực hành tạo file domain-module/src/main/java/com/enterprise/ecommerce/domain/model/Product.java:

Java
package com.enterprise.ecommerce.domain.model;

import java.math.BigDecimal;
import java.util.Objects;

// Sử dụng Java 25 Record cho Immutability trong Domain
public record Product(
    String id,
    String name,
    BigDecimal price,
    int stockQuantity
) {
    public Product {
        Objects.requireNonNull(id, "Product ID cannot be null");
        Objects.requireNonNull(name, "Product Name cannot be null");
        if (price.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("Price must be greater than or equal to 0");
        }
    }

    public boolean isAvailable() {
        return stockQuantity > 0;
    }
}

Tạo Domain Repository Interface domain-module/src/main/java/com/enterprise/ecommerce/domain/repository/ProductRepository.java:

Java
package com.enterprise.ecommerce.domain.repository;

import com.enterprise.ecommerce.domain.model.Product;
import java.util.Optional;

public interface ProductRepository {
    Product save(Product product);
    Optional<Product> findById(String id);
}


BƯỚC 3: Khởi tạo infrastructure-module (Database & External Adapters)

Tạo thư mục infrastructure-module và file pom.xml:

XML
<?xml version="1.0" encoding="UTF-8"?>
<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.enterprise.ecommerce</groupId>
        <artifactId>ecommerce-platform</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>infrastructure-module</artifactId>
    <packaging>jar</packaging>

    <name>E-Commerce :: Infrastructure Module</name>

    <dependencies>
        <!-- Phụ thuộc vào Domain Module -->
        <dependency>
            <groupId>com.enterprise.ecommerce</groupId>
            <artifactId>domain-module</artifactId>
        </dependency>

        <!-- Database & ORM -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <scope>runtime</scope>
        </dependency>
    </dependencies>
</project>


BƯỚC 4: Khởi tạo api-module (Executable Application)

Tạo thư mục api-module và file pom.xml:

XML
<?xml version="1.0" encoding="UTF-8"?>
<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.enterprise.ecommerce</groupId>
        <artifactId>ecommerce-platform</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>api-module</artifactId>
    <packaging>jar</packaging>

    <name>E-Commerce :: API Module</name>

    <dependencies>
        <!-- Phụ thuộc vào Infrastructure Module (Đã bao gồm cả Domain) -->
        <dependency>
            <groupId>com.enterprise.ecommerce</groupId>
            <artifactId>infrastructure-module</artifactId>
        </dependency>

        <!-- Web & Security Starters -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- Plugin chịu trách nhiệm tạo Executable Fat-JAR -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring.boot.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>


Viết mã nguồn cho REST Controller và Entry Point:

Tạo file api-module/src/main/java/com/enterprise/ecommerce/api/EcommerceApplication.java:

Java
package com.enterprise.ecommerce.api;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.domain.EntityScan;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

@SpringBootApplication
@ComponentScan(basePackages = "com.enterprise.ecommerce")
@EntityScan(basePackages = "com.enterprise.ecommerce.infrastructure")
@EnableJpaRepositories(basePackages = "com.enterprise.ecommerce.infrastructure")
public class EcommerceApplication {
    public static void main(String[] args) {
        SpringApplication.run(EcommerceApplication.class, args);
    }
}


BƯỚC 5: Thực thi Build và Kiểm tra kết quả

Mở Terminal tại thư mục gốc ecommerce-platform/ và thực thi các câu lệnh CLI:

  • Dọn dẹp và Biên dịch toàn bộ dự án:
Bash
mvn clean compile
Maven sẽ tự động tính toán thứ tự Build (Reactor Build Order): ecommerce-platform $\rightarrow$ domain-module $\rightarrow$ infrastructure-module $\rightarrow$ api-module.
  • In cây phụ thuộc của api-module để kiểm tra xung đột:
Bash
mvn dependency:tree -pl api-module
  • Đóng gói dự án thành Fat-JAR:
Bash
mvn clean package -DskipTests
  • Kiểm tra file Fat-JAR được sinh ra: Kiểm tra trong thư mục api-module/target/, file api-module-1.0.0-SNAPSHOT.jar đã sẵn sàng để triển khai bằng lệnh java -jar.

PHẦN 3: BÀI TẬP VỀ NHÀ (ASSIGNMENT)

  1. Cấu hình Profiles trong Maven: Bổ sung khối <profiles> vào file parent-pom/pom.xml định nghĩa 2 môi trường: dev và prod. Cấu hình sao cho khi build bằng lệnh mvn clean package -Pprod, Maven sẽ tự động active cấu hình production và thực thi plugin nén mã nguồn.
  2. Phân tích Dependency Conflict: Thêm thư viện commons-logging phiên bản 1.1.1 vào infrastructure-module và dùng lệnh mvn dependency:tree để tìm xem nó xung đột thế nào với jcl-over-slf4j của Spring Boot. Viết thẻ <exclusions> để xử lý triệt để xung đột này.
  3. Thực hành Maven Enforcer Plugin: Tích hợp maven-enforcer-plugin vào Root pom.xml để cấu hình quy tắc (Rule): Bắt buộc toàn bộ lập trình viên trong team phải sử dụng phiên bản Java từ 21 trở lên và Maven từ 3.9 trở lên, nếu không thỏa mãn lệnh mvn compile sẽ dừng lập tức và báo lỗi.

Đăng nhận xét

0 Nhận xét