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:
default: Quản lý quy trình biên dịch, đóng gói và phát hành ứng dụng.clean: Dọn dẹp các artifact được tạo ra từ lần build trước.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 trongpom.xml.compile: Biên dịch mã nguồn Java (src/main/java) thành Java Bytecode (.class) lưu trong thư mụctarget/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
compilemặc định liên kết với goalcompiler:compilecủamaven-compiler-plugin. Phasetestliên kết vớisurefire:testcủamaven-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-modulevà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:
- 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).
- 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.xmlsẽ đượ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:
- Đóng gói ứng dụng thành Fat JAR / Executable JAR chứa toàn bộ dependencies cùng Embedded Server (Tomcat/Netty).
- Tự động tìm kiếm hàm
main()để cấu hìnhMain-ClasstrongMETA-INF/MANIFEST.MF. - 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:
- parent-pom: Root project đóng vai trò quản lý chung.
- domain-module: Chứa Entities, Value Objects, Domain Interfaces (Không dính Spring Boot Framework).
- infrastructure-module: Chứa Spring Data JPA Repositories, Database Configurations, External Adapters.
- 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 & 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/, fileapi-module-1.0.0-SNAPSHOT.jarđã sẵn sàng để triển khai bằng lệnhjava -jar.
PHẦN 3: BÀI TẬP VỀ NHÀ (ASSIGNMENT)
- Cấu hình Profiles trong Maven:
Bổ sung khối
<profiles>vào fileparent-pom/pom.xmlđịnh nghĩa 2 môi trường:devvàprod. Cấu hình sao cho khi build bằng lệnhmvn clean package -Pprod, Maven sẽ tự động active cấu hình production và thực thi plugin nén mã nguồn. - Phân tích Dependency Conflict:
Thêm thư viện
commons-loggingphiên bản1.1.1vàoinfrastructure-modulevà dùng lệnhmvn dependency:treeđể tìm xem nó xung đột thế nào vớijcl-over-slf4jcủa Spring Boot. Viết thẻ<exclusions>để xử lý triệt để xung đột này. - Thực hành Maven Enforcer Plugin:
Tích hợp
maven-enforcer-pluginvào Rootpom.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ệnhmvn compilesẽ dừng lập tức và báo lỗi.

0 Nhận xét