Maven là gì? Cấu trúc project Java và pom.xml cơ bản

Maven là gì và dùng để làm gì? Học cấu trúc thư mục project Java, đọc pom.xml, thêm thư viện, chạy mvn package và sửa lỗi Maven hay gặp qua ví dụ quán cà phê.

Maven là công cụ dựng project Java. Bạn khai báo project cần những thư viện nào trong file pom.xml, còn Maven tự tải thư viện về, biên dịch code, chạy test và đóng gói thành file jar. Nó thay cho việc bạn tự gõ lệnh javac với đủ thứ đường dẫn mỗi lần build.

Ở bài trước, mình tách code tính tiền của quán Mộc (quán cà phê tình huống minh họa của loạt bài) thành các method, và chương trình đã dài hơn 70 dòng trong một file. Bạn sẽ sớm muốn chia thành nhiều file, dùng thư viện của người khác và chạy test. Làm tay những việc đó thì rất mệt, và bài này cho bạn thấy vì sao rồi dựng lại bằng Maven.

Không có Maven thì khổ ở đâu?

Mình mở rộng chương trình một chút: in phiếu tính tiền có căn cột cho đẹp. Việc căn cột bằng dấu cách là việc ai cũng cần, nên mình dùng thư viện Apache Commons Lang thay vì tự viết. Chương trình gồm hai file. File thứ nhất là TinhDon.java, giữ nguyên phần tính tiền của bài trước:

src/main/java/vn/moc/donhang/TinhDon.java
package vn.moc.donhang;

public class TinhDon {
    static final long NGUONG_GIAM_GIA = 100_000;
    static final int PHAN_TRAM_GIAM = 10;

    public static long tinhTongTien(int[] soLuong, long[] donGia) {
        long tong = 0;
        for (int i = 0; i < soLuong.length; i++) {
            tong += soLuong[i] * donGia[i];
        }
        return tong;
    }

    public static long tinhGiamGia(long tongTien) {
        if (tongTien >= NGUONG_GIAM_GIA) {
            return tongTien * PHAN_TRAM_GIAM / 100;
        }
        return 0;
    }
}

File thứ hai là App.java, chứa main. Nó in phiếu cho một đơn 2 cà phê sữa và 2 bánh mì que, dùng StringUtils của thư viện để căn cột:

src/main/java/vn/moc/donhang/App.java
package vn.moc.donhang;

import org.apache.commons.lang3.StringUtils;

public class App {
    public static void main(String[] args) {
        String[] mon = {"Cà phê sữa", "Bánh mì que"};
        int[] soLuong = {2, 2};
        long[] donGia = {35_000, 15_000};

        System.out.println(StringUtils.center(" PHIẾU TÍNH TIỀN - QUÁN MỘC ", 40, '='));
        for (int i = 0; i < mon.length; i++) {
            long thanhTien = soLuong[i] * donGia[i];
            System.out.println(StringUtils.rightPad(soLuong[i] + " x " + mon[i], 28)
                    + StringUtils.leftPad(String.valueOf(thanhTien), 12));
        }

        long tong = TinhDon.tinhTongTien(soLuong, donGia);
        long giam = TinhDon.tinhGiamGia(tong);
        System.out.println(StringUtils.repeat('-', 40));
        System.out.println(StringUtils.rightPad("Tổng", 28) + StringUtils.leftPad(String.valueOf(tong), 12));
        System.out.println(StringUtils.rightPad("Giảm 10%", 28) + StringUtils.leftPad("-" + giam, 12));
        System.out.println(StringUtils.rightPad("Phải trả", 28) + StringUtils.leftPad(String.valueOf(tong - giam), 12));
    }
}

Dòng package vn.moc.donhang; ở đầu mỗi file cho biết class thuộc package nào. Package là cách Java gom class vào "thư mục logic", và quy ước là đặt tên theo tên miền đảo ngược. Hai file nằm trong cùng một package nên App gọi được TinhDon mà không cần import. Giờ mình thử biên dịch bằng javac thuần, lệnh trong thư mục gốc của project:

Chạy
javac -encoding UTF-8 -d out src/main/java/vn/moc/donhang/*.java
Kết quả (chỉ lỗi đầu tiên)
src\main\java\vn\moc\donhang\App.java:3: error: package org.apache.commons.lang3 does not exist
import org.apache.commons.lang3.StringUtils;
                               ^

Dĩ nhiên, vì javac không biết thư viện nằm ở đâu. Để làm tay, bạn phải vào trang của Apache, tìm đúng phiên bản, tải file jar về một thư mục, rồi chỉ đường cho javac bằng -cp (classpath, danh sách nơi Java tìm class). Lúc chạy cũng phải chỉ đường lại. Sau đó mọi thứ vẫn còn dở: người cùng nhóm phải làm lại từng bước đó và để jar ở đúng chỗ; một thư viện lớn kéo theo thư viện con của nó, rồi con của con, và bạn phải tự tải từng cái; còn khi đổi phiên bản, bạn phải thay tay và hy vọng không ai dùng bản cũ. Maven giải đúng những việc đó.

Cài Maven như thế nào?

Maven cần JDK có sẵn. Bạn tải bản bin.zip ở trang chủ Maven, giải nén vào một thư mục, rồi thêm thư mục bin bên trong vào biến môi trường PATH. Với Maven bạn cũng cần biến JAVA_HOME trỏ tới thư mục JDK. Mình quên đặt nó lần đầu chạy và thấy thông báo này:

Lỗi khi chưa có JAVA_HOME
The JAVA_HOME environment variable is not defined correctly,
this environment variable is needed to run this program.

Sau khi đặt JAVA_HOME (trên máy mình là thư mục của Temurin 25.0.5), kiểm tra bằng:

Chạy
mvn -v
Kết quả (ba dòng đầu)
Apache Maven 3.9.16 (2bdd9fddda4b155ebf8000e807eb73fd829a51d5)
Maven home: ...
Java version: 25.0.5, vendor: Eclipse Adoptium, runtime: C:\Program Files\Eclipse Adoptium\jdk-25.0.5.8-hotspot

Dòng Java version cho bạn biết Maven đang dùng JDK nào. Nếu nó chỉ vào một JDK cũ, đây là chỗ để phát hiện trước khi build lỗi. Các IDE như IntelliJ cũng có Maven đi kèm và đọc pom.xml để nhận ra project, nên nếu bạn chỉ làm việc trong IDE thì chưa cần cài riêng; còn mình cài riêng để chạy lệnh trong terminal giống như trên máy chủ build sau này.

Một project Maven trông như thế nào?

Maven áp dụng nguyên tắc "quy ước hơn cấu hình": nếu bạn đặt file đúng chỗ quy định, bạn không phải khai báo gì thêm. Đây là cấu trúc của project trong bài:

Cấu trúc thư mục
04-maven-co-ban/
├── pom.xml                         <- mô tả project
└── src/
    ├── main/
    │   ├── java/vn/moc/donhang/    <- code chạy thật
    │   │   ├── App.java
    │   │   └── TinhDon.java
    │   └── resources/              <- file cấu hình, dữ liệu (chưa dùng)
    └── test/
        ├── java/                   <- code test (bài về JUnit sẽ dùng)
        └── resources/

Sau khi build, Maven tạo thêm thư mục target/ để chứa mọi thứ nó sinh ra (class đã biên dịch, file jar), nên bạn không cần commit thư mục này. Thư mục con trong src/main/java khớp với tên package: vn.moc.donhang ứng với vn/moc/donhang. Cách chia main cho code thật và test cho code kiểm thử giúp file test không bị đóng gói vào sản phẩm.

Vì Maven dựa vào quy ước, nó có một cái bẫy mà người mới hay vấp. Mình thử đặt source sai chỗ, trong src/main/vn/moc/ thay vì src/main/java/vn/moc/, rồi chạy mvn compile:

Kết quả của mvn -B compile (hai dòng đáng chú ý)
[INFO] No sources to compile
[INFO] BUILD SUCCESS

Maven báo thành công, trong khi nó không biên dịch gì cả, vì nó chỉ tìm code trong src/main/java. Lỗi này sẽ lộ ra muộn hơn, khi bạn chạy và không thấy class. Lần sau gặp "No sources to compile", hãy kiểm tra đường dẫn thư mục trước tiên. Bạn có thể đọc thêm trong tài liệu về cấu trúc thư mục chuẩn của Maven.

File pom.xml có những gì?

pom.xml (Project Object Model) là bản mô tả project bằng XML. Của project này như sau:

pom.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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <!-- Địa chỉ của project: nhóm, tên, phiên bản -->
  <groupId>vn.moc</groupId>
  <artifactId>don-hang</artifactId>
  <version>1.0.0</version>

  <properties>
    <maven.compiler.release>25</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
    <!-- Thư viện của người khác: Maven tự tải về -->
    <dependency>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-lang3</artifactId>
      <version>3.22.0</version>
    </dependency>
  </dependencies>
</project>

Ba dòng groupId, artifactId, version là "địa chỉ" của project, gọi là tọa độ Maven. Mọi thư viện đều có tọa độ như vậy, nên khi bạn viết ba dòng trong <dependency>, Maven biết chính xác cần lấy file nào. groupId thường là tên miền đảo ngược của tổ chức, artifactId là tên sản phẩm, version là phiên bản. Thư viện được lưu ở Maven Central, kho chung của cộng đồng Java: Commons Lang 3.22.0 nằm ở repo.maven.apache.org/maven2/org/apache/commons/commons-lang3/3.22.0/, đúng theo tọa độ.

Phần <properties> có hai thiết lập. maven.compiler.release bảo trình biên dịch dùng Java 25. Mình chọn release thay cho cặp source và target cũ vì nó kiểm cả các hàm của thư viện chuẩn, không chỉ cú pháp. project.build.sourceEncoding cho Maven biết file nguồn lưu bằng UTF-8. JDK mới đã mặc định UTF-8, nhưng khai báo rõ thì chữ tiếng Việt trong code không bị đọc sai khi ai đó build bằng JDK cũ hơn hoặc trên máy cấu hình khác.

Giờ xem điều gì xảy ra khi tọa độ sai. Mình đổi commons-lang3 thành commons-lang (thiếu số 3) rồi build:

Kết quả của mvn -B compile (các dòng lỗi)
[INFO] BUILD FAILURE
[ERROR] Failed to execute goal on project don-hang: Could not resolve dependencies for project vn.moc:don-hang:jar:1.0.0
[ERROR] dependency: org.apache.commons:commons-lang:jar:3.22.0 (compile)
[ERROR] 	Could not find artifact org.apache.commons:commons-lang:jar:3.22.0 in central (https://repo.maven.apache.org/maven2)

Thông báo nói đủ: không tìm thấy commons-lang bản 3.22.0 trên Central. Khi gặp "Could not find artifact", việc đầu tiên là so tọa độ từng chữ với trang của thư viện, vì gõ sai tên hoặc phiên bản không tồn tại là nguyên nhân thường gặp nhất.

Lần đầu build, Maven tải thư viện về một thư mục trên máy gọi là local repository (thư mục .m2/repository trong thư mục người dùng). Các lần sau nó dùng bản đã tải, nên chạy nhanh hơn. Lệnh mvn dependency:tree cho bạn thấy thư viện nào đang được dùng, kể cả thư viện con:

Kết quả của mvn -B dependency:tree
[INFO] vn.moc:don-hang:jar:1.0.0
[INFO] \- org.apache.commons:commons-lang3:jar:3.22.0:compile

Commons Lang không kéo theo thư viện nào khác nên cây chỉ có một nhánh. Với Spring Boot ở chặng sau, cây này sẽ dài hàng chục thư viện, và đó là lúc việc Maven tự giải quyết "thư viện con của thư viện" phát huy tác dụng. Chữ compile ở cuối là phạm vi (scope) của thư viện, nghĩa là cần cả lúc biên dịch lẫn lúc chạy; thư viện chỉ dùng cho test sẽ có scope test.

Chạy mvn package làm những gì?

Maven chạy build theo một chuỗi các giai đoạn cố định, gọi là vòng đời (lifecycle). Các giai đoạn chính theo thứ tự là biên dịch (compile), chạy test (test), đóng gói (package) và vài giai đoạn sau. Khi bạn gọi một giai đoạn, Maven chạy mọi giai đoạn đứng trước nó. Mỗi giai đoạn do một plugin đảm nhận. Mình chạy mvn clean package và chỉ giữ các dòng cho thấy plugin nào làm việc gì (mình bỏ các dòng trống và đường dẫn dài):

Kết quả của mvn -B -ntp clean package (các dòng chính)
[INFO] Building don-hang 1.0.0
[INFO] --- clean:3.2.0:clean (default-clean) @ don-hang ---
[INFO] --- resources:3.4.0:resources (default-resources) @ don-hang ---
[INFO] --- compiler:3.15.0:compile (default-compile) @ don-hang ---
[INFO] Compiling 2 source files with javac [debug release 25] to target\classes
[INFO] --- resources:3.4.0:testResources (default-testResources) @ don-hang ---
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ don-hang ---
[INFO] No sources to compile
[INFO] --- surefire:3.5.4:test (default-test) @ don-hang ---
[INFO] No tests to run.
[INFO] --- jar:3.5.0:jar (default-jar) @ don-hang ---
[INFO] Building jar: ...\target\don-hang-1.0.0.jar
[INFO] BUILD SUCCESS

Đọc từ trên xuống: clean xóa thư mục target cũ, resources chép tài nguyên, compiler:compile gọi javac biên dịch hai file nguồn, surefire:test chạy test (hiện chưa có, bài JUnit sẽ lấp chỗ này), và jar:jar đóng gói thành don-hang-1.0.0.jar. Bạn không viết bước nào trong số đó, vì Maven có sẵn từ quy ước. Còn chữ -ntp trong lệnh chỉ để ẩn dòng tiến độ tải file cho log gọn.

Mình nên thêm clean khi nghi ngờ: nếu bạn xóa một file .java nhưng file .class cũ vẫn nằm trong target, chương trình có thể vẫn "chạy được" với class đã không còn trong code. clean xóa sạch để build lại từ đầu. Tài liệu đầy đủ ở phần vòng đời build của Maven.

Vì sao java -jar báo "no main manifest attribute"?

Có jar rồi, mình thử chạy thẳng. Đây là chỗ nhiều người mới gặp lỗi lần đầu:

Chạy
java -jar target/don-hang-1.0.0.jar
Kết quả
no main manifest attribute, in target\don-hang-1.0.0.jar

File jar là một file nén, bên trong có một tệp MANIFEST.MF ghi thông tin về jar, trong đó có tên class chứa main. Maven chưa được dặn class nào là điểm bắt đầu, nên manifest không có dòng đó, và java -jar không biết chạy gì. Xem bên trong jar bằng jar tf sẽ thấy nó chỉ chứa hai class của chúng ta (App.class, TinhDon.class) cùng vài file thông tin của Maven. Thư viện Commons Lang không nằm trong đó. Vậy nên kể cả khi có manifest, máy khác chạy jar này vẫn thiếu thư viện.

Cách đơn giản để chạy lúc này là nhờ Maven chép thư viện ra, rồi chỉ classpath bằng tay. Ở bước này mình dùng chính lệnh tay mà ta đã né ở đầu bài, và nó chạy được vì Maven đã lo phần khó nhất là tải đúng thư viện:

Chạy
mvn dependency:copy-dependencies
java -Dstdout.encoding=UTF-8 -cp "target/classes;target/dependency/*" vn.moc.donhang.App
Kết quả
====== PHIẾU TÍNH TIỀN - QUÁN MỘC ======
2 x Cà phê sữa                     70000
2 x Bánh mì que                    30000
----------------------------------------
Tổng                              100000
Giảm 10%                          -10000
Phải trả                           90000

Lệnh đầu chép commons-lang3-3.22.0.jar vào target/dependency. Lệnh thứ hai chạy class vn.moc.donhang.App với classpath gồm thư mục target/classes và mọi jar trong target/dependency. Trên Linux và macOS bạn đổi dấu ; thành : để ngăn cách các đường dẫn. Phiếu in ra khớp với tính tay: 70.000 cộng 30.000 là 100.000, đúng mốc giảm giá, nên giảm 10.000 và trả 90.000.

Cách này vẫn rườm rà để đưa cho người khác chạy. Đây cũng chính là vấn đề mà Spring Boot giải quyết ở chặng sau: nó đóng gói code cùng mọi thư viện vào một file jar duy nhất, và java -jar là đủ.

Maven và Gradle: chọn cái nào?

Gradle là công cụ build thứ hai rất phổ biến ở Java, cũng làm việc tương tự nhưng cấu hình bằng file code thay vì XML. Cả hai đều dùng chung kho thư viện Maven Central. Loạt bài này dùng Maven, vì pom.xml là khai báo thuần nên dễ đọc, và tài liệu của Spring cho Maven rất đầy đủ. Khái niệm trong bài (tọa độ, dependency, vòng đời build) đổi sang Gradle gần như nguyên vẹn, nên bạn học cái nào trước cũng không phí.

Hỏi phỏng vấn thế nào?

Ở vị trí junior, câu hỏi thường là "Maven dùng để làm gì?" và "pom.xml chứa những gì?". Câu trả lời tốt nhắc ba ý: quản lý thư viện (kể cả thư viện con), quy ước cấu trúc thư mục, và vòng đời build với các lệnh như clean, test, package. Nếu kể được lỗi "Could not find artifact" hay "No sources to compile" bạn đã gặp và cách xử lý, bạn nghe có kinh nghiệm hơn nhiều so với người chỉ thuộc định nghĩa. Bạn có thể ôn thêm ở mục phỏng vấn.

Bước tiếp theo là gì?

Bạn đã có project Maven chạy được, thêm thư viện bằng một khối XML, và build bằng một lệnh. Nhưng khi code lớn dần, sẽ có lúc chương trình chạy mà in ra kết quả sai, hoặc dừng với một dòng lỗi mà bạn không hiểu. Lần trước, ArrayIndexOutOfBoundsException còn dễ vì mình biết trước mình viết sai ở đâu. Với code lớn hơn, bạn cần cách đứng trong chương trình đang chạy để nhìn từng biến. Đó là việc của bài kế tiếp trong series Học Java từ đầu cho người làm backend.

Nhận bài tiếp theo qua email.

Một email mỗi tuần, chỉ khi có điều đáng đọc. Không spam.