Tiến trình di chuyển DSL/API của Trình bổ trợ Android cho Gradle

Trình bổ trợ Android cho Gradle (AGP) là một hệ thống xây dựng được hỗ trợ cho các ứng dụng Android, đồng thời hỗ trợ biên dịch nhiều loại nguồn khác nhau và liên kết chúng với nhau thành một ứng dụng mà bạn có thể chạy trên thiết bị Android thực hoặc một trình mô phỏng.

Phần sau đây mô tả sự phát triển theo kế hoạch cho DSL và API của AGP. Khi các API mới được đưa vào trong bản phát hành ổn định, các API cũ sẽ được đánh dấu là không dùng nữa. Sau đó, những API không dùng nữa sẽ ngừng hoạt động trong bản phát hành chính thức tiếp theo. Các phần sau đây cung cấp thông tin về những thay đổi sắp tới trong mỗi bản phát hành AGP chính.

Để biết nhật ký chi tiết hơn về việc ngừng sử dụng hoặc xoá API AGP, hãy xem thông tin cập nhật về API AGP.

AGP 10.0 (cuối năm 2026)

Các thay đổi và hiện đại hoá API của Trình bổ trợ Android cho Gradle 10.0

AGP 10.0 hoàn tất quá trình chuyển đổi sang mô hình bản dựng hoàn toàn trì hoãn và tương thích với bộ nhớ đệm cấu hình. Bản phát hành này là đỉnh cao của nỗ lực kéo dài nhiều năm nhằm thay thế các API cũ, không trì hoãn bằng một kiến trúc an toàn và hiệu suất cao hơn.

Vì sao cần mô hình bản dựng trì hoãn?

Trong mô hình bản dựng cũ, không trì hoãn, Gradle sẽ đánh giá các đối tượng, truy vấn dữ liệu biến thể và định cấu hình các tác vụ trên tất cả các mô-đun dự án trong mỗi lần đồng bộ hoá hoặc gọi bản dựng. Việc đánh giá sớm này sẽ lãng phí thời gian CPU và bộ nhớ trên các biến thể và tác vụ không chạy, đồng thời gây ra xung đột về thứ tự đánh giá trên các tập lệnh bản dựng phức tạp.

Bằng cách chuyển đổi sang mô hình bản dựng hoàn toàn trì hoãn bằng cách sử dụng nhà cung cấp trì hoãn (Provider<T>) và API biến thể hiện đại (androidComponents {}), các thuộc tính và hệ thống dây dẫn tác vụ sẽ được tính toán trì hoãn theo yêu cầu chỉ khi cần thiết cho biểu đồ thực thi bản dựng đang hoạt động.

Các API cũ bị xoá trong bản phát hành này vốn không tương thích với kiến trúc hiện đại này. Việc xoá các API này cho phép AGP hỗ trợ đầy đủ Bộ nhớ đệm cấu hình Gradle và tính năng cách ly dự án, giúp cải thiện đáng kể tốc độ bản dựng và thời gian đồng bộ hoá trong Android Studio.

Sự khác biệt chính về kiến trúc

API BaseVariant cũ (applicationVariants.all {}) là API sớm và tập trung vào tác vụ. API này cho phép nhà phát triển truy cập trực tiếp vào các tác vụ Gradle và cấu hình nội bộ trong giai đoạn định cấu hình, vốn phá vỡ các tính năng hiệu suất hiện đại của Gradle.

API biến thể mới (androidComponents {}) là API trì hoãn và tập trung vào cấu phần phần mềm. API này sử dụng rộng rãi API thuộc tính của Gradle và xoá hoàn toàn mọi tham chiếu đến Task và TaskProvider, yêu cầu bạn tương tác rõ ràng với dữ liệu đầu vào và đầu ra (Variant.artifacts) thay vì các tác vụ cơ bản.

Nội dung bị xoá và thay thế

Tất cả các giao diện và lớp trước đây được sử dụng trong DSL cũ và API biến thể cũ đều sẽ bị xoá. Để chuẩn bị tập lệnh bản dựng và trình bổ trợ tuỳ chỉnh, hãy di chuyển khỏi các API và cờ cuối vòng đời sau đây:

API hoặc tính năng bị xoá Cần thay thế hoặc thực hiện hành động
Quyền truy cập trực tiếp vào tác vụ:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 API cấu phần phần mềm: Thay vì tìm nạp tác vụ để thay đổi hành vi của tác vụ đó, hãy sử dụng variant.artifacts để thêm, sửa đổi hoặc thay thế các tệp thực tế (cấu phần phần mềm) chuyển giữa các tác vụ.
Đăng ký nguồn sớm:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 API nguồn: Kết nối thư mục đầu ra của tác vụ tuỳ chỉnh bằng cách sử dụng variant.sources.java.addGeneratedSourceDirectory(...).
Quyền truy cập vào classpath / cấu hình:
  • getCompileConfiguration()
  • getCompileClasspath()
 API đo lường: Để sửa đổi hoặc kiểm tra mã byte (trường hợp sử dụng phổ biến nhất cho quyền truy cập vào classpath), hãy sử dụng variant.instrumentation.transformClassesWith(...) bằng cách sử dụng AsmClassVisitorFactory.
Đột biến thuộc tính sớm:
  • buildConfigField()
  • resValue()
 Các thực thể `MapProperty` trì hoãn: Sử dụng variant.buildConfigFields.put(...) và variant.manifestPlaceholders.put(...).
Cờ chọn không sử dụng:
  • android.newDsl
  • android.builtInKotlin
 Không có loại thay thế trực tiếp. Xoá các cờ này khỏi gradle.properties; DSL hiện đại và Kotlin tích hợp được thực thi nghiêm ngặt.
Các phần mở rộng API biến thể cũ:
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 Thay thế bằng androidComponents.onVariants().
Lọc biến thể (khối variantFilter) Thay thế bằng androidComponents.beforeVariants() bằng cách sử dụng bộ chọn biến thể.
Các thành phần SDK và NDK:
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 Truy cập vào các thành phần SDK bằng cách sử dụng androidComponents.sdkComponents.
Môi trường kiểm thử:
  • deviceProvider
  • testServer
 Di chuyển quá trình đăng ký thiết bị kiểm thử tuỳ chỉnh sang các thiết bị do Gradle quản lý.
Các API đăng ký không dùng nữa:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 Đã xoá mà không thay thế trực tiếp.
API chuyển đổi Thay thế các phép chuyển đổi bằng API cấu phần phần mềm và AsmClassVisitorFactory.

Để truy cập vào tất cả các giao diện và lớp DSL và API biến thể thay thế (androidComponents {}) , hãy luôn sử dụng cấu phần phần mềm gradle-api khi phát triển các trình bổ trợ Gradle tuỳ chỉnh hoặc logic bản dựng.

Các bước di chuyển

Để giúp quá trình nâng cấp lên AGP 10.0 diễn ra liền mạch và có thể dự đoán được, hãy làm theo các phương pháp di chuyển sau:

  1. Chạy Trợ lý nâng cấp AGP: Trước khi nâng cấp trực tiếp lên 10.0, hãy chạy Trợ lý nâng cấp AGP chính thức trong Android Studio (Tools > AGP Upgrade Assistant). Trợ lý này tự động hoá một số quá trình di chuyển DSL và tập lệnh bản dựng phổ biến, đồng thời giúp duy trì các hành vi bản dựng hiện có.
  2. Sử dụng các kỹ năng ở Chế độ tác nhân trong Android Studio: Tận dụng các kỹ năng nâng cấp bằng AI (chẳng hạn như các kỹ năng nâng cấp AGP có trong kho lưu trữ kỹ năng Android) để tự động hoá và đơn giản hoá việc di chuyển các DSL và logic bản dựng phức tạp bên trong Android Studio.
  3. Khắc phục cảnh báo không dùng nữa trong AGP 9.x trước: Nâng cấp dự án của bạn lên bản phát hành AGP 9.x mới nhất và giải quyết tất cả các cảnh báo không dùng nữa hiện có. Sau khi dự án của bạn hoạt động với 9.x mà không có cảnh báo và không dựa vào android.newDsl=false hoặc android.builtInKotlin=false, việc chuyển sang 10.0 sẽ diễn ra suôn sẻ.
  4. Kiểm tra các trình bổ trợ Gradle của bên thứ ba: Đảm bảo các trình bổ trợ của bên thứ ba được nâng cấp lên các phiên bản tương thích với AGP 10.0. Các trình bổ trợ vẫn dựa vào các loại phần mở rộng cũ sẽ gây ra lỗi bản dựng, chẳng hạn như ClassCastException: ... cannot be cast to class BaseExtension.
  5. Sử dụng các công thức di chuyển chính thức: Để xem các ví dụ di chuyển phức tạp trong thế giới thực và so sánh song song, hãy tham khảo kho lưu trữ gradle-recipes chính thức trên GitHub.

Sau đây là so sánh trước và sau cho thấy cách di chuyển từ việc truy vấn sớm các biến thể cũ sang định cấu hình trì hoãn các biến thể bằng cách sử dụng androidComponents {}:

Trước: API biến thể cũ (Đã xoá trong AGP 10.0)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

Sau: API biến thể hiện đại (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

Cách kiểm thử hành vi của AGP 10.0 trong AGP 9.x

Bạn không cần phải đợi bản phát hành AGP 10.0 để bắt đầu kiểm thử hành vi bản dựng và xác thực khả năng tương thích. Trong khi chạy trên bất kỳ bản phát hành AGP 9.x nào, bạn có thể thực thi rõ ràng hành vi của AGP 10.0 bằng cách xác minh rằng gradle.properties sẽ tắt mọi lựa chọn không sử dụng và đặt các cờ hành vi nghiêm ngặt sau:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

Bằng cách thực thi android.newDsl=true và android.builtInKotlin=true, bạn có thể xác minh rằng logic bản dựng tuỳ chỉnh và các trình bổ trợ của bên thứ ba hoàn toàn tương thích với các yêu cầu nghiêm ngặt về API của AGP 10.0.

Chọn không sử dụng dự án con trong quá trình di chuyển

Nếu bạn muốn bật android.newDsl=true trên toàn cầu trong dự án của mình để kiểm thử các hành vi hiện đại, nhưng cần thêm thời gian để di chuyển các dự án con cụ thể, thì bạn có thể chọn không sử dụng các mô-đun riêng lẻ bắt đầu từ AGP 9.4.0-alpha04. Thêm android.newDsl.optOut vào gradle.properties chỉ định đường dẫn dự án:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

Chọn tắt Kotlin tích hợp cho từng mô-đun

Nếu bạn muốn bật Kotlin tích hợp trên toàn cầu trong dự án của mình (android.builtInKotlin=true), nhưng cần thêm thời gian để di chuyển các dự án con cụ thể khỏi kotlin-android (hoặc cho các mô-đun không có mã Kotlin), hãy định cấu hình các mô-đun đó ở cấp DSL thay vì cấp dự án. Đặt enableKotlin = false bên trong tệp bản dựng của mô-đun:

android {
    enableKotlin = false
}

Quy trình phản hồi và báo cáo lỗi

Chúng tôi muốn đảm bảo API biến thể mới hỗ trợ các trường hợp sử dụng mà bạn yêu cầu. Nếu bạn gặp phải trở ngại khi di chuyển khỏi các API cũ mà API biến thể mới không thể đáp ứng trường hợp sử dụng của bạn, hãy làm theo các bước sau để gửi ý kiến phản hồi:

  1. Kiểm tra các mục hiện có: Trước tiên, hãy kiểm tra Lỗi theo dõi toàn cầu API biến thể AGP 10.0 để xem liệu trình chặn di chuyển của bạn đã được biết đến hay chưa và +1 vấn đề đó.
  2. Báo cáo các API bị thiếu: Nếu trường hợp sử dụng của bạn là duy nhất, hãy gửi yêu cầu tính năng mới bằng mẫu API biến thể cụ thể của chúng tôi để chúng tôi có thể điều tra và hỗ trợ.

(Thông tin dự đoán) Đã xoá quyền truy cập vào các lớp AGP nội bộ riêng tư

Giờ đây, phần phụ thuộc vào cấu phần phần mềm gradle sẽ ẩn tất cả các lớp nội bộ và chỉ cấp quyền truy cập biên dịch cho các giao diện và lớp có trong cấu phần phần mềm gradle-api. Điều này tác động đến quá trình biên dịch trình bổ trợ.

Bạn không thể thêm phần phụ thuộc để truy cập vào các lớp nội bộ theo cách thủ công.

AGP 9.0 (tháng 1 năm 2026)

API biến thể mới ổn định, API cũ không còn dùng nữa

Các API biến thể đang được tích hợp trong 4.1 và 4.2 là ổn định và nằm trong cấu phần phần mềm gradle-api. Các giao diện và lớp trước đây được sử dụng trong API biến thể cũ hiện không được dùng nữa và yêu cầu bạn phải chọn sử dụng rõ ràng.

Các giao diện DSL mới là ổn định, các giao diện cũ không còn được dùng nữa.

Các giao diện DSL đang được tích hợp trong 4.1, 4.2 và 7.0 hiện đã ổn định và nằm trong cấu phần phần mềm gradle-api. Các giao diện và lớp trước đây được dùng trong DSL hiện đã ngừng hoạt động và yêu cầu bạn phải chọn sử dụng rõ ràng.

Bạn vẫn có thể truy cập vào các lớp AGP nội bộ riêng tư

Các lớp nội bộ riêng tư của AGP, nằm trong các cấu phần phần mềm khác, vẫn có thể truy cập được trong quá trình biên dịch tệp bản dựng và trình bổ trợ, nhưng bạn không nên sử dụng các lớp này vì chúng có thể thay đổi theo cách phá vỡ vào bất cứ lúc nào.