Android 原生应用开发与 Material…

在开发 Android 原生应用（Kotlin + Jetpack Compose + Material Design 3）时，用于项目初始化配置、代码规范、UI 设计合规、构建排错与分层测试。

适用场景

解决思路

1. 开发前先评估项目状态：空目录需完整初始化（含 Gradle Wrapper）；已有 gradlew 和 gradle/wrapper/ 则直接用 ./gradlew 构建；Android Studio 项目检查 wrapper，缺失时运行 gradle wrapper；不完整项目补齐缺失文件与配置。
2. 写业务逻辑前先确保 ./gradlew assembleDebug 成功；若缺少 gradle.properties 先创建并配置 AndroidX。
3. 按清单准备必需文件：gradle.properties、settings.gradle.kts、根 build.gradle.kts、gradle/wrapper/gradle-wrapper.properties、app/build.gradle.kts、AndroidManifest.xml、MainActivity.kt、res/values 下的 strings.xml/colors.xml/themes.xml 以及 mipmap-* 图标。
4. 在 gradle.properties 中配置 android.useAndroidX=true、android.enableJetifier=true、org.gradle.parallel=true、kotlin.code.style=official，并按项目规模设置 org.gradle.jvmargs 的 -Xmx（小项目 2048m、中型 4096m、大型 8192m+）；遇 OutOfMemoryError 时增大 -Xmx。
5. 依赖声明使用 BOM 管理 Compose 版本（如 platform("androidx.compose:compose-bom:2024.02.00")），并显式引入 ui、material3、activity-compose、lifecycle-viewmodel-compose。
6. 用 Product Flavors 创建不同版本：定义 flavorDimensions，创建 dev/staging/prod 等 flavor，配置 applicationIdSuffix、versionNameSuffix、buildConfigField、resValue；buildTypes 中区分 debug（isDebuggable=true、isMinifyEnabled=false）与 release（isDebuggable=false、isMinifyEnabled=true、配置 proguardFiles）。
7. 构建变体命名为 {flavor}{BuildType}（如 devDebug、prodRelease）；用 ./gradlew tasks --group="build" 列出变体，用 assembleDevDebug / assembleProdRelease / assembleDebug / assembleRelease 构建，用 installDevDebug 安装，用 ./gradlew installDevDebug && adb shell am start -n 包名/.MainActivity 构建并启动。
8. AGP 8.0 起 BuildConfig 默认不生成，需在 build.gradle.kts 中设置 buildFeatures { buildConfig = true }；代码中通过 BuildConfig.API_BASE_URL、BuildConfig.ENABLE_LOGGING、BuildConfig.DEBUG 访问。
9. 按 flavor 组织源码集：app/src/main 共享、app/src/dev、app/src/staging、app/src/prod 存放各 flavor 专属代码与资源，app/src/debug、app/src/release 存放构建类型专属代码。
10. 支持多 flavor 维度（如 environment + tier），结果形如 devFreeDebug、prodPaidRelease。
11. 遵循 Kotlin 命名规范：类/接口 PascalCase、函数/变量 camelCase、常量 SCREAMING_SNAKE、包名小写、Composable 用 PascalCase。
12. 避免非空断言 !!，改用安全调用加默认值（user?.name ?: "Unknown"）或 let 处理。
13. 异常处理：不要在业务层随意 try-catch 吞掉异常；用 Result 包装返回让调用方决定，或在 ViewModel 中用 runCatching 统一处理并更新 UiState。
14. 线程选择：UI 更新用 Dispatchers.Main，网络请求与文件 I/O 用 Dispatchers.IO，计算密集用 Dispatchers.Default；在 ViewModel 中用 viewModelScope.launch 配合 withContext(Dispatchers.IO) 切换线程，Repository 的 suspend 函数应主线程安全。
15. 避免在 IO 线程更新 UI、避免在主线程执行耗时操作（ANR）。
16. 显式声明可见性：默认 public，类内私有用 private，模块内用 internal。
17. 避免访问未初始化的 lateinit，改用可空类型加默认值；lambda 中避免用 return 返回外层函数，改用 return@forEach。
18. 服务端响应数据类字段必须全部声明为可空（如 val id: String? = null）并用 @SerializedName 映射。
19. 生命周期资源成对管理：addObserver 必须在 onDetachedFromWindow 等对应位置 removeObserver，避免内存泄漏。
20. 日志分级使用：Log.i 记录正常流程关键检查点，Log.w 记录可恢复异常/回退/空返回，Log.e 记录请求失败/捕获异常/不可恢复错误。
21. Composable 规则：非 Composable 函数不能调用 Composable；suspend 调用需放在 LaunchedEffect 中；不要在 Composable 内直接创建 ViewModel，使用 viewModel() 或 remember。
22. 状态管理：用 remember { mutableStateOf(...) } 保存基本状态，用 derivedStateOf 派生状态避免冗余计算，用 rememberScrollState 等持久化跨重组状态，ViewModel 中用 MutableStateFlow + asStateFlow 暴露状态。
23. 提供多分辨率应用图标：mipmap-mdpi 48x48、hdpi 72x72、xhdpi 96x96、xxhdpi 144x144、xxxhdpi 192x192；推荐使用 Adaptive Icon（mipmap-anydpi-v26/ic_launcher.xml 配置 background 与 foreground）。
24. 资源命名规范：布局用 layout_ 前缀，图片用 ic_/img_/bg_ 前缀，颜色用 color_ 前缀，字符串用 app_name、btn_submit 等描述性名称。
25. 避免使用 Android 保留名：颜色避免 background/foreground/transparent/white/black，图标避免 icon/logo/image/drawable，视图避免 view/text/button/layout/container，属性避免 id/name/type/style/theme/color，系统避免 app/android/content/data/action；改用带前缀的名称如 app_background、icon_primary、ic_home。
26. 构建错误排查：先读完整错误信息定位文件与行号，检查最近改动，执行 ./gradlew clean assembleDebug，检查依赖版本冲突，必要时刷新依赖。
27. 常用调试命令：./gradlew clean assembleDebug、./gradlew :app:dependencies、./gradlew assembleDebug --stacktrace、./gradlew --refresh-dependencies。
28. 按应用类别选择视觉风格：工具类极简、金融类专业可信、健康类柔和自然、幼儿（3-5）明亮大目标（56dp+）、儿童（6-12）活泼游戏化、社交娱乐表现力强、生产力简洁高对比、电商突出转化。
29. 遵循 M3 关键规格：正文对比度至少 4.5:1、大文本（18sp+）3:1、UI 组件 3:1；触控目标最小 48x48dp、主要操作推荐 56x56dp、儿童应用 56dp+、目标间距至少 8dp。
30. 使用 8dp 网格：xs 4dp、sm 8dp、md 16dp、lg 24dp、xl 32dp、xxl 48dp。
31. 遵循排版比例：Display 57/45/36sp，Headline 32/28/24sp，Title 22/16/14sp，Body 16/14/12sp，Label 14/12/11sp。
32. 动画时长：微交互（涟漪）50-100ms，短动画 100-200ms，中动画（展开/收起）200-300ms，长动画（复杂）300-500ms。
33. 组件尺寸：Button 高 40dp 最小宽 64dp，FAB 56x56dp，Text Field 高 56dp 最小宽 280dp，App Bar 高 64dp，Bottom Nav 高 80dp。
34. 避免 UI 反模式：底部导航不超过 5 项、同屏不超过一个 FAB、触控目标不小于 48dp、间距为 8dp 倍数、支持深色主题、彩色背景文字需检查对比度。
35. 避免性能反模式：启动超过 2 秒需显示进度、帧率不低于 60 FPS（每帧不超过 16ms）、崩溃率不超过 1.09%、ANR 率不超过 0.47%。
36. 避免无障碍反模式：交互元素必须有 contentDescription、标签不要包含元素类型（用 "Save" 而非 "Save button"）、儿童应用避免复杂手势、非阅读者避免纯文字按钮。
37. 按评审清单检查：8dp 间距合规、48dp 最小触控目标、排版比例正确、文字对比度 4.5:1+、支持深色主题、所有交互元素有 contentDescription、启动 2 秒内或显示进度、视觉风格匹配应用类别。
38. 仅在用户明确要求测试时添加测试依赖；先检查 gradle/libs.versions.toml 与现有 build.gradle.kts 中已固定的版本，按版本对齐规则匹配：kotlinx-coroutines-test 对齐 coroutines-core，compose-ui-test-junit4 对齐 Compose BOM，espresso-* 各构件版本一致，androidx.test 使用兼容版本，mockk 支持项目 Kotlin 版本。
39. 按需添加测试依赖：本地单元测试用 junit、robolectric、mockk、kotlinx-coroutines-test、androidx.arch.core:core-testing、turbine；仪器测试用 androidx.test.ext:junit、runner、rules、espresso-core/contrib/intents/idling-resource、uiautomator；Compose UI 测试用 ui-test-junit4 与 debugImplementation 的 ui-test-manifest（使用 BOM 时无需显式版本）。
40. 在 android 块中启用 testOptions { unitTests.isIncludeAndroidResources = true } 以支持 Robolectric 资源。
41. 按层选择测试方式：单元测试（src/test/，JVM，毫秒级）测 ViewModel/仓库/映射/校验；Robolectric（src/test/，JVM+模拟 Android，约 100ms）测需要 Context/资源/SharedPrefs 的代码；本地 Compose UI 测试（src/test/，JVM+Robolectric）测 Composable 渲染与交互；Espresso（src/androidTest/，设备/模拟器）测 View 流程/Intent/数据库集成；设备 Compose UI 测试测完整 Compose 流程；UI Automator 测系统对话框/通知/多应用；Gradle Managed Device 用于 CI 与跨 API 矩阵测试。
42. 测试命令：./gradlew test 或 :app:testDebugUnitTest 跑本地单元测试，--tests "包名.类名" 跑单个测试类，connectedDebugAndroidTest 在连接设备上跑仪器测试，pixel6Api34DebugAndroidTest 在托管设备上跑，test connectedDebugAndroidTest 同时跑，testDebugUnitTest jacocoTestReport 生成覆盖率报告。

适用边界 · 注意事项

• 不适用于非 Android 原生开发（如 iOS、Flutter、React Native 跨平台项目）。
• 不适用于不使用 Kotlin/Jetpack Compose 的 Android 项目（如纯 Java + View 体系需自行调整）。
• 测试部分仅在用户明确要求测试时才添加测试依赖，否则不要主动引入。