Gradle KTS — nó là gì, Kotlin DSL cho Gradle và cú pháp

Gradle KTS là gì?

Gradle KTS là một Kotlin DSL (Ngôn ngữ dành riêng cho miền) cung cấp giải pháp thay thế cho Groovy để viết các tệp cấu hình Gradle. Thay vì cú pháp Groovy, các nhà phát triển sử dụng Kotlin — một ngôn ngữ được kiểu chặt chẽ, xác thực tính đúng đắn của cấu hình tại thời điểm biên dịch. KTS lần đầu tiên được giới thiệu trong Gradle 5.0 vào năm 2018 như một tính năng thử nghiệm và đạt đến độ ổn định trong Gradle 6.0.

Mục tiêu chính của KTS là loại bỏ những thiếu sót của Groovy trong các tập lệnh xây dựng. Groovy là một ngôn ngữ được kiểu động, trong đó các lỗi cấu hình chỉ xuất hiện tại thời gian chạy khi thực thi một tác vụ. KTS cho phép phát hiện các lỗi tương tự ở giai đoạn chỉnh sửa mã nhờ kiểu tĩnh của Kotlin. Ngoài ra, KTS cung cấp quyền truy cập vào API Gradle với tài liệu kiểu đầy đủ, giúp đơn giản hóa đáng kể việc học và sử dụng các khối cấu hình phức tạp.

Hệ sinh thái KTS được hỗ trợ bởi tất cả các công cụ chính: Android Studio, IntelliJ IDEA, VS Code với plugin Kotlin và Gradle Build Tool. Tất cả các plugin hiện đại (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) đều cung cấp API thân thiện với Kotlin với kiểu rõ ràng, khiến KTS trở thành lựa chọn ưu tiên cho các dự án mới.

Cách Gradle KTS hoạt động

Gradle KTS sử dụng trình biên dịch Kotlin để xử lý các tệp .gradle.kts. Gradle nhận ra phần mở rộng và chuyển các tập lệnh đến công cụ tập lệnh Kotlin, công cụ này biên dịch chúng thành các lớp. Các lớp này sau đó được Gradle thực thi để xây dựng mô hình dự án. Sự khác biệt chính so với Groovy: các tập lệnh KTS được biên dịch trước, không được diễn giải động, cho phép phát hiện lỗi trước khi bắt đầu thực thi tác vụ.

Kiến trúc KTS dựa trên kotlin-scripting. Mỗi tệp .gradle.kts là một tập lệnh Kotlin với các import ngầm của API Gradle. Nhà phát triển có thể sử dụng bất kỳ cấu trúc Kotlin nào: hàm mở rộng, lambda, lớp dữ liệu và thậm chí khai báo các hàm trợ giúp bên trong tập lệnh xây dựng. Gradle cung cấp một tập hợp các hàm mở rộng để cấu hình kiểu cho các khối: dependencies, android, kotlin và các khối khác.

plugins {
    id("com.android.application") version "8.4.0"
    kotlin("android") version "2.0.21"
}

android {
    namespace = "com.itsectr.app"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.itsectr.app"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0.0"
    }
}

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.06.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.core:core-ktx:1.13.1")
}

Chuyển đổi kiểu trong KTS

Một trong những khác biệt chính giữa KTS và Groovy là cách xử lý kiểu. Trong Groovy, tất cả cấu hình chấp nhận Object, trong khi trong KTS, chúng chấp nhận các kiểu Kotlin cụ thể. Ví dụ: compileSdk chấp nhận Int, không phải chuỗi. Điều này loại bỏ các lỗi liên quan đến kiểu không chính xác: trong Groovy, compileSdk 34 và compileSdk "34" hoạt động giống nhau, trong khi trong KTS chỉ có biến thể đầu tiên là hợp lệ. Sự chặt chẽ này làm cho cấu hình dễ dự đoán và được tài liệu hóa hơn.

Gradle KTS vs Groovy: so sánh

Groovy là DSL gốc cho Gradle và vẫn được hỗ trợ đầy đủ. Tuy nhiên, KTS cung cấp một số lợi thế khiến nó trở thành lựa chọn được khuyến nghị cho các dự án mới. Kiểu tĩnh, hiệu suất chỉnh sửa IDE tốt hơn và cú pháp chặt chẽ hơn là những lý do chính để chuyển sang KTS. Đồng thời, Groovy vẫn giữ được lợi thế về tính ngắn gọn cho các cấu hình đơn giản.

Hiệu suất xây dựng trên KTS và Groovy gần như giống hệt nhau sau khi biên dịch tập lệnh. Các tập lệnh KTS mất nhiều thời gian hơn để biên dịch trong lần chạy đầu tiên hoặc sau khi xóa bộ nhớ đệm, nhưng các bản dựng tiếp theo chạy với tốc độ tương tự như tập lệnh Groovy. Gradle lưu vào bộ nhớ đệm các tập lệnh KTS đã biên dịch trong thư mục xây dựng, do đó việc biên dịch lại chỉ xảy ra khi tập lệnh thay đổi.

Sự lựa chọn giữa KTS và Groovy trong năm 2026 rất rõ ràng: cho các dự án mới — KTS. Google, JetBrains và Gradle khuyến nghị KTS cho tất cả các dự án mới. Groovy vẫn phù hợp để bảo trì các dự án kế thừa nơi việc di chuyển không thực tế do khối lượng cấu hình hoặc các plugin cụ thể không tương thích với KTS.

Ví dụ mã: tập lệnh xây dựng trên KTS

Hãy xem các khối cấu hình điển hình trong KTS cho Android, Kotlin Multiplatform và Compose Multiplatform. Một dự án Android với KTS yêu cầu chỉ định kiểu rõ ràng trong cấu hình buildTypes và productFlavors. Ví dụ dưới đây minh họa việc thiết lập một ứng dụng với hai hương vị.

android {
    buildTypes {
        val release = getByName("release") {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        getByName("debug") {
            applicationIdSuffix = ".debug"
        }
    }

    flavorDimensions += "version"
    productFlavors {
        register("demo") {
            dimension = "version"
            versionNameSuffix = "-demo"
        }
        register("full") {
            dimension = "version"
        }
    }
}

Đối với Kotlin Multiplatform, KTS là bắt buộc — Groovy không hỗ trợ chính xác cấu hình của các mô-đun đa nền tảng. Cấu hình mô-đun KMM bao gồm thiết lập các nền tảng mục tiêu và tập hợp nguồn. Ví dụ dưới đây cho thấy cấu hình mô-đun chia sẻ với iOS và Android.

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions {
                jvmTarget = "17"
            }
        }
    }

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "Shared"
            isStatic = true
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
        }
        androidMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
        }
    }
}

Hàm trợ giúp và tác vụ tùy chỉnh

KTS cho phép khai báo các hàm Kotlin trợ giúp bên trong tập lệnh xây dựng. Điều này đặc biệt thuận tiện cho các cấu hình lặp đi lặp lại như cấu hình ký hoặc quản lý phiên bản. Nhờ kiểu tĩnh, các hàm này có thể được gọi với xác thực tham số tại thời điểm biên dịch, loại bỏ lỗi trong cấu hình ký trước khi xuất bản lên Google Play.

fun Project.configureSigning() {
    android {
        signingConfigs {
            register("release") {
                storeFile = file("release.keystore")
                storePassword = System.getenv("KEYSTORE_PASSWORD")
                keyAlias = System.getenv("KEY_ALIAS")
                keyPassword = System.getenv("KEY_PASSWORD")
            }
        }
    }
}

// Sử dụng trong build.gradle.kts
configureSigning()

Di chuyển từ Groovy sang KTS

Việc di chuyển từ Groovy sang KTS là một quá trình có thể thực hiện dần dần. Gradle hỗ trợ các dự án hỗn hợp nơi một số mô-đun sử dụng Groovy (build.gradle) và một số sử dụng KTS (build.gradle.kts). settings.gradle và build.gradle gốc có thể được di chuyển trước vì chúng không phụ thuộc vào plugin mô-đun. Google khuyến nghị bắt đầu di chuyển với settings.gradle.kts, sau đó là build.gradle.kts gốc, và chỉ sau đó mới đến các mô-đun.

Các bước di chuyển chính bao gồm: thay thế cú pháp closure bằng lambda, thêm dấu = cho gán, thay thế khóa chuỗi bằng hằng số kiểu và kiểu rõ ràng cho biến. Android Studio cung cấp chuyển đổi tự động Groovy → KTS cho các khối đơn giản, nhưng các cấu hình phức tạp với closure lồng nhau yêu cầu viết lại thủ công.

Các vấn đề di chuyển điển hình bao gồm các lệnh gọi phương thức Groovy ngầm không có tương đương Kotlin và các plugin không cung cấp API thân thiện với Kotlin. Đối với vấn đề đầu tiên, Gradle cung cấp khả năng tương thích thông qua withGroovyBuilder — một cơ chế cho phép gọi các phương thức Groovy từ KTS. Đối với vấn đề thứ hai — cần đợi bản cập nhật plugin hoặc sử dụng nó trong mô-đun Groovy cho đến khi di chuyển hoàn tất.

Gradle KTS cho Kotlin Multiplatform

Kotlin Multiplatform là dự án chính mà KTS là yêu cầu bắt buộc. Plugin kotlin multiplatform cung cấp các tiện ích mở rộng để cấu hình nền tảng mục tiêu, tập hợp nguồn và tệp nhị phân framework chỉ khả dụng thông qua Kotlin DSL. Groovy không hỗ trợ chính xác cấu hình đa nền tảng, do đó các dự án KMM sử dụng độc quyền KTS.

Cấu hình KMM trong KTS bao gồm các khối không tiêu chuẩn: kotlin.target để chỉ định nền tảng, kotlin.sourceSets để tổ chức mã chung và mã dành riêng cho nền tảng, kotlin.cocoapods để tích hợp với CocoaPods và kotlin.jvmToolchain để chọn JDK. Mỗi khối có một API được kiểu chặt chẽ với tự động hoàn thành trong Android Studio, điều này đặc biệt có giá trị cho cấu hình dự án KMM phức tạp với nhiều nền tảng.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

    cocoapods {
        summary = "Shared Kotlin module"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = false
        }
        pod("Alamofire") {
            version = "5.9"
        }
    }
}

Nhờ kiểu tĩnh của KTS, các nhà phát triển KMM nhận được tự động hoàn thành cho tập hợp nguồn và phụ thuộc, kiểm tra kiểu của cấu hình framework và khả năng tái cấu trúc tên nền tảng. KTS cũng đơn giản hóa việc gỡ lỗi: lỗi trong cấu hình KMM xuất hiện dưới dạng lỗi biên dịch Kotlin với thông báo rõ ràng, không giống như Groovy nơi lỗi có thể bị ẩn cho đến khi thực thi một tác vụ Gradle.