جدول زمانی مهاجرت DSL/API افزونه Android Gradle

افزونه‌ی گریدل اندروید (AGP) سیستم ساخت پشتیبانی‌شده برای برنامه‌های اندروید است و شامل پشتیبانی از کامپایل انواع مختلف منابع و پیوند دادن آنها به یکدیگر در قالب یک برنامه است که می‌توانید آن را روی یک دستگاه اندروید فیزیکی یا یک شبیه‌ساز اجرا کنید.

بخش زیر، تکامل برنامه‌ریزی‌شده‌ی DSL و API مربوط به AGP را شرح می‌دهد. با معرفی APIهای جدید در نسخه‌های پایدار، APIهای قدیمی به عنوان منسوخ‌شده علامت‌گذاری می‌شوند. سپس این APIهای منسوخ‌شده در نسخه پایدار بعدی از دسترس خارج می‌شوند. بخش‌های زیر اطلاعاتی در مورد تغییرات آتی در هر نسخه اصلی AGP ارائه می‌دهند.

برای گزارش دقیق‌تر از منسوخ شدن‌ها یا حذف‌های API AGP، به به‌روزرسانی‌های API AGP مراجعه کنید.

AGP 10.0 (اواخر ۲۰۲۶)

تغییرات و نوسازی API افزونه Gradle نسخه ۱۰.۰ اندروید

AGP 10.0 گذار به یک مدل ساخت کاملاً تنبل و سازگار با حافظه پنهان پیکربندی را تکمیل می‌کند. این نسخه، اوج تلاش چند ساله برای جایگزینی APIهای قدیمی و غیر تنبل با معماری ایمن‌تر و کارآمدتر است.

چرا یک مدل ساخت تنبل؟

در مدل ساخت قدیمی و غیر تنبل، Gradle مشتاقانه اشیاء را ارزیابی می‌کند، داده‌های متغیر را پرس‌وجو می‌کند و وظایف را در تمام ماژول‌های پروژه در طول هر فراخوانی همگام‌سازی یا ساخت پیکربندی می‌کند. این ارزیابی مشتاقانه، زمان و حافظه CPU را برای متغیرها و وظایفی که در حال اجرا نیستند، هدر می‌دهد و باعث ایجاد تداخل در ترتیب ارزیابی در اسکریپت‌های ساخت پیچیده می‌شود.

با گذار به یک مدل ساخت کاملاً تنبل با استفاده از ارائه‌دهندگان تنبل ( Provider<T> ) و API مدرن Variant ( androidComponents {} )، ویژگی‌ها و سیم‌کشی وظایف فقط در صورت نیاز توسط گراف اجرای ساخت فعال، به صورت تنبل و بر اساس تقاضا محاسبه می‌شوند.

APIهای قدیمی که در این نسخه حذف شدند، اساساً با این معماری مدرن سازگار نبودند. حذف آنها AGP را قادر می‌سازد تا به طور کامل از Gradle Configuration Cache و Project Isolation پشتیبانی کند، که به طور چشمگیری سرعت ساخت و زمان همگام‌سازی را در اندروید استودیو بهبود می‌بخشد.

تفاوت اصلی معماری

رابط برنامه‌نویسی قدیمی BaseVariant ( applicationVariants.all {} ) مشتاق و وظیفه‌محور بود. این رابط به توسعه‌دهندگان دسترسی مستقیم به وظایف Gradle و پیکربندی‌های داخلی در طول مرحله پیکربندی می‌داد، که ذاتاً ویژگی‌های عملکرد مدرن Gradle را مختل می‌کند.

API جدید Variant ( androidComponents {} ) تنبل و مبتنی بر مصنوعات است. این API به طور گسترده از Property API مربوط به Gradle استفاده می‌کند و تمام ارجاعات به Task و TaskProvider را به طور کامل حذف می‌کند و شما را ملزم می‌کند که به جای خود وظایف اساسی، به طور واضح با ورودی‌ها و خروجی‌ها ( Variant.artifacts ) تعامل داشته باشید.

چه چیزی حذف و جایگزین می‌شود؟

تمام رابط‌ها و کلاس‌های قبلی مورد استفاده در DSL قدیمی و API نوع قدیمی حذف شده‌اند. برای آماده‌سازی اسکریپت‌های ساخت و افزونه‌های سفارشی خود، از APIها و پرچم‌های منسوخ‌شده‌ی زیر مهاجرت کنید:

API یا ویژگی حذف شده تعویض یا اقدام مورد نیاز
دسترسی مستقیم به وظایف:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 API مربوط به Artifacts: به جای واکشی وظیفه برای تغییر رفتار آن، از variant.artifacts برای افزودن، تغییر یا جایگزینی فایل‌های واقعی (Artifacts) که بین وظایف رد و بدل می‌شوند، استفاده کنید.
ثبت منبع مشتاق:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 API منابع: دایرکتوری خروجی وظیفه سفارشی خود را با استفاده از variant.sources.java.addGeneratedSourceDirectory(...) به هم متصل کنید.
دسترسی به مسیر کلاس/پیکربندی:
  • getCompileConfiguration()
  • getCompileClasspath()
 API ابزار دقیق: برای تغییر یا بررسی بایت‌کد (رایج‌ترین مورد استفاده برای دسترسی به classpath)، از variant.instrumentation.transformClassesWith(...) با استفاده از AsmClassVisitorFactory استفاده کنید.
جهش ویژگی مشتاق:
  • buildConfigField()
  • resValue()
 نمونه‌های تنبلِ `MapProperty`: variant.buildConfigFields.put(...) و variant.manifestPlaceholders.put(...) استفاده کنید.
پرچم‌های انصراف:
  • android.newDsl
  • android.builtInKotlin
 جایگزین مستقیمی وجود ندارد. این پرچم‌ها را از gradle.properties حذف کنید؛ DSL مدرن و کاتلین داخلی به شدت اعمال می‌شوند.
افزونه‌های API نسخه قدیمی:
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 با androidComponents.onVariants() جایگزین کنید.
فیلتر کردن متغیرها (بلوک variantFilter ) با استفاده از انتخابگرهای متغیر، androidComponents.beforeVariants() ‎ را جایگزین کنید.
اجزای SDK و NDK:
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 با استفاده از androidComponents.sdkComponents به اجزای SDK دسترسی پیدا کنید.
محیط‌های آزمایش:
  • deviceProvider
  • testServer
 ثبت دستگاه‌های تست سفارشی را به دستگاه‌های مدیریت‌شده توسط Gradle منتقل کنید.
API های ثبت نام منسوخ شده:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 بدون جایگزینی مستقیم حذف شد.
API تبدیل تبدیل‌ها را با Artifacts API و AsmClassVisitorFactory جایگزین کنید.

برای دسترسی به تمام رابط‌ها و کلاس‌های جایگزین DSL و Variant API ( androidComponents {} )، همیشه هنگام توسعه افزونه‌های سفارشی Gradle یا منطق ساخت، از gradle-api artifact استفاده کنید.

مراحل مهاجرت

برای اینکه ارتقاء به AGP 10.0 بدون مشکل و قابل پیش‌بینی باشد، این شیوه‌های مهاجرت را دنبال کنید:

  1. دستیار ارتقاء AGP را اجرا کنید: قبل از ارتقاء مستقیم به نسخه ۱۰.۰، دستیار رسمی ارتقاء AGP را در اندروید استودیو ( Tools > AGP Upgrade Assistant ) اجرا کنید. این ابزار چندین انتقال اسکریپت DSL و build رایج را خودکار می‌کند و به حفظ رفتارهای موجود در build کمک می‌کند.
  2. از مهارت‌های حالت عامل (Agent Mode) در اندروید استودیو استفاده کنید: از مهارت‌های ارتقاء هوش مصنوعی (مانند مهارت‌های ارتقاء AGP موجود در مخزن مهارت‌های اندروید ) برای خودکارسازی و ساده‌سازی مهاجرت منطق ساخت پیچیده و DSLها در اندروید استودیو بهره ببرید.
  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 مراجعه کنید.

در اینجا مقایسه‌ای قبل و بعد نشان داده شده است که چگونه می‌توان با استفاده از androidComponents {} از پرس‌وجوی مشتاقانه‌ی انواع قدیمی به پیکربندی تنبلانه‌ی انواع مهاجرت کرد:

قبل: رابط برنامه‌نویسی قدیمی (در 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
        }
    }
}

بعد از: 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، می‌توانید با تأیید اینکه gradle.properties شما هرگونه opt-out را غیرفعال می‌کند و پرچم‌های رفتاری سختگیرانه زیر را تنظیم می‌کند، رفتار AGP 10.0 را به صراحت اعمال کنید:

# 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

غیرفعال‌سازی انتخابی کاتلین داخلی برای هر ماژول

اگر می‌خواهید کاتلین داخلی را به صورت سراسری در کل پروژه خود فعال کنید ( android.builtInKotlin=true )، اما برای انتقال زیرپروژه‌های خاص از kotlin-android (یا برای ماژول‌هایی که کد کاتلین ندارند) به زمان بیشتری نیاز دارید، آن ماژول‌ها را در سطح DSL به جای سطح پروژه پیکربندی کنید. enableKotlin = false درون فایل ساخت ماژول تنظیم کنید:

android {
    enableKotlin = false
}

گردش کار بازخورد و گزارش اشکال

ما می‌خواهیم مطمئن شویم که API نوع جدید، موارد استفاده مورد نیاز شما را پشتیبانی می‌کند. اگر در مهاجرت از APIهای قدیمی با مانعی مواجه شدید که API نوع جدید نمی‌تواند مورد استفاده شما را در خود جای دهد، برای ارائه بازخورد، این مراحل را دنبال کنید:

  1. بررسی موارد موجود: ابتدا، اشکال ردیابی جهانی API نوع AGP 10.0 را بررسی کنید تا ببینید آیا مسدودکننده مهاجرت شما از قبل شناخته شده است یا خیر، و مشکل را +1 کنید.
  2. گزارش APIهای از دست رفته: اگر مورد استفاده شما منحصر به فرد است، با استفاده از الگوی API نوع خاص ما، درخواست ویژگی جدیدی را ثبت کنید تا بتوانیم آن را بررسی و کمک کنیم.

(آزمایشی) دسترسی به کلاس‌های خصوصی داخلی AGP حذف شده است

وابستگی به gradle artifact اکنون تمام کلاس‌های داخلی را پنهان می‌کند و فقط به رابط‌ها و کلاس‌های موجود در gradle-api artifact دسترسی کامپایل می‌دهد. این امر بر کامپایل افزونه تأثیر می‌گذارد.

اضافه کردن دستی یک وابستگی برای دسترسی به کلاس‌های داخلی امکان‌پذیر نیست.

AGP 9.0 (ژانویه 2026)

APIهای نوع جدید پایدار هستند، APIهای قدیمی منسوخ شده‌اند

APIهای Variant که در نسخه‌های ۴.۱ و ۴.۲ در حال توسعه بودند، پایدار هستند و در gradle-api قرار دارند. رابط‌ها و کلاس‌های قبلی که در API Variant قدیمی استفاده می‌شدند، اکنون منسوخ شده‌اند و برای استفاده نیاز به انتخاب صریح دارند.

رابط‌های DSL جدید پایدار هستند، رابط‌های قدیمی منسوخ شده‌اند

رابط‌های DSL که در نسخه‌های ۴.۱، ۴.۲ و ۷.۰ در حال توسعه بودند، اکنون پایدار هستند و در gradle-api قرار دارند. رابط‌ها و کلاس‌های قبلی مورد استفاده در DSL اکنون منسوخ شده‌اند و برای استفاده نیاز به انتخاب صریح دارند.

کلاس‌های خصوصی داخلی AGP هنوز در دسترس هستند

کلاس‌های داخلی خصوصی از AGP، که در سایر مصنوعات قرار دارند، همچنان در طول کامپایل فایل‌های ساخت و افزونه‌ها قابل دسترسی هستند، اما استفاده از آنها را توصیه نمی‌کنیم زیرا ممکن است در هر زمانی در نحوه‌ی شکستن تغییر کنند.