工具和程式庫的相互依附

建構依附元件是指建構專案時所需的外部元件。建構作業可以依賴程式庫、外掛程式、子專案、Android SDK、工具 (例如 Kotlin 和 Java 編譯器)、開發環境 (例如 Android Studio) 和 Gradle 本身。

每個依附元件本身可能需要其他依附元件。我們稱之為「遞移依附元件」，可以快速增加應用程式使用的整體依附元件。無論是程式庫、工具或 Android SDK，只要您想升級依附元件，升級作業就會依序進行，升級許多其他依附元件。

這通常不會造成任何問題，因為許多程式庫都遵循語意化版本管理的做法。這些程式庫會限制他們所做的變更類型，以提供與較低版本的相容性。

語意版本管理會採用 major.minor.patch 格式。舉例來說，在版本號碼 4.8.3 中，4 是 major 版本，8 是 minor 版本，而 3 是 patch 號碼。當 major 部分變更時，程式庫可能會對 API 或行為造成破壞性變更。這可能會影響您的建構或應用程式行為。

當 minor (新功能) 或 patch (錯誤修正) 部分變更時，程式庫開發人員會告知您，程式庫仍相容，且不會影響您的應用程式。

因此，您必須留意這類變更，而多種依附元件升級工具可提供協助。

建構內容中的關係

Android 版本包含以下之間的關係：

• 原始碼：您可控管的程式碼和資源
• 程式庫依附元件：專案和子專案在建構時所包含的外部程式庫或模組
• 工具：編譯器、外掛程式和 SDK，可將來源轉譯為應用程式或程式庫

原始碼

原始碼是您在應用程式或程式庫中編寫的 Kotlin 或 Java 程式碼。(如要進一步瞭解使用 C++，請參閱 Android NDK)。

原始碼依附於程式庫 (包括 Kotlin 和 Java 執行階段程式庫) 和 Android SDK，並且需要其對應的 Kotlin 或 Java 編譯器。

某些原始碼含有需要額外處理的註解。舉例來說，當您編寫 Jetpack Compose 程式碼時，必須新增需要由 Compose Kotlin 編譯器外掛程式處理的 @Composable 等註解。其他註解可由 Kotlin 符號處理器 (KSP) 或獨立的註解處理工具處理。

程式庫依附元件

程式庫包含提取至應用程式的位元碼。可以是 Java JAR、Android 程式庫 (AAR) 或建構作業中的子專案。許多程式庫都遵循語義版本管理，可協助您瞭解升級後程式庫是否仍相容。

程式庫可能會依附其他程式庫以便重複使用，稱為遞移依附元件。這會減少必須明確管理的依附元件；您可以指定直接使用的依附元件，Gradle 會連同這些遞移依附元件一起提取依附元件。請注意，當您升級直接依附元件時，這些依附元件可能會升級這些遞移依附元件。

有時，程式庫可能會在執行階段 (minSdk) 或編譯期間 (compileSdk) 要求 Android SDK 的最低版本。如果程式庫使用 Android SDK 或其提供的 JDK API 中的函式，就必須這樣做。應用程式的有效 minSdk 是應用程式和所有直接和遞移的程式庫依附元件所要求的最高 minSdk。

使用某些程式庫時，可能需要使用特定的 Gradle 外掛程式。這些輔助外掛程式通常會安裝 Kotlin 符號處理器或其他註解處理器，以產生程式碼或修改來源編譯內容，以便您使用程式庫功能。舉例來說，Jetpack Room 包含註解和 KSP，可將註解轉換為產生的程式碼，用於擷取及修改資料庫中的資料。Jetpack Compose 需要 Compose 編譯器外掛程式修改註解函式，以便管理該函式的重新執行方式和時間。

工具

Gradle 範圍

Gradle 會將程式庫依附元件分組至不同的範圍 (在 Gradle API 中稱為「設定」)，讓您指定在建構作業的不同部分中要使用的不同程式庫依附元件組合。舉例來說，您可能不想在已發布的應用程式或程式庫中加入 JUnit 等測試程式庫，但在建構及執行單元測試時，您可能會需要這些程式庫。您也可以使用範圍新增符號或註解處理程序，以便分析程式碼。

舉例來說，AGP 會定義 implementation 和 api 範圍，讓您指定是否要向子專案的使用者公開依附元件。如要瞭解在 Android 建構中使用的這些和其他範圍，請參閱「設定依附元件」。

在建構檔案的 dependencies 區塊中新增程式庫依附元件，可做為 group:artifact:version 字串：

// In a module-level build script
// explicit dependency strings ("group:artifact:version")
dependencies {
    implementation("com.example:library1:1.2.3")
    api("com.example:library2:1.1.1")
}

// In a module-level build script
// explicit dependency strings ("group:artifact:version")
dependencies {
    implementation 'com.example:library1:1.2.3'
    api 'com.example:library2:1.1.1'
}

或在版本目錄中執行以下操作：

# Version catalog - gradle/libs.versions.toml
[versions]
exampleLib = "1.2.3"
examplePlugin = "2.3.4"

[libraries]
example-library = { group = "com.example", name = "library", version.ref = "exampleLib" }

[plugins]
example-plugin = { id = "com.example.plugin", version.ref = "examplePlugin" }

並在建構檔案中指定產生的變數：

// In a module-level build script
// Using a version catalog
plugins {
    alias(libs.plugins.example.plugin)
}

dependencies {
    implementation(libs.example.library)
}

// In a module-level build script
// Using a version catalog
plugins {
    alias(libs.plugins.example.plugin)
}

dependencies {
    implementation libs.example.library
}