引入必要依赖并且完善 gradle 配置及注释说明

2025-12-27 15:47:11 +00:00 · 2025-11-28 23:19:32 +08:00
parent 81aa95486e
commit 70e274a5cf
5 changed files with 293 additions and 17 deletions
--- a/app/.gitignore
+++ b/app/.gitignore
@@ -1 +1,3 @@
 /build
+/release/
+/debug/
--- a/app/build.gradle.kts
+++ b/app/build.gradle.kts
@@ -1,55 +1,192 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
 plugins {
+    // Android 应用构建插件
    alias(libs.plugins.android.application)
+    // Kotlin Android 支持
    alias(libs.plugins.kotlin.android)
+    // Compose 编译插件
    alias(libs.plugins.kotlin.compose)
+    // Kotlin 序列化插件
+    alias(libs.plugins.kotlin.serialization)
+    // Hilt 依赖注入插件
+    alias(libs.plugins.hilt)
+    // KSP 注解处理插件
+    alias(libs.plugins.ksp)
 }

 android {
+    // 应用包名（影响最终安装包的 namespace）
+    // https://developer.android.com/jetpack/androidx/versions?hl=zh-cn
    namespace = "com.joker.kit"
+    // 编译期使用的 SDK 版本
    compileSdk {
        version = release(36)
    }

    defaultConfig {
+        // 最终安装包 ID
        applicationId = "com.joker.kit"
+        // 支持的最低 Android 版本
        minSdk = 23
+        // Play 建议的目标 Android 版本
        targetSdk = 36
+        // 递增的内部版本号
        versionCode = 1
-        versionName = "1.0"
+        // 显示给用户的版本名称
+        versionName = "1.0.0"

+        // Instrumentation 测试入口
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+
+        // 仅包括中文和英文必要的语言资源
+        androidResources {
+            // 仅保留常用语种以减小包体
+            @Suppress("UnstableApiUsage")
+            localeFilters += listOf("zh", "en")
+        }
+    }
+
+    // ABI 分包配置 - 一次性打包多个架构版本
+    splits {
+        abi {
+            // 启用 ABI 分包
+            isEnable = true
+            // 重置默认列表
+            reset()
+            // 包含的架构：32位和64位 ARM
+            include("armeabi-v7a", "arm64-v8a")
+            // 是否生成通用 APK（包含所有架构）
+            // 设置为 true 会额外生成一个包含所有架构的 APK
+            isUniversalApk = true
+        }
+    }
+
+    // 签名配置
+    signingConfigs {
+        // 通用签名配置
+        // 如果你的项目需要获取 MD5 或 SHA-1 签名值来做类似三方集成（如微信/支付宝）
+        // 完善以下配置并在 buildTypes 中解除注释后项目中执行命令 ./gradlew signingReport 来获取签名信息
+        create("common") {
+            // 签名文件路径
+            storeFile = file("你的签名文件路径")
+            // 密钥别名
+            keyAlias = "你的密钥别名"
+            // 密钥密码
+            keyPassword = "你的密钥密码"
+            // 签名文件密码
+            storePassword = "你的签名文件密码"
+
+            // 启用所有签名方案以确保最大兼容性
+            // JAR 签名 (Android 1.0+)
+            enableV1Signing = true
+            // APK 签名 v2 (Android 7.0+)
+            enableV2Signing = true
+            // APK 签名 v3 (Android 9.0+)
+            enableV3Signing = true
+            // APK 签名 v4 (Android 11.0+)
+            enableV4Signing = true
+        }
    }

    buildTypes {
+        // debug 构建类型
+        debug {
+            // debug 模式下的签名配置（默认使用 debug 签名）
+            // signingConfig = signingConfigs.getByName("common")
+            // debug 模式下包名后缀
+            applicationIdSuffix = ".debug"
+        }
+
+        // release 构建类型
        release {
-            isMinifyEnabled = false
+            // 是否启用代码压缩
+            isMinifyEnabled = true
+            // 是否启用资源压缩
+            isShrinkResources = true
+            // 正式发布模式下的签名配置（配置完 common 签名配置后，取消注释以下行）
+            // signingConfig = signingConfigs.getByName("common")
+            // 混淆规则文件
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
+
    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_11
-        targetCompatibility = JavaVersion.VERSION_11
-    }
-    kotlinOptions {
-        jvmTarget = "11"
+        // Java 源码/字节码兼容级别
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
    }
+
    buildFeatures {
+        // 开启 Compose 支持
        compose = true
    }
 }

+kotlin {
+    compilerOptions {
+        // Kotlin 编译生成的 JVM 字节码版本
+        jvmTarget.set(JvmTarget.JVM_17)
+    }
+}
+
 dependencies {
+    // AndroidX Core 基础
    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.lifecycle.runtime.ktx)
    implementation(libs.androidx.activity.compose)
+    implementation(libs.androidx.core.splashscreen)
+
+    // Jetpack Compose UI
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.compose.ui)
    implementation(libs.androidx.compose.ui.graphics)
    implementation(libs.androidx.compose.ui.tooling.preview)
    implementation(libs.androidx.compose.material3)
+    implementation(libs.coil.compose)
+
+    // 导航组件
+    implementation(libs.navigation.compose)
+
+    // 序列化
+    implementation(libs.kotlinx.serialization.json)
+
+    // 网络请求 (Retrofit + OkHttp)
+    implementation(libs.retrofit)
+    implementation(libs.retrofit2.kotlinx.serialization.converter)
+    implementation(libs.okhttp)
+    implementation(libs.logging.interceptor)
+    debugImplementation(libs.chucker)
+    releaseImplementation(libs.chucker.no.op)
+
+    // 日志
+    implementation(libs.timber)
+
+    // 依赖注入 (Hilt + Navigation)
+    implementation(libs.hilt.android)
+    ksp(libs.hilt.android.compiler)
+    implementation(libs.hilt.navigation.compose)
+    androidTestImplementation(libs.hilt.android.testing)
+    kspAndroidTest(libs.hilt.android.compiler)
+    compileOnly(libs.ksp.gradlePlugin)
+
+    // 数据库 (Room)
+    implementation(libs.androidx.room.runtime)
+    implementation(libs.androidx.room.ktx)
+    implementation(libs.androidx.room.paging)
+    ksp(libs.androidx.room.compiler)
+    kspTest(libs.androidx.room.compiler)
+    kspAndroidTest(libs.androidx.room.compiler)
+    testImplementation(libs.androidx.room.testing)
+    androidTestImplementation(libs.androidx.room.testing)
+
+    // 调试工具
+    debugImplementation(libs.leakcanary.android)
+
+    // 单元 / UI 测试
    testImplementation(libs.junit)
    androidTestImplementation(libs.androidx.junit)
    androidTestImplementation(libs.androidx.espresso.core)
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -1,6 +1,18 @@
-// Top-level build file where you can add configuration options common to all sub-projects/modules.
+// 顶层构建文件，用于配置所有子项目/模块的通用选项
+
+// 配置项目级插件
 plugins {
+    // Android应用程序插件，用于构建Android应用
    alias(libs.plugins.android.application) apply false
+    // Kotlin Android插件，支持Kotlin语言开发
    alias(libs.plugins.kotlin.android) apply false
+    // Kotlin Compose插件，用于Jetpack Compose UI开发
    alias(libs.plugins.kotlin.compose) apply false
+    // Kotlin Serialization插件
+    alias(libs.plugins.kotlin.serialization) apply false
+    // 依赖注入相关插件
+    // Hilt插件，用于依赖注入框架的支持
+    alias(libs.plugins.hilt) apply false
+    // KSP (Kotlin Symbol Processing)插件，用于注解处理
+    alias(libs.plugins.ksp) apply false
 }
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -1,32 +1,155 @@
 [versions]
+# 构建工具版本
+# Android Gradle Plugin: https://developer.android.com/studio/releases/gradle-plugin
 agp = "8.13.1"
+# Kotlin 编译器: https://kotlinlang.org/docs/releases.html
 kotlin = "2.2.21"
+
+# Android 核心库版本
+# AndroidX Core KTX: https://developer.android.com/jetpack/androidx/releases/core
 coreKtx = "1.17.0"
-junit = "4.13.2"
-junitVersion = "1.3.0"
-espressoCore = "3.7.0"
-lifecycleRuntimeKtx = "2.10.0"
+# AndroidX Activity Compose: https://developer.android.com/jetpack/androidx/releases/activity
 activityCompose = "1.12.0"
+# AndroidX Lifecycle Runtime KTX: https://developer.android.com/jetpack/androidx/releases/lifecycle
+lifecycleRuntimeKtx = "2.10.0"
+
+# 测试框架版本
+# JUnit 4 测试框架: https://junit.org/junit4/
+junit = "4.13.2"
+# AndroidX JUnit 扩展: https://developer.android.com/jetpack/androidx/releases/test#test-ext-junit
+junitVersion = "1.3.0"
+# AndroidX Espresso 测试框架: https://developer.android.com/training/testing/espresso
+espressoCore = "3.7.0"
+
+# Jetpack Compose 相关版本
+# Compose BOM: https://developer.android.com/jetpack/compose/bom
+# 说明: BOM 统一管理所有 Compose 库版本，确保兼容性
 composeBom = "2025.11.01"

+# 导航相关版本
+# Navigation Compose: https://developer.android.com/jetpack/androidx/releases/navigation
+navigationCompose = "2.9.6"
+
+# 序列化相关版本
+# Kotlinx Serialization JSON: https://github.com/Kotlin/kotlinx.serialization
+kotlinxSerializationJson = "1.9.0"
+
+# 网络请求相关版本
+# OkHttp HTTP 客户端: https://square.github.io/okhttp/
+okhttp = "5.3.2"
+# Retrofit HTTP 客户端: https://square.github.io/retrofit/
+retrofit = "3.0.0"
+# Retrofit Kotlinx Serialization 转换器: https://github.com/JakeWharton/retrofit2-kotlinx-serialization-converter
+retrofit2KotlinxSerializationConverter = "1.0.0"
+# OkHttp 日志拦截器: https://github.com/square/okhttp/tree/master/okhttp-logging-interceptor
+loggingInterceptor = "5.3.2"
+# Chucker 网络调试工具: https://github.com/ChuckerTeam/chucker
+# 说明: 通过 OkHttp 拦截器机制在应用通知栏显示网络请求功能
+chucker = "4.2.0"
+
+# 日志框架版本
+# Timber 日志库: https://github.com/JakeWharton/timber
+timber = "5.0.1"
+
+# 依赖注入相关版本
+# Hilt 依赖注入框架: https://developer.android.com/training/dependency-injection/hilt-android
+# GitHub: https://github.com/google/dagger
+# 说明: 基于 Dagger 的 Android 依赖注入库
+hilt = "2.57.2"
+# Hilt Navigation Compose: https://developer.android.com/jetpack/androidx/releases/hilt
+hiltNavigationCompose = "1.3.0"
+# KSP (Kotlin Symbol Processing): https://github.com/google/ksp
+# 说明: Kotlin 注解处理器，用于代码生成
+ksp = "2.3.2"
+
+# 启动页相关版本
+# AndroidX Core Splashscreen: https://developer.android.com/jetpack/androidx/releases/core
+# 说明: 提供启动画面 API，兼容 Android 12+ 的启动画面
+androidxCoreSplashscreen = "1.2.0"
+
+# 图片加载相关版本
+# Coil Compose 图片加载库: https://coil-kt.github.io/coil/compose/
+coilCompose = "2.7.0"
+
+# 调试工具相关版本
+# LeakCanary 内存泄漏检测工具: https://github.com/square/leakcanary
+# 说明: 仅在 debug 构建中使用，用于检测内存泄漏
+leakcanaryAndroid = "2.14"
+
+# 数据库相关版本
+# Room 数据库框架: https://developer.android.com/training/data-storage/room
+# 说明: SQLite 的抽象层，提供流畅的数据库访问
+room = "2.8.4"
+
 [libraries]
+# AndroidX 基础组件
 androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
-junit = { group = "junit", name = "junit", version.ref = "junit" }
-androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
-androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }
 androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycleRuntimeKtx" }
 androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
+
+# Jetpack Compose UI
 androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
 androidx-compose-ui = { group = "androidx.compose.ui", name = "ui" }
 androidx-compose-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
 androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
 androidx-compose-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
+androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
 androidx-compose-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
 androidx-compose-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
-androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
+
+# 测试框架
+junit = { group = "junit", name = "junit", version.ref = "junit" }
+androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
+androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }
+
+# 导航
+navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigationCompose" }
+
+# 序列化
+kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerializationJson" }
+
+# 网络请求
+okhttp = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" }
+retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
+logging-interceptor = { module = "com.squareup.okhttp3:logging-interceptor", version.ref = "loggingInterceptor" }
+retrofit2-kotlinx-serialization-converter = { module = "com.jakewharton.retrofit:retrofit2-kotlinx-serialization-converter", version.ref = "retrofit2KotlinxSerializationConverter" }
+
+# 日志
+timber = { module = "com.jakewharton.timber:timber", version.ref = "timber" }
+
+# 依赖注入
+ksp-gradlePlugin = { group = "com.google.devtools.ksp", name = "com.google.devtools.ksp.gradle.plugin", version.ref = "ksp" }
+hilt-android = { module = "com.google.dagger:hilt-android", version.ref = "hilt" }
+hilt-android-compiler = { module = "com.google.dagger:hilt-android-compiler", version.ref = "hilt" }
+hilt-android-testing = { module = "com.google.dagger:hilt-android-testing", version.ref = "hilt" }
+hilt-navigation-compose = { module = "androidx.hilt:hilt-navigation-compose", version.ref = "hiltNavigationCompose" }
+
+# 图片加载
+coil-compose = { module = "io.coil-kt:coil-compose", version.ref = "coilCompose" }
+
+# 启动页
+androidx-core-splashscreen = { group = "androidx.core", name = "core-splashscreen", version.ref = "androidxCoreSplashscreen" }
+
+# 调试工具
+leakcanary-android = { module = "com.squareup.leakcanary:leakcanary-android", version.ref = "leakcanaryAndroid" }
+chucker = { module = "com.github.chuckerteam.chucker:library", version.ref = "chucker" }
+chucker-no-op = { module = "com.github.chuckerteam.chucker:library-no-op", version.ref = "chucker" }
+
+# 数据库
+androidx-room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
+androidx-room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }
+androidx-room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" }
+androidx-room-testing = { group = "androidx.room", name = "room-testing", version.ref = "room" }
+androidx-room-paging = { group = "androidx.room", name = "room-paging", version.ref = "room" }

 [plugins]
 android-application = { id = "com.android.application", version.ref = "agp" }
 kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
 kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

+# 序列化相关插件
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+
+# 依赖注入相关插件
+hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
+ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
--- a/settings.gradle.kts
+++ b/settings.gradle.kts
@@ -1,3 +1,5 @@
+@file:Suppress("UnstableApiUsage")
+
 pluginManagement {
    repositories {
        google {