Android Host — Lab 索引

统一 Android 承载工程，所有 Android 平台专项 labs 在此运行。

版本与复现信息

当前已验证版本

项目	版本 / 值
JDK	17
Gradle	8.14
Android Gradle Plugin	8.11.1
Kotlin Android Plugin	2.2.20
compileSdk	36
targetSdk	36
minSdk	24

其他设备复现建议

1. 安装 JDK 17（java -version 显示 17.x）
2. 安装 Android SDK，对齐 compileSdk 36
3. 配置 SDK 路径（二选一）：
   • 环境变量：ANDROID_HOME 或 ANDROID_SDK_ROOT
   • 或复制 local.properties.example → local.properties，填写 sdk.dir
4. 连接真机或启动模拟器（adb devices 可见）

前置条件

• JDK 17（Android Gradle Plugin 8.x 需要）
• Android SDK 已安装且路径可被 Gradle 解析（见上）
• 首次运行需网络下载 Gradle / Android 依赖

运行

cd labs/android/host
chmod +x gradlew

# 验证 Gradle 与依赖（可选）
./gradlew tasks

# 编译 Debug APK
./gradlew assembleDebug

# 安装到已连接设备/模拟器并在桌面打开「Android Host」
./gradlew installDebug

若 JAVA_HOME 未指向 JDK 17，可先设置（路径按本机调整）：

export JAVA_HOME=$(/usr/libexec/java_home -v 17)   # macOS
# 或 export JAVA_HOME=/path/to/jdk-17

常见失败原因：

现象	处理
SDK location not found	配置 ANDROID_HOME 或 local.properties 中的 sdk.dir
JAVA_HOME is set to an invalid directory	不要照抄他人路径；用 java -version 确认 JDK 17，再设 JAVA_HOME
installDebug 失败 / 无设备	先 adb devices，确保模拟器或真机已连接并授权

各 Lab 的入口在应用主界面；安装后打开 Android Host，按按钮进入对应生命周期实验。

当前目标

当前先提供单一 app 模块的最小骨架，后续逐步承载：

• Activity / Fragment / ViewModel / SavedStateHandle
• Compose / StateFlow / SharedFlow
• WorkManager / Foreground Service / AlarmManager
• Room / DataStore / 冷启动 / 前后台限制 / ANR
• Flutter bridge 的 Android 实现侧
• XML / Java 经典视图体系复习样例

目录结构

labs/android/host/
├── README.md
├── settings.gradle.kts
├── build.gradle.kts
├── gradle.properties
├── local.properties.example   ← 复制为 local.properties（不入库）
├── gradle/
│   └── wrapper/
├── gradlew
├── gradlew.bat
├── topics/
│   ├── memory-lifecycle/
│   ├── background-tasks/
│   └── state-routing-architecture/
└── app/
    ├── build.gradle.kts
    └── src/main/
        ├── AndroidManifest.xml
        ├── java/.../MainActivity.kt
        └── res/

设计原则

1. 先单 app，后模块化：先保证工程可运行、目录清晰、docs 可直链。
2. Compose + Kotlin 为主线：后续新增 Android 主题时，优先补 Compose / Kotlin 版本。
3. 保留 XML + Java 复习样例：
   • 经典生命周期、View 系统、旧架构可放 XML / Java
   • 允许同一主题并列放 Compose 版、XML 版、Java 版作对照
4. 源码与 README 分离但近邻：
   • 源码放 app/src/main/java/.../topics/<domain>/<lab-name>/...
   • XML 放 app/src/main/res/layout/...
   • Lab README 放 topics/<domain>/<lab-name>/README.md
5. docs 直链具体文件：知识库文档必须同时链接到具体 README 与具体源码文件。
6. 逐步演进：只有当实验数量与共享构建逻辑明显增多时，再拆 feature/* / core/* / build-logic/。

对应文档

• Android 生命周期：docs/02-memory-lifecycle/02-android-lifecycle-overview.md
• Android 后台任务：docs/03-background-tasks/01-workmanager-foregroundservice-alarmmanager.md
• 状态管理与架构：docs/04-state-routing-architecture/01-compose-flutter-vue-state-management.md