build.gradle: nó là gì, cú pháp và cấu hình trong Android

build.gradle là gì?

build.gradle là một tập lệnh xây dựng bằng ngôn ngữ Groovy (phần mở rộng .gradle) hoặc Kotlin (.gradle.kts) quản lý tất cả các khía cạnh của việc biên dịch ứng dụng Android. Gradle là hệ thống xây dựng tự động được Google áp dụng vào năm 2013 làm tiêu chuẩn cho Android. build.gradle mô tả: plugin nào được áp dụng (Android, Kotlin, thư viện), phụ thuộc nào được kết nối, phiên bản SDK nào được sử dụng, cách ký ứng dụng và nơi xuất bản.

Quy trình xây dựng bao gồm ba giai đoạn: Initialization (khám phá mô-đun), Configuration (thực thi tập lệnh build.gradle), Execution (thực thi tác vụ). build.gradle chạy trong giai đoạn Configuration, khi Gradle tạo đồ thị tác vụ. Tại thời điểm này, Build Variants được xác định, phụ thuộc được tính toán và tác vụ được cấu hình. Quan trọng: build.gradle là mã, không chỉ là cấu hình. Nó có thể sử dụng điều kiện, vòng lặp, lời gọi phương thức và tập lệnh bên ngoài.

Các tệp Gradle được lưu trữ trong thư mục gốc của mô-đun (app/build.gradle) và thư mục gốc của dự án (build.gradle). Ngoài ra, Gradle hỗ trợ apply from — bao gồm các tập lệnh Gradle bên ngoài. Điều này cho phép trích xuất logic lặp lại vào các tệp có cài đặt dùng chung. Với sự ra đời của Convention Plugins (AGP 7+), apply from được coi là lỗi thời — Convention Plugins cung cấp cách tái sử dụng cấu hình giữa các mô-đun một cách an toàn về kiểu và có thể kết hợp.

Sự phát triển của build.gradle

Từ năm 2013, cú pháp build.gradle đã trải qua những thay đổi đáng kể: từ Groovy với cấu hình động đến Kotlin DSL với kiểm tra tại thời điểm biên dịch. AGP đã phát triển từ phiên bản 1.0 lên 8.7 (2025). Các cột mốc chính: AGP 3.0 (Java 8 desugar, variant API mới), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL mặc định, Java 11 tối thiểu), AGP 8.0 (lớp R không bắc cầu, cấu hình xây dựng trong Kotlin), AGP 8.7 (KSP thay vì kapt, cấu hình nhanh).

Project-level và Module-level build.gradle

Project-level build.gradle (gốc) xác định plugin, kho lưu trữ và cấu hình chung cho tất cả các mô-đun. Các khối chính: plugins (khai báo plugin Gradle), repositories (nguồn phụ thuộc: mavenCentral, google, jitpack). build.gradle gốc thường không có khối android — nó xuất hiện trong các mô-đun. Project-level cũng có thể chứa khối subprojects để cấu hình chung cho tất cả các dự án con, mặc dù Convention Plugins được ưa chuộng hơn.

Module-level build.gradle (ví dụ: app/build.gradle) mô tả một mô-đun cụ thể. Nếu mô-đun là ứng dụng, nó áp dụng plugin com.android.application. Nếu là thư viện — com.android.library. Module-level chứa: khối android (compileSdk, defaultConfig, buildTypes, productFlavors), khối dependencies (phụ thuộc mô-đun) và tùy chọn các khối để cấu hình kiểm thử và đóng gói. Module-level chạy sau project-level và có thể ghi đè cài đặt chung.

Bắt đầu từ AGP 8.0, build.gradle gốc có thể sử dụng version catalogs (libs.versions.toml) để quản lý tập trung phiên bản phụ thuộc. version catalog là tệp trong thư mục gradle/ chứa phiên bản, thư viện và plugin. Trong build.gradle, phụ thuộc được kết nối qua libs: implementation(libs.retrofit). version catalogs là bắt buộc cho các dự án mới và được khuyến nghị cho tất cả các dự án có ba mô-đun trở lên.

// settings.gradle.kts — gốc dự án
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (project-level)
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts (module-level)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0.0"
    }
}

Groovy vs Kotlin DSL

Groovy là ngôn ngữ JVM động, là cú pháp gốc của Gradle. Các tập lệnh Groovy (.gradle) sử dụng kiểu động: bạn có thể bỏ qua kiểu, sử dụng chuỗi có hoặc không có dấu ngoặc kép, gọi các phương thức không tồn tại tại thời điểm biên dịch. Tính linh hoạt của Groovy cũng là nhược điểm của nó: IDE không thể xác minh cú pháp và kiểu cho đến khi tập lệnh được thực thi, dẫn đến lỗi thời gian chạy do tên tham số hoặc kiểu không chính xác.

Kotlin DSL (.gradle.kts) sử dụng kiểu tĩnh của Kotlin. IDE kiểm tra kiểu, gợi ý các tham số có sẵn thông qua tự động hoàn thành và đánh dấu lỗi tại thời điểm chỉnh sửa. Kotlin DSL chậm hơn trong giai đoạn Configuration (do biên dịch tệp .kts thành bytecode), nhưng Google liên tục cải thiện hiệu suất: AGP 8.5+ sử dụng Gradle Configuration Cache và Caching Kotlin DSL compilation, giảm sự khác biệt xuống còn 1-2 giây.

Google khuyến nghị Kotlin DSL cho tất cả các dự án mới và di chuyển dần các dự án hiện có. Di chuyển từ Groovy sang Kotlin DSL rất đơn giản: dấu ngoặc kép được thay thế bằng dấu ngoặc đơn, kiểu được thêm vào, toán tử được chuyển đổi thành hàm. Hầu hết các thư viện đều cung cấp ví dụ Kotlin DSL trong tài liệu của chúng. Đối với các trường hợp phức tạp (Custom Plugin, Task Graph), Kotlin DSL cung cấp API an toàn về kiểu và ngăn ngừa các lỗi mà trong Groovy chỉ được phát hiện khi chạy. Version catalogs (libs.versions.toml) hoạt động giống nhau với cả hai cú pháp.

Khối android: cấu hình ứng dụng

compileSdk, minSdk và targetSdk

Khối android là phần tử trung tâm của module-level build.gradle. Bên trong nó được cấu hình: namespace (cho R và BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Tất cả các tham số của khối android chỉ áp dụng cho các mô-đun Android. Nếu mô-đun là thư viện, plugin thư viện được sử dụng thay vì application và applicationId không có trong khối android.

compileSdk là phiên bản SDK dùng để biên dịch mã. Nó phải là API Android mới nhất (tại thời điểm viết — 35). minSdk là phiên bản API tối thiểu được hỗ trợ. targetSdk là phiên bản mà ứng dụng nhắm mục tiêu (các thay đổi hành vi của phiên bản này được áp dụng). Sự khác biệt giữa compileSdk và targetSdk: compileSdk xác định API có sẵn, targetSdk xác định hành vi thời gian chạy. Khuyến nghị: compileSdk = mới nhất, targetSdk = mới nhất - 1 (để kiểm tra thích ứng với các thay đổi mới).

compileOptions đặt khả năng tương thích Java: sourceCompatibility và targetCompatibility. AGP 8+ yêu cầu Java 17+ để biên dịch. packaging quản lý việc bao gồm tệp từ thư viện: exclude, merge, pickFirst để giải quyết xung đột META-INF. buildFeatures bật/tắt ViewBinding, DataBinding, Compose. aaptOptions cấu hình xử lý tài nguyên: ignoreAssetsPattern, cruncherEnabled. Mỗi phần tử của khối android tối ưu hóa một khía cạnh cụ thể của việc xây dựng.

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

Quản lý phụ thuộc

BOM (Bill of Materials)

Phụ thuộc trong build.gradle là các thư viện và mô-đun được kết nối với dự án. Khối dependencies nằm cùng cấp với khối android. Gradle hỗ trợ nhiều cấu hình: implementation (thư viện có sẵn trong mô-đun này, không bắc cầu), api (thư viện có sẵn theo cách bắc cầu cho các mô-đun phụ thuộc), compileOnly (chỉ biên dịch, không bao gồm trong APK), runtimeOnly (chỉ thời gian chạy), annotationProcessor / ksp (trình xử lý chú thích), testImplementation (chỉ kiểm thử), androidTestImplementation (chỉ kiểm thử công cụ).

Bắt đầu từ AGP 8.0, Lớp R không bắc cầu — mỗi thư viện có lớp R riêng, ngăn ngừa xung đột tài nguyên. Trong khối dependencies, điều quan trọng là sử dụng đúng cấu hình: implementation không hiển thị phụ thuộc bắc cầu, giúp tăng tốc xây dựng. api hiển thị chúng — được sử dụng khi thư viện xuất kiểu từ thư viện khác (ví dụ: Retrofit sử dụng kiểu OkHttp trong API công khai của nó).

Để quản lý phiên bản, nên sử dụng BOM (Bill of Materials) — tệp xây dựng xác định phiên bản thư viện tương thích. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Sau khi kết nối BOM, bạn chỉ có thể chỉ định tên thư viện mà không cần phiên bản — BOM sẽ tự động chọn phiên bản tương thích. Điều này loại bỏ xung đột giữa các phụ thuộc bắc cầu của các thư viện khác nhau. BOM có sẵn cho Firebase, Compose, Kotlin, Ktor, AndroidX.

dependencies {
    // BOM — quản lý phiên bản
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX và Compose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase (phiên bản từ BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Kiểm thử
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle trong dự án đa mô-đun

Trong dự án đa mô-đun, mỗi mô-đun có build.gradle riêng. Để kết nối mô-đun này với mô-đun khác, sử dụng cú pháp implementation(project(":module-name")). Gradle tự động xây dựng lại mô-đun nếu cấu hình của nó thay đổi. Kiến trúc đa mô-đun cải thiện thời gian xây dựng (xây dựng gia tăng, song song) và phân tách trách nhiệm giữa các mô-đun tính năng, mô-đun lõi và thư viện.

Vấn đề chính của các dự án đa mô-đun là trùng lặp cấu hình. Nếu 10 mô-đun có cùng minSdk, compileSdk và phụ thuộc Compose, đó là 10 bản sao trong các tệp build.gradle khác nhau. Giải pháp là Convention Plugins (trước đây là buildSrc). Convention Plugin là plugin Gradle được viết bằng Kotlin áp dụng cho các mô-đun: plugins { id("myapp.android.library") }. Plugin chứa cấu hình chung và các thay đổi được áp dụng ngay lập tức cho tất cả các mô-đun.

Để tổ chức Convention Plugins, sử dụng thư mục build-logic/ trong thư mục gốc của dự án. Nó chứa includeBuild trong settings.gradle và các plugin Kotlin. Convention Plugins có thể được xuất bản lên kho lưu trữ maven để tái sử dụng giữa các dự án. Google khuyến nghị Convention Plugins làm tiêu chuẩn cho các dự án đa mô-đun, thay thế subprojects { } và apply from. Chuyển sang Convention Plugins giúp giảm build.gradle của mô-đun xuống còn 10-15 dòng.

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — sau Convention Plugin
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}