⚙️ Hướng Dẫn Kỹ Thuật:

Tài liệu này hướng dẫn từng bước cách tích hợp và tùy chỉnh công cụ Checkstyle trong dự án Gradle, bằng cách tải về và chỉnh sửa trực tiếp tệp cấu hình google_checks.xml chính thức.

Cách làm này đảm bảo mã nguồn được biên dịch (build) thành công trước khi Checkstyle chạy kiểm tra, duy trì chất lượng code nghiêm ngặt.

Bước 1: Tải tệp cấu hình google_checks.xml

Để dễ dàng tùy chỉnh luật, chúng ta sẽ bắt đầu bằng cách tải tệp cấu hình chuẩn của Google Java Style.

1. Tải tệp: Truy cập kho lưu trữ GitHub của Checkstyle và lưu lại tệp với tên chính xác là google_checks.xml.

   • Kho lưu trữ GitHub của Checkstyle: google_checks.xml

2. Đặt tệp vào dự án: Tạo cấu trúc thư mục sau trong thư mục gốc của dự án và đặt tệp vừa tải vào đó:

   <thư_mục_gốc_dự_án>
   └── config
       └── checkstyle
           └── google_checks.xml  <-- Đặt tệp tại đây
   

Bước 2: Cấu hình Gradle để dùng tệp tùy chỉnh

Mở tệp build.gradle và thiết lập để plugin Checkstyle sử dụng tệp cấu hình mà bạn vừa đặt trong dự án.

A. Thêm Plugin

Đảm bảo đã thêm plugin java và checkstyle vào đầu tệp build.gradle:

// build.gradle (Sử dụng Groovy DSL)
plugins {
    id 'java'
    id 'checkstyle' 
}

B. Cấu hình Phiên bản và Độ Nghiêm ngặt

Thêm khối cấu hình sau để thiết lập phiên bản công cụ và chỉ định đường dẫn đến tệp tùy chỉnh.

// build.gradle (Sử dụng Groovy DSL)
checkstyle {
    // 1. Chỉ định phiên bản Checkstyle muốn dùng
    toolVersion = '10.12.4' 

    // 2. CHỈ ĐƯỜNG DẪN đến tệp cấu hình đã tải về
    configFile = rootProject.file('config/checkstyle/google_checks.xml')
    
    // 3. QUAN TRỌNG: Đặt là 'false' để KHI CÓ LỖI Checkstyle, build sẽ THẤT BẠI
    ignoreFailures = false 
}

C. Cấu hình Ràng buộc Task và Báo cáo

Thêm khối này để thiết lập độ nghiêm ngặt và đảm bảo việc biên dịch (build) được thực hiện trước khi Checkstyle chạy.

// build.gradle (Sử dụng Groovy DSL)
tasks.withType(Checkstyle) {
    // Buộc build phải thất bại ngay cả khi có cảnh báo (Warning) hoặc lỗi (Error)
    maxErrors = 0
    maxWarnings = 0
    
    // Tùy chọn: Bật báo cáo HTML (dễ đọc hơn)
    reports {
        xml.required = false
        html.required = true
    }
}

// KHAI BÁO RÀNG BUỘC (Dependency)
// Đảm bảo mã nguồn phải được biên dịch thành công trước khi Checkstyle chạy.
tasks.named('checkstyleMain') {
    // Yêu cầu chạy task 'classes' (biên dịch mã nguồn chính) trước
    dependsOn 'classes' 
}

tasks.named('checkstyleTest') {
    // Yêu cầu chạy task 'testClasses' (biên dịch mã nguồn test) trước
    dependsOn 'testClasses' 
}

Bước 3: Tùy Chỉnh Danh Sách Luật (Rules)

Bây giờ, bạn có thể mở tệp config/checkstyle/google_checks.xml và chỉnh sửa các luật để phù hợp với quy tắc của dự án.

1. Vô Hiệu Hóa (Tắt) một Luật (Ví dụ: Javadoc)

Để tắt một luật, bạn chỉ cần tìm thẻ <module> tương ứng và xóa hoặc ghi chú (comment) nó lại.

2. Thay đổi Cấu hình Luật (Ví dụ: Độ dài Dòng)

Để thay đổi thiết lập của một luật, bạn chỉnh sửa thuộc tính (property) bên trong thẻ <module> của nó.

Bước 4: Chạy Kiểm Tra (Execution)

1. Các Lệnh Chạy

Sử dụng các lệnh sau để chạy Checkstyle, tùy thuộc vào phạm vi mã bạn muốn kiểm tra. Nhờ vào cấu hình ở Bước 2C, việc biên dịch sẽ tự động chạy trước.

2. Xem Báo cáo

Sau khi chạy lệnh, báo cáo chi tiết (dạng HTML) sẽ được tạo ra tại thư mục build của dự án: