ไทม์ไลน์การย้ายข้อมูล DSL/API ของปลั๊กอิน Android Gradle

ปลั๊กอิน Android Gradle (AGP) เป็นระบบบิลด์ที่รองรับสำหรับแอปพลิเคชัน Android และรองรับการคอมไพล์แหล่งที่มาหลายประเภท และลิงก์เข้าด้วยกันเป็นแอปพลิเคชันที่คุณเรียกใช้ในอุปกรณ์ Android จริง หรือโปรแกรมจำลองได้

ส่วนต่อไปนี้จะอธิบายวิวัฒนาการที่วางแผนไว้ของ DSL และ API ของ AGP เมื่อมีการเปิดตัว API ใหม่ในรุ่นที่เสถียร ระบบจะทําเครื่องหมาย API เก่าว่า เลิกใช้แล้ว จากนั้น API ที่เลิกใช้งานแล้วจะใช้งานไม่ได้ในรุ่นเสถียรถัดไป ส่วนต่อไปนี้จะให้ข้อมูลเกี่ยวกับการเปลี่ยนแปลงที่กำลังจะมีขึ้น ใน AGP แต่ละรุ่นหลัก

ดูบันทึกการเลิกใช้งานหรือการนำ AGP API ออกโดยละเอียดได้ที่การอัปเดต AGP API

AGP 10.0 (ปลายปี 2026)

การเปลี่ยนแปลง API และการปรับปรุงปลั๊กอิน Android Gradle 10.0

AGP 10.0 จะเปลี่ยนไปใช้โมเดลบิลด์ที่รองรับแคชการกำหนดค่าและเลซีอย่างเต็มรูปแบบ การเปิดตัวนี้เป็นผลลัพธ์ของความพยายามหลายปีในการแทนที่ API เดิมที่ไม่ใช่แบบ Lazy ด้วยสถาปัตยกรรมที่ปลอดภัยและมีประสิทธิภาพมากขึ้น

ทำไมถึงต้องใช้โมเดลการสร้างแบบเลซี

ในโมเดลการสร้างแบบเดิมที่ไม่ใช่แบบ Lazy Gradle จะประเมินออบเจ็กต์ ค้นหา ข้อมูลตัวแปร และกำหนดค่างานในโมดูลโปรเจ็กต์ทั้งหมดอย่างกระตือรือร้นในระหว่างการซิงค์ หรือการเรียกใช้การสร้างทุกครั้ง การประเมินแบบกระตือรือร้นนี้ทำให้เสียเวลา CPU และหน่วยความจำไปกับ ตัวแปรและงานที่ไม่ได้ทำงาน และทำให้เกิดความขัดแย้งในการจัดลำดับการประเมิน ในสคริปต์การสร้างที่ซับซ้อน

การเปลี่ยนไปใช้โมเดลบิลด์แบบเลซีอย่างเต็มรูปแบบโดยใช้ Lazy Providers (Provider<T>) และ Variant API ที่ทันสมัย (androidComponents {}) จะทำให้ระบบคำนวณพร็อพเพอร์ตี้ และการเชื่อมต่อทาสก์แบบเลซีตามต้องการเฉพาะเมื่อกราฟการดำเนินการบิลด์ที่ใช้งานอยู่ต้องการเท่านั้น

API เดิมที่จะนำออกในรุ่นนี้ไม่สามารถใช้งานร่วมกับสถาปัตยกรรมสมัยใหม่นี้ได้ การนำออกจะช่วยให้ AGP รองรับ แคชการกำหนดค่า Gradle และการแยกโปรเจ็กต์ได้อย่างเต็มที่ ซึ่งจะช่วยปรับปรุง ความเร็วในการสร้างและเวลาในการซิงค์ใน Android Studio ได้อย่างมาก

ความแตกต่างหลักของสถาปัตยกรรม

BaseVariant API (applicationVariants.all {}) เวอร์ชันเดิมมีความกระตือรือร้นและ มุ่งเน้นที่งาน ซึ่งช่วยให้นักพัฒนาแอปเข้าถึงงาน Gradle และการกำหนดค่าภายในได้โดยตรงในระหว่างขั้นตอนการกำหนดค่า ซึ่งทำให้ฟีเจอร์ประสิทธิภาพของ Gradle สมัยใหม่ใช้งานไม่ได้

Variant API ใหม่ (androidComponents {}) จะทำงานแบบเลซีและเน้นที่อาร์ติแฟกต์ โดยจะใช้ Property API ของ Gradle อย่างกว้างขวางและนำการอ้างอิงทั้งหมดไปยัง Task และ TaskProvider ออกทั้งหมด ซึ่งกำหนดให้คุณต้องโต้ตอบกับอินพุตและ เอาต์พุต (Variant.artifacts) อย่างชัดเจนแทนที่จะเป็นงานพื้นฐานเอง

สิ่งที่กำลังจะถูกนำออกและแทนที่

ระบบจะลบอินเทอร์เฟซและคลาสก่อนหน้าทั้งหมดที่ใช้ใน DSL เดิมและ Variant API เก่า หากต้องการเตรียมสคริปต์บิลด์และปลั๊กอินที่กำหนดเอง ให้ย้ายข้อมูล ออกจาก API และค่าสถานะที่สิ้นสุดการใช้งานต่อไปนี้

API หรือฟีเจอร์ที่นำออก ต้องเปลี่ยนหรือดำเนินการ
การเข้าถึงงานโดยตรง
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 Artifacts API: แทนที่จะดึงข้อมูลงานเพื่อ เปลี่ยนลักษณะการทำงาน ให้ใช้ variant.artifacts เพื่อ ผนวก แก้ไข หรือแทนที่ไฟล์จริง (อาร์ติแฟกต์) ที่ส่งผ่านระหว่าง งาน
การลงทะเบียนแหล่งที่มาแบบ Eager
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 Sources API: เชื่อมต่อเอาต์พุตของไดเรกทอรีงานที่กำหนดเองโดยใช้ variant.sources.java.addGeneratedSourceDirectory(...)
การเข้าถึง Classpath / การกำหนดค่า
  • getCompileConfiguration()
  • getCompileClasspath()
 Instrumentation API: หากต้องการแก้ไขหรือตรวจสอบไบต์โค้ด (กรณีการใช้งานที่พบบ่อยที่สุดสำหรับการเข้าถึง classpath) ให้ใช้ variant.instrumentation.transformClassesWith(...) โดยใช้ AsmClassVisitorFactory
การเปลี่ยนแปลงพร็อพเพอร์ตี้แบบกระตือรือร้น
  • buildConfigField()
  • resValue()
 อินสแตนซ์ `MapProperty` แบบเลซี: ใช้ variant.buildConfigFields.put(...) และ variant.manifestPlaceholders.put(...)
Flag การเลือกไม่ใช้
  • android.newDsl
  • android.builtInKotlin
 ไม่มีการแทนที่โดยตรง นำฟีเจอร์เหล่านี้ออกจาก gradle.properties; ระบบจะบังคับใช้ DSL ที่ทันสมัยและ Kotlin ในตัว อย่างเคร่งครัด
ส่วนขยาย API ตัวแปรเดิม
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 แทนที่ด้วย androidComponents.onVariants()
การกรองตัวแปร (variantFilter บล็อก) แทนที่ด้วย androidComponents.beforeVariants() โดยใช้ ตัวเลือกรูปแบบ
คอมโพเนนต์ SDK และ NDK
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 เข้าถึงคอมโพเนนต์ SDK โดยใช้ androidComponents.sdkComponents
สภาพแวดล้อมการทดสอบ
  • deviceProvider
  • testServer
 ย้ายข้อมูลการลงทะเบียนอุปกรณ์ทดสอบที่กำหนดเองไปยังอุปกรณ์ที่มีการจัดการจาก Gradle
API การลงทะเบียนที่ล้าสมัย
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 ลบแล้วโดยไม่มีการแทนที่โดยตรง
Transform API แทนที่การแปลงด้วย Artifacts API และ AsmClassVisitorFactory

หากต้องการเข้าถึง DSL และ Variant API (androidComponents {}) อินเทอร์เฟซและคลาสทั้งหมดที่ใช้แทน ให้ใช้ชิ้นงาน gradle-api เสมอเมื่อพัฒนาปลั๊กอิน Gradle ที่กำหนดเองหรือตรรกะการสร้าง

ขั้นตอนการย้ายโปรเจ็กต์

โปรดทำตามแนวทางการย้ายข้อมูลต่อไปนี้เพื่อให้การอัปเกรดเป็น AGP 10.0 เป็นไปอย่างราบรื่นและคาดการณ์ได้

  1. เรียกใช้ผู้ช่วยอัปเกรด AGP: ก่อนอัปเกรดเป็น 10.0 โดยตรง ให้เรียกใช้ผู้ช่วยอัปเกรด AGP อย่างเป็นทางการใน Android Studio (Tools > AGP Upgrade Assistant) ซึ่งจะทำการย้ายข้อมูล DSL และสคริปต์บิลด์ทั่วไปหลายรายการโดยอัตโนมัติ และช่วยรักษาลักษณะการทำงานของบิลด์ที่มีอยู่
  2. ใช้ทักษะโหมดเอเจนต์ใน Android Studio: ใช้ประโยชน์จากทักษะการอัปเกรด AI (เช่น ทักษะการอัปเกรด AGP ที่มีอยู่ในที่เก็บทักษะ Android) เพื่อทำให้การย้ายข้อมูลตรรกะการสร้างที่ซับซ้อนและ DSL ภายใน Android Studio เป็นไปโดยอัตโนมัติและง่ายขึ้น
  3. แก้ไขคำเตือนการเลิกใช้งานใน AGP 9.x ก่อน: อัปเกรดโปรเจ็กต์เป็น AGP 9.x เวอร์ชันล่าสุดและแก้ไขคำเตือนการเลิกใช้งานที่มีอยู่ทั้งหมด เมื่อโปรเจ็กต์ของคุณทำงานร่วมกับ 9.x ได้โดยไม่มีคำเตือนและไม่ต้องอาศัย android.newDsl=false หรือ android.builtInKotlin=false การเปลี่ยนไปใช้ 10.0 ก็จะราบรื่น
  4. ตรวจสอบปลั๊กอิน Gradle ของบุคคลที่สาม: ตรวจสอบว่าปลั๊กอินของบุคคลที่สามได้รับการ อัปเกรดเป็นเวอร์ชันที่ใช้ร่วมกับ AGP 10.0 ได้ ปลั๊กอินที่ยังคงใช้ส่วนขยายประเภทเดิมจะทำให้การสร้างล้มเหลว เช่น ClassCastException: ... cannot be cast to class BaseExtension
  5. ใช้สูตรการย้ายข้อมูลอย่างเป็นทางการ: ดูตัวอย่างการย้ายข้อมูลที่ซับซ้อนในสถานการณ์จริงและการเปรียบเทียบแบบเคียงข้างกันได้ในที่เก็บ gradle-recipes ใน GitHub อย่างเป็นทางการ

นี่คือการเปรียบเทียบก่อนและหลังที่แสดงวิธีย้ายข้อมูลจากการค้นหาตัวแปรเดิมอย่างรวดเร็วไปเป็นการกำหนดค่าตัวแปรอย่างช้าๆ โดยใช้ androidComponents {}:

ก่อนหน้า: Legacy Variant API (นำออกใน 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
        }
    }
}

หลังจากนี้: Modern Variant API (androidComponents {})

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

วิธีทดสอบลักษณะการทำงานของ AGP 10.0 ใน AGP 9.x

คุณไม่จำเป็นต้องรอให้ AGP 10.0 เปิดตัวเพื่อเริ่มทดสอบลักษณะการทำงานของบิลด์ และตรวจสอบความเข้ากันได้ ขณะเรียกใช้ AGP 9.x คุณสามารถบังคับใช้ลักษณะการทำงานของ AGP 10.0 อย่างชัดเจนได้โดยตรวจสอบว่า gradle.properties ปิดใช้การเลือกไม่ใช้ทั้งหมดและตั้งค่าสถานะลักษณะการทำงานที่เข้มงวดต่อไปนี้

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

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

การบังคับใช้ android.newDsl=true และ android.builtInKotlin=true จะช่วยให้คุณ ยืนยันได้ว่าตรรกะการบิลด์ที่กำหนดเองและปลั๊กอินของบุคคลที่สาม เข้ากันได้กับข้อกำหนด API ที่เข้มงวดของ AGP 10.0 อย่างสมบูรณ์

การเลือกไม่ใช้โปรเจ็กต์ย่อยบางรายการระหว่างการย้ายข้อมูล

หากต้องการเปิดใช้ android.newDsl=true ทั่วทั้งโปรเจ็กต์เพื่อ ทดสอบลักษณะการทำงานที่ทันสมัย แต่ต้องการเวลาเพิ่มเติมในการย้ายข้อมูลโปรเจ็กต์ย่อยที่เฉพาะเจาะจง คุณ สามารถเลือกไม่ใช้โมดูลแต่ละโมดูลได้ตั้งแต่ AGP 9.4.0-alpha04 เป็นต้นไป เพิ่ม android.newDsl.optOut ไปยัง gradle.properties โดยระบุเส้นทางโปรเจ็กต์

# 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

การปิดใช้ Kotlin ในตัวแบบเฉพาะเจาะจงต่อโมดูล

หากต้องการเปิดใช้ Kotlin ในตัวทั่วทั้งโปรเจ็กต์ (android.builtInKotlin=true) แต่ต้องการเวลาเพิ่มเติมในการย้ายข้อมูลโปรเจ็กต์ย่อยที่เฉพาะเจาะจงออกจาก kotlin-android (หรือสำหรับโมดูลที่ไม่มีโค้ด Kotlin) ให้กำหนดค่าโมดูลเหล่านั้นที่ระดับ DSL แทนระดับโปรเจ็กต์ ตั้งค่า enableKotlin = false ภายในไฟล์บิลด์ของโมดูล

android {
    enableKotlin = false
}

เวิร์กโฟลว์การรายงานข้อบกพร่องและการแสดงความคิดเห็น

เราต้องการให้มั่นใจว่า Variant API ใหม่รองรับกรณีการใช้งานที่คุณต้องการ หากพบปัญหาในการย้ายข้อมูลออกจาก API เก่าซึ่ง API ใหม่ของผลิตภัณฑ์ย่อยไม่รองรับ Use Case ของคุณ ให้ทำตามขั้นตอนต่อไปนี้เพื่อแสดงความคิดเห็น

  1. ตรวจสอบสินค้าที่มีอยู่: ก่อนอื่นให้ตรวจสอบ AGP 10.0 Variant API Global Tracking Bug เพื่อดูว่าปัญหาที่ทำให้ย้ายข้อมูลไม่ได้เป็นปัญหาที่ทราบอยู่แล้วหรือไม่ แล้วกด +1 ที่ปัญหา
  2. รายงาน API ที่ขาดหายไป: หากกรณีการใช้งานของคุณไม่เหมือนใคร โปรดยื่นคำขอฟีเจอร์ใหม่โดยใช้เทมเพลต AGP 10.0 เฉพาะของเรา เพื่อให้เราตรวจสอบและช่วยเหลือได้

(ทดลอง) ระบบจะนำสิทธิ์เข้าถึงคลาส AGP ภายในแบบส่วนตัวออก

ทรัพยากร Dependency บนสิ่งประดิษฐ์ gradle จะซ่อนคลาสภายในทั้งหมด และให้สิทธิ์เข้าถึงการคอมไพล์เฉพาะอินเทอร์เฟซและคลาส ที่อยู่ในสิ่งประดิษฐ์ gradle-api ซึ่งจะส่งผลต่อการคอมไพล์ปลั๊กอิน

คุณเพิ่มการอ้างอิงด้วยตนเองเพื่อเข้าถึงคลาสภายใน ไม่ได้

AGP 9.0 (มกราคม 2026)

API ใหม่ของตัวเลือกมีเสถียรภาพแล้ว ส่วน API เก่าเลิกใช้งานแล้ว

Variant API ที่อยู่ในระยะทดลองใน 4.1 และ 4.2 พร้อมใช้งานแล้วและอยู่ในอาร์ติแฟกต์ gradle-api ตอนนี้อินเทอร์เฟซและคลาสก่อนหน้าซึ่งใช้ใน Variant API เก่าเลิกใช้งานแล้ว และต้องเลือกใช้โดยชัดแจ้งจึงจะใช้งานได้

อินเทอร์เฟซ DSL ใหม่มีความเสถียร ส่วนอินเทอร์เฟซเก่าจะเลิกใช้งาน

อินเทอร์เฟซ DSL ที่อยู่ในระยะทดลองใน 4.1, 4.2 และ 7.0 ตอนนี้เสถียรแล้วและอยู่ในอาร์ติแฟกต์ gradle-api ตอนนี้อินเทอร์เฟซและคลาสก่อนหน้าซึ่งใช้ใน DSL ถูกเลิกใช้งานแล้ว และต้องเลือกใช้โดยชัดแจ้งจึงจะใช้งานได้

ชั้นเรียน AGP ภายในแบบส่วนตัวที่ยังคงเข้าถึงได้

คลาสภายในแบบส่วนตัวจาก AGP ซึ่งอยู่ในอาร์ติแฟกต์อื่นๆ จะยังคงเข้าถึงได้ในระหว่างการคอมไพล์ไฟล์บิลด์และปลั๊กอิน แต่เราไม่แนะนำให้ใช้คลาสเหล่านี้เนื่องจากอาจมีการเปลี่ยนแปลงในลักษณะที่ทำให้เกิดการหยุดทำงานได้ทุกเมื่อ