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 xóa API AGP, hãy xem thông tin cập nhật về API AGP.

AGP 10.0 (cuối năm 2026)

Những thay đổi và hoạt động 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 linh hoạt, tương thích với bộ nhớ đệm cấu hình. Bản phát hành này là kết quả của nỗ lực nhiều năm nhằm thay thế các API cũ, không có tính năng tải trễ bằng một cấu trúc an toàn và hiệu quả hơn.

Tại sao nên dùng mô hình tạo lười?

Trong mô hình bản dựng cũ, không có độ trễ, Gradle sẽ đánh giá các đối tượng một cách nhanh chó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. Quá trình đánh giá này tiêu tốn thời gian CPU và bộ nhớ cho 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 sang mô hình xây dựng hoàn toàn trì hoãn bằng cách sử dụng các trình cung cấp trì hoãn (Provider<T>) và Variant API hiện đại (androidComponents {}), các thuộc tính và việc kết nối tác vụ sẽ được tính toán một cách 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ề cơ bản không tương thích với cấu trúc hiện đại này. Việc xoá các thành phần 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.

Điểm khác biệt chính về kiến trúc

API BaseVariant cũ (applicationVariants.all {}) rất mong muốn và tập trung vào tác vụ. Thao tác 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 vốn dĩ làm hỏng các tính năng hiệu suất hiện đại của Gradle.

Variant API (androidComponents {}) mới có tính chất trì hoãn và tập trung vào cấu phần phần mềm. Nó sử dụng rộng rãi Property API 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 một cách rõ ràng với các đầu vào và đầu ra (Variant.artifacts) thay vì chính các tác vụ cơ bản.

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

Tất cả các giao diện và lớp trước đây được 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ờ đã ngừng hoạt động sau đây:

Xoá API hoặc tính năng Cần thay thế hoặc hành động
Truy cập trực tiếp vào việc cần làm:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 Artifacts API: Thay vì tìm nạp tác vụ để thay đổi hành vi của tác vụ, hãy dùng variant.artifacts để thêm, sửa đổi hoặc thay thế các tệp thực tế (Artifacts) truyền giữa các tác vụ.
Đăng ký nguồn chủ động:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 Sources API: Kết nối thư mục đầu ra của tác vụ tuỳ chỉnh bằng variant.sources.java.addGeneratedSourceDirectory(...).
Quyền truy cập vào đường dẫn lớp / cấu hình:
  • getCompileConfiguration()
  • getCompileClasspath()
 Instrumentation API: Để sửa đổi hoặc kiểm tra mã byte (trường hợp sử dụng phổ biến nhất để truy cập vào đường dẫn lớp), hãy sử dụng variant.instrumentation.transformClassesWith(...) bằng cách sử dụng AsmClassVisitorFactory.
Thay đổi thuộc tính một cách chủ động:
  • buildConfigField()
  • resValue()
 Các thực thể "MapProperty" có độ trễ: Sử dụng variant.buildConfigFields.put(...) và variant.manifestPlaceholders.put(...).
Cờ chọn không tham gia:
  • 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 tiện ích API cũ cho biến thể:
  • 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 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 androidComponents.sdkComponents.
Môi trường thử nghiệm:
  • deviceProvider
  • testServer
 Di chuyển quy trình đăng ký thiết bị thử nghiệm tuỳ chỉnh sang các thiết bị do Gradle quản lý.
Các API đăng ký lỗi thời:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 Bị xoá mà không được thay thế trực tiếp.
Transform API Thay thế các phép biến đổi bằng Artifacts API và AsmClassVisitorFactory.

Để truy cập vào tất cả các giao diện và lớp DSL và Variant API (androidComponents {}) thay thế, 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

Để quá trình nâng cấp lên AGP 10.0 diễn ra suôn sẻ 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 phiên bả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ố quy 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 của Chế độ tác nhân trong Android Studio: Tận dụng các kỹ năng nâng cấp AI (chẳng hạn như các kỹ năng nâng cấp AGP có trong kho kỹ năng Android) để tự động hoá và đơn giản hoá việc di chuyển logic bản dựng và DSL phức tạp trong Android Studio.
  3. Trước tiên, hãy khắc phục các cảnh báo không dùng nữa trong AGP 9.x: 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 phiên bản 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 phiên bản 10.0 sẽ diễn ra suôn sẻ.
  4. Kiểm tra trình bổ trợ Gradle của bên thứ ba: Đảm bảo 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 tiện ích 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: Để biết các ví dụ di chuyển phức tạp trong thực tế 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ừ các biến thể cũ truy vấn một cách háo hức sang các biến thể định cấu hình một cách lười biếng bằng cách sử dụng androidComponents {}:

Trước: Legacy Variant API (Đã 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: Modern Variant API (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 AGP 10.0 trong AGP 9.x

Bạn không cần đợi bản phát hành AGP 10.0 để bắt đầu kiểm thử các hành vi bản dựng và xác thực khả năng tương thích. 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 AGP 10.0 bằng cách xác minh rằng gradle.properties của bạn sẽ tắt mọi lựa chọn không tham gia 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 một số dự án con trong quá trình di chuyển

Nếu muốn bật android.newDsl=true trên toàn bộ dự án để 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ể, 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

Tắt Kotlin tích hợp có chọn lọc theo từng mô-đun

Nếu bạn muốn bật Kotlin tích hợp trên toàn bộ dự án (android.builtInKotlin=true), nhưng cần thêm thời gian để di chuyển các dự án con cụ thể ra khỏi kotlin-android (hoặc đối với 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 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 Variant API 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 AGP 10.0 Variant API để xem vấn đề chặn di chuyển của bạn đã được biết hay chưa, rồi +1 cho vấn đề đó.
  2. Báo cáo 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 về tính năng mới bằng mẫu AGP 10.0 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 ảnh hưở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

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 dùng trong API biến thể cũ hiện không được dùng nữa và yêu cầu chọn sử dụng một cách rõ ràng để sử dụ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 tiềm năng trong phiên bản 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 chọn sử dụng một cách 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.