Android新项目配置相关

Gradle版本配置Version Catalog

libs.versions.toml

依赖集中管理文件，提高依赖管理的可维护性

# 版本定义
[versions]
agp = "8.7.2"
kotlin = "1.9.24"
coreKtx = "1.16.0"
junit = "4.13.2"
junitVersion = "1.2.1"
espressoCore = "3.6.1"
appcompat = "1.7.0"
material = "1.12.0"

# 依赖库分组
[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
material = { group = "com.google.android.material", name = "material", version.ref = "material" }

# 测试
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" }

# 插件定义
[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

# 依赖组
# [bundles]
# androidx = ["androidx-core-ktx", "androidx-appcompat", "androidx-material"]
# testing = ["test-junit", "androidx-test-ext", "androidx-espresso-core"]

settings.gradle.kts

• google()仓库使用content块限制仓库搜索范围，减少网络请求
• repositoriesMode配置为FAIL_ON_PROJECT_REPOS便于集中管理仓库配置，避免重复和冲突
  • 通过 FAIL_ON_PROJECT_REPOS 防止项目级仓库配置导致的问题

pluginManagement {
    repositories {
        // 先检查 Google 仓库，再检查其他仓库，提高查找效率
        google {
            // google()仓库包含 Android 开发所需的官方插件和库
            // 使用 content 块优化查找范围，限制仓库搜索范围，减少不必要的网络请求
            content {
                // 包含所有 Android 相关插件
                includeGroupByRegex("com\\.android.*")
                // 包含所有 Google 相关插件
                includeGroupByRegex("com\\.google.*")
                // 包含所有 AndroidX 库
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    // 配置仓库解析策略
    // FAIL_ON_PROJECT_REPOS 表示在项目级解析，build.gradle.kts 中定义了仓库无效
    // 这是为了强制所有仓库配置集中在 settings.gradle.kts 中，避免冲突
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "250620"
include(":app")

项目build.gradle.kts

• 顶层构建文件，配置所有子项目/模块共享的构建属性

// 顶层构建文件，配置所有子项目/模块共享的构建属性
plugins {
    // 不再需要显式指定版本，从 libs.versions.toml 获取
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
}

模块build.gradle.kts

• 模块级配置

plugins {
    // 使用插件别名，不再需要指定版本
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
}

android {
    namespace = "com.dcxing"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.dcxing"
        minSdk = 24
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            isMinifyEnabled = false
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
        }
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = "11"
    }
}

dependencies {
    // 使用依赖别名，不再需要指定版本
    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.appcompat)
    implementation(libs.material)
    testImplementation(libs.junit)
    androidTestImplementation(libs.androidx.junit)
    androidTestImplementation(libs.androidx.espresso.core)
}

xml文件相关配置

数据备份

android:dataExtractionRules 和 android:fullBackupContent

• Android 系统中两个重要的备份相关配置，它们分别控制不同场景下的数据处理方式。
• 当两个配置同时存在时
  • 备份操作优先使用 fullBackupContent
  • 数据迁移操作优先使用 dataExtractionRules

// AndroidManifest.xml
<application
    android:allowBackup="true"  <!-- 是否允许备份 -->
    android:dataExtractionRules="@xml/data_extraction_rules"
    android:fullBackupOnly="true"  <!-- 是否仅使用完全备份 -->
    android:fullBackupContent="@xml/backup_rules">
    <!-- ... -->
</application>

android:dataExtractionRules="@xml/data_extraction_rules"

• Android 13 (API 33)引入
• 主要用于控制设备间迁移或数据共享时的数据提取
• 配置文件@xml/data_extraction_rules
• 数据范围通常更大，可包含用户生成内容
• 目标场景：1. 用户更换设备、2. 工作资料迁移、3. 数据共享
• 支持多种场景的规则 (cloud-backup、device-transfer、work-profile)

data_extraction_rules.xml

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        <!-- TODO: Use <include> and <exclude> to control what is backed up.
        <include .../>
        <exclude .../>
        -->
    </cloud-backup>
    <!--
    <device-transfer>
        <include .../>
        <exclude .../>
    </device-transfer>
    -->
</data-extraction-rules>

android:fullBackupContent="@xml/backup_rules"

• Android 6.0 (API 23)引入
• 主要用于控制应用数据的备份和恢复
• 配置文件@xml/backup_rules
• 数据范围受限于备份大小限制 (5-25MB)
• 目标场景：1. 设备重置、2. 应用卸载重装、3. 云备份
• 单一的备份规则配置

backup_rules.xml

• 是AndroidManifest.xml中的一个重要属性，用于配置应用数据的备份和恢复策略。这对于用户数据保护和应用迁移非常重要。使用android:fullBackupContent="@xml/backup_rules"配置
• 备份触发条件
  • 当用户恢复出厂设置后重新设置设备时
  • 当用户更换设备并设置新设备时
  • 当用户卸载并重新安装应用时
• 属性说明
  • domain 属性
    • sharedpref：应用的共享偏好设置，存储在 data/data//shared_prefs/ 目录下的文件
    • database：应用的 SQLite 数据库，存储在 data/data//databases/ 目录下的 SQLite 数据库文件
    • files：应用内部存储的文件，存储在 data/data//files/ 目录下的文件
    • external：应用外部存储的文件，路径通常为 /sdcard/Android/data//files/
    • root：应用根目录下的文件，谨慎使用，可能包含敏感数据
  • path 属性
    • .：表示整个域
    • 具体路径：如 app_database.db、important_data/
  • include 和 exclude 标签
    • include：指定要备份的内容
    • exclude：指定要排除的内容
• 注意事项
  • 数据大小限制
    • 自动备份限制为 5MB
    • 完全备份限制为 25MB
  • 敏感数据
    • 不要备份包含敏感信息的文件
    • 使用 exclude 标签排除敏感数据

// backup_rules.xml
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <!-- 包含指定的文件路径 -->
    <include domain="sharedpref" path="." />
    <include domain="database" path="app_database.db" />
    
    <!-- 排除不需要备份的文件 -->
    <exclude domain="files" path="temp/" />
    <exclude domain="external" path="cache/" />
    
    <!-- 备份特定目录中的所有文件 -->
    <include domain="files" path="important_data/" />
    
    <!-- 备份外部存储中的特定文件 -->
    <include domain="external" path="documents/important.pdf" />
</full-backup-content>

// 测试备份功能
# 触发备份
adb shell bmgr backupnow <package_name>

# 触发恢复
adb shell bmgr restore <package_name>

# 测试设备迁移
adb shell bmgr transport com.google.android.gms/.backup.BackupTransportService

网络安全配置android:networkSecurityConfig

android:networkSecurityConfig="@xml/network_security_config"是 Android 6.0 (API 级别 23) 引入的一项重要安全功能，用于控制应用如何验证网络连接和处理加密数据。这对于保护用户隐私和防止网络攻击非常重要。

• 网络安全配置允许

  • 自定义应用如何验证服务器证书
  • 配置应用是否允许明文 HTTP 流量
  • 指定自定义的证书颁发机构 (CA)
  • 启用证书锁定 (Certificate Pinning)
  • 配置网络流量的 DNS 解析方式

• 属性介绍

  • cleartextTrafficPermitted：是否允许明文 HTTP 流量
  • usesCleartextTraffic：在 AndroidManifest.xml 中设置的属性，覆盖配置文件中的设置

<network-security-config>
    <!-- 应用的默认安全配置 -->
    <base-config cleartextTrafficPermitted="true">
        <!-- 定义应用信任的证书颁发机构 -->
        <trust-anchors>
            <!-- 信任系统默认的 CA 证书 -->
            <certificates src="system" overridePins="true"/>
            <!-- 信任用户安装的 CA 证书 -->
            <certificates src="user" overridepins="true" />
            <!-- 信任应用内置的 CA 证书 -->
            <certificates src="@raw/my_ca" overridepins="true" />
        </trust-anchors>
    </base-config>

    <!-- 禁止所有明文流量 -->
    <!-- <base-config cleartextTrafficPermitted="false" /> -->

    <!-- 针对特定域的安全配置：允许特定域名的明文流量 -->
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">localhost</domain>
        <domain includeSubdomains="true">127.0.0.1</domain> <!-- 你的本地IP -->

        <!-- 仅信任特定域的自定义 CA -->
        <!--
        <domain includeSubdomains="true">internal.example.com</domain>
        <trust-anchors>
            <certificates src="@raw/internal_ca" />  <!-- 内部网络的 CA -->
        </trust-anchors>
        -->

        <!-- 证书锁定：只信任指定的证书。会限制应用只能连接到指定的证书，如果证书过期或被替换，应用可能无法连接到服务器 -->
        <pin-set expiration="2025-01-01">
            <!-- 建议设置合理的过期时间和备用证书 -->
            <!-- 主证书 -->
            <pin digest="SHA-256">7HXxx...=</pin>
            <!-- 备用证书 -->
            <pin digest="SHA-256">fwXxx...=</pin>
        </pin-set>
    </domain-config>

    <!-- 仅在调试模式下生效的配置：开发环境配置 -->
    <debug-overrides>
        <!-- 开发环境允许使用用户添加的 CA 证书 -->
        <trust-anchors>
            <certificates src="system" />
            <certificates src="user" />
            <certificates src="@raw/my_ca" />
        </trust-anchors>
    </debug-overrides>
</network-security-config>

// 网络安全配置测试
# 检查网络安全配置是否有效
adb shell dumpsys package <package_name> | grep -A 20 networkSecurityConfig

# 捕获网络流量（需要 root 权限）
adb shell tcpdump -i any -s 0 -w /sdcard/capture.pcap