android-kotlin-compose

Android Kotlin Compose 开发

遵循 Google 官方架构指南和最佳实践，创建可用于生产环境的 Android 应用。 适用于使用 Kotlin、Jetpack Compose、MVVM 架构、Hilt 依赖注入、Room 数据库或 Android 多模块项目构建 Android 应用。 当用户请求创建 Android 项目、界面、ViewModel、仓库、功能模块，或询问 Android 架构模式时触发。

快速参考

任务	参考文件
项目结构与模块	modularization.md
架构层（Presentation、Domain、Data、UI）	architecture.md
Compose 模式、动画、效果、修饰符	compose-patterns.md
无障碍功能与 TalkBack 支持	android-accessibility.md
通知与前台服务	android-notifications.md
数据同步与离线优先模式	android-data-sync.md
Material 3 主题与动态颜色	android-theming.md
Navigation3 与自适应导航	android-navigation.md
Kotlin 最佳实践	kotlin-patterns.md
协程最佳实践	coroutines-patterns.md
Gradle 与构建配置	gradle-setup.md
测试方法	testing.md
国际化与本地化	android-i18n.md
图标、图形与自定义绘制	android-graphics.md
运行时权限	android-permissions.md
Kotlin 委托模式	kotlin-delegation.md
崩溃报告	crashlytics.md
StrictMode 防护措施	android-strictmode.md
多模块依赖	dependencies.md
代码质量（Detekt）	code-quality.md
代码覆盖率（JaCoCo）	android-code-coverage.md
安全（加密、生物识别、证书固定）	android-security.md
设计模式	design-patterns.md
Android 性能、重组与应用启动	android-performance.md
调试（Logcat、ANR、R8、内存泄漏）	android-debugging.md
迁移指南（XML、RxJava、Navigation、Compose）	migration.md

工作流决策树

正在创建新项目？ → 使用 assets/settings.gradle.kts.template 设置项目并包含模块
→ 使用 assets/libs.versions.toml.template 设置版本目录
→ 将 assets/convention/ 中的所有文件复制到 build-logic/convention/src/main/kotlin/
→ 创建 build-logic/settings.gradle.kts（参见 assets/convention/QUICK_REFERENCE.md）
→ 在根目录的 settings.gradle.kts 中添加 includeBuild("build-logic")
→ 将插件条目添加到 gradle/libs.versions.toml（参见 assets/convention/QUICK_REFERENCE.md） → 将 assets/proguard-rules.pro.template 复制到 app/proguard-rules.pro → 阅读 modularization.md，了解结构和模块类型
→ 使用 gradle-setup.md 设置构建文件和构建逻辑

正在配置 Gradle/构建文件？ → 使用 gradle-setup.md 了解模块 build.gradle.kts 的模式
→ 使用 gradle-setup.md → “构建性能”，了解优化工作流、诊断和瓶颈排查
→ 将 assets/convention/ 中的约定插件复制到项目的 build-logic/
→ 参见 assets/convention/QUICK_REFERENCE.md，了解设置说明和示例
→ 将 assets/proguard-rules.pro.template 复制到 app/proguard-rules.pro，以配置 R8 规则

正在设置代码质量 / Detekt？ → 使用 code-quality.md 设置 Detekt 约定插件
→ 从 assets/detekt.yml.template 开始配置规则，并启用 Compose 规则

正在添加或更新依赖项？ → 按照 dependencies.md 操作
→ 如果缺少该依赖项，请更新 assets/libs.versions.toml.template

正在添加新功能/模块？ → 按照 modularization.md 中的模块命名规范
→ 在功能模块中实现 Presentation
→ 遵循依赖流向：Feature → Core/Domain → Core/Data

正在构建 UI 屏幕/组件？ → 阅读 compose-patterns.md，了解屏幕架构、状态、组件和修饰符
→ 使用 android-theming.md 配置 Material 3 颜色、排版和形状
→ 始终使 Kotlin 代码符合 kotlin-patterns.md
→ 在功能模块中创建 Screen + ViewModel + UiState
→ 尽可能使用 core/ui 中的共享组件

正在设置应用主题（颜色、排版、形状）？ → 按照 android-theming.md 设置 Material 3 主题和动态颜色
→ 使用 MaterialTheme.colorScheme 中的语义颜色角色（切勿硬编码颜色）
→ 支持浅色/深色主题，并提供用户偏好切换开关
→ 为 API 31+ 启用动态颜色（Material You）

正在编写 Kotlin 代码？ → 始终遵循 kotlin-patterns.md
→ 确保实践符合 architecture.md、modularization.md 和 compose-patterns.md

正在设置数据层/领域层？ → 阅读 architecture.md
→ 在 core/domain 中创建 Repository 接口 → 在 core/data 中实现 Repository → 在 core/data 中创建 DataSource + DAO

正在实现离线优先或数据同步？ → 按照 android-data-sync.md 了解同步策略、冲突解决和缓存失效
→ 使用 Room 作为唯一事实来源，并保存同步元数据（syncStatus、lastModified）
→ 使用 WorkManager 安排后台同步
→ 同步前检查网络状态
正在设置导航？ → 按照 android-navigation.md 了解 Navigation3 架构、状态管理和自适应导航
→ 查看 modularization.md，了解功能模块导航组件（Destination、Navigator、Graph）
→ 在 app 模块中配置导航图
→ 使用功能导航目标和 Navigator 接口

正在添加测试？ → 使用 testing.md 中的模式和示例
→ 使用 testing.md →“截图测试”了解 Compose Preview 截图测试的设置方法
→ 将测试替身放在 core/testing 中

正在处理运行时权限？ → 按照 android-permissions.md 了解清单声明和 Compose 权限模式
→ 在合适的场景请求权限，并处理“不要再询问”流程

正在显示通知或前台服务？ → 使用 android-notifications.md 了解通知渠道、样式、操作和前台服务
→ 在显示通知前，检查 API 33+ 上的 POST_NOTIFICATIONS 权限
→ 在应用启动时创建通知渠道（API 26+ 必需）

正在多个 ViewModel 之间共享逻辑，或避免使用基类？ → 按照 kotlin-delegation.md 中的说明，通过接口使用委托
→ 优先使用小型、注入式委托来处理验证、分析或功能标志

正在添加崩溃报告／监控？ → 按照 crashlytics.md 了解与提供方无关的接口和模块放置方式
→ 使用 DI 绑定，在 Firebase Crashlytics 和 Sentry 之间切换

正在启用 StrictMode 防护？ → 按照 android-strictmode.md 了解应用级设置和 Compose 编译器诊断
→ 使用 crashlytics.md 中的 Sentry/Firebase 初始化来上报 StrictMode 日志

正在为新功能、业务逻辑或系统选择设计模式？ → 使用 design-patterns.md 获取面向 Android 的模式指导
→ 遵循 architecture.md 和 modularization.md

正在衡量性能回退或启动／卡顿情况？ → 使用 android-performance.md 了解 Macrobenchmark、Baseline Profiles 和 ProfileInstaller 的设置方法
→ 使基准测试模块与 gradle-setup.md 中的 benchmark 构建类型保持一致
→ 如果用户明确要求调查卡顿或添加自定义跟踪点，请使用 android-performance.md 了解 System Tracing（androidx.tracing）的设置方法

正在设置应用初始化或启动画面？ → 按照 android-performance.md →“应用启动与初始化”了解 App Startup 库、延迟初始化和启动画面
→ 避免基于 ContentProvider 的自动初始化，改用 Initializer 接口
→ 使用 installSplashScreen() 和 setKeepOnScreenCondition 处理加载状态

正在添加图标、图像或自定义图形？ → 使用 android-graphics.md 了解 Material Symbols 图标和自定义绘图
→ 通过 Iconify API 或 Google Fonts 下载图标（避免使用已弃用的 Icons.Default.* 库）
→ 使用 Modifier.drawWithContent、drawBehind 或 drawWithCache 绘制自定义图形

正在创建自定义 UI 效果（发光、阴影、渐变）？ → 查看 android-graphics.md，了解 Canvas 绘图、BlendMode 和 Palette API 模式
→ 使用 rememberInfiniteTransition 创建动画效果
如何确保符合无障碍要求（TalkBack、触控目标、颜色对比度）？ → 遵循 android-accessibility.md 中的语义属性和 WCAG 指南
→ 为所有图标和图片提供 contentDescription
→ 确保触控目标至少为 48dp × 48dp
→ 使用 TalkBack 和 Accessibility Scanner 进行测试

如何处理图片和颜色提取？ → 使用 android-graphics.md → “Image Loading with Coil3”，了解 AsyncImage、SubcomposeAsyncImage、rememberAsyncImagePainter 和 Hilt ImageLoader 设置
→ 使用 android-graphics.md 了解 Palette API 和颜色提取

如何实现复杂的协程流或后台工作？ → 遵循 coroutines-patterns.md 中的结构化并发模式
→ 使用合适的调度器（IO、Default、Main），并妥善处理取消
→ 状态管理优先使用 StateFlow/SharedFlow，而不是通道
→ 使用 callbackFlow 将 Android 回调 API（网络连接、传感器、位置）封装为 Flow
→ 使用 suspendCancellableCoroutine 处理一次性回调（Play Services 任务、生物识别）
→ 在 ViewModel 中使用 combine() 合并多个 Flow，使用 shareIn 共享开销较大的上游流
→ 使用 buffer、conflate、debounce 或 sample 处理背压

如何在多个类之间共享行为？ → 使用 kotlin-delegation.md 中的接口委托模式
→ 避免使用基类；优先采用由委托接口组成的组合方式
→ 示例：Analytics、FormValidator、CrashReporter

如何重构现有代码或改进架构？ → 查看 architecture.md，了解各层职责
→ 查看 design-patterns.md，选择适用的模式
→ 遵循 kotlin-patterns.md，改进 Kotlin 特定代码
→ 确保符合 modularization.md 中的依赖规则

如何调试崩溃、ANR 或混淆后的堆栈跟踪？ → 遵循 android-debugging.md，了解 Logcat、ANR 跟踪和 Compose 重组调试
→ 使用 android-debugging.md 处理 R8 映射文件并进行手动反混淆
→ 查看 gradle-setup.md，了解 R8 构建配置和 keep 规则

如何调试性能问题或内存泄漏？ → 在开发构建中启用 android-strictmode.md
→ 使用 android-performance.md 进行性能分析和基准测试
→ 使用 android-debugging.md 分析 LeakCanary 和堆转储
→ 查看 coroutines-patterns.md 中的协程取消模式

如何设置 CI/CD 或代码质量检查？ → 使用 code-quality.md 配置 Detekt 基线并集成 CI
→ 使用 gradle-setup.md 配置构建缓存和约定插件
→ 使用 testing.md 了解测试组织和覆盖率

如何处理敏感数据或隐私问题？ → 遵循 crashlytics.md 中的数据清理模式
→ 使用 android-permissions.md，确保正确说明权限用途
→ 查看 android-strictmode.md，了解如何检测明文网络流量

如何迁移旧代码（LiveData、Fragments、Accompanist、RxJava）？ → 使用 migration.md 了解所有迁移路径
→ 遵循 architecture.md 中的现代 MVVM 模式
添加 Compose 动画？ → 使用 compose-patterns.md → “动画”，了解 AnimatedVisibility、AnimatedContent、animate*AsState、Animatable 和共享元素
→ 使用 graphicsLayer 实现 GPU 加速变换（不会触发重组）
→ 始终提供 label 参数，以便使用 Layout Inspector 调试

使用副作用（LaunchedEffect、DisposableEffect）？ → 使用 compose-patterns.md → “副作用”，查看效果选择指南
→ 使用 LaunchedEffect(key) 处理由状态驱动的协程，使用 rememberCoroutineScope 处理由事件驱动的协程
→ 使用 DisposableEffect 清理监听器和资源，并始终包含 onDispose
→ 使用 LifecycleResumeEffect 处理 onResume/onPause 阶段的工作（相机、媒体），使用 LifecycleStartEffect 处理 onStart/onStop 阶段的工作（位置、传感器）

处理 Modifier 顺序或自定义 Modifier？ → 使用 compose-patterns.md → “Modifier”，了解链式顺序规则和模式
→ 使用 Modifier.Node 创建自定义 Modifier（不要使用已弃用的 Modifier.composed）
→ 顺序：尺寸 → 内边距 → 绘制 → 交互

从 Accompanist 或已弃用的 Compose API 迁移？ → 使用 migration.md，了解 Accompanist、Compose API、Material 和 Edge-to-Edge 迁移
→ 查看 compose-patterns.md → “已弃用的模式和迁移”，获取摘要列表

优化 Compose 重组或稳定性？ → 使用 compose-patterns.md 了解 @Immutable/@Stable 注解
→ 使用 android-performance.md → “Compose 重组性能”，了解三个阶段、延迟状态读取和 Strong Skipping Mode
→ 查看 gradle-setup.md，了解 Compose Compiler 指标和稳定性报告
→ 使用 kotlin-patterns.md 了解不可变数据结构

使用数据库（Room）？ → 按照 modularization.md 的说明，在 core/database 中定义 DAO 和实体
→ 使用 testing.md 了解内存数据库测试和迁移测试
→ 按照 architecture.md 中的 Room 仓库模式进行开发

需要国际化/本地化（i18n/l10n）？ → 使用 android-i18n.md 了解字符串资源、复数形式和 RTL 支持
→ 按照 compose-patterns.md 的说明，创建支持 RTL 的 Compose 布局
→ 使用 testing.md 进行特定区域设置的测试

实现网络调用（Retrofit）？ → 使用 architecture.md → “网络层设置”，了解 Retrofit 服务接口、Hilt NetworkModule 和 AuthInterceptor
→ 按照 modularization.md 的说明，在 core/network 中定义 API 接口
→ 按照 dependencies.md 的说明配置 Retrofit、OkHttp 和序列化
→ 使用 kotlin-patterns.md 中的泛型 Result<T> 处理错误

创建自定义 lint 规则或代码检查？ → 使用 code-quality.md 创建 Detekt 自定义规则
→ 按照 gradle-setup.md 的说明设置约定插件
→ 查看 android-strictmode.md 了解运行时检查

需要代码覆盖率报告？ → 使用 android-code-coverage.md 配置 JaCoCo
→ 按照 testing.md 的说明制定测试策略
→ 查看 gradle-setup.md 了解约定插件集成 实现安全功能（加密、生物识别、固定）？ → 使用 android-security.md 查看全面的安全指南
→ 按照 android-permissions.md 处理运行时权限
→ 查看 crashlytics.md 了解 PII 清理和数据隐私