android-development

平台说明

• 可选的辅助插件在某些环境中可能会有所帮助，但不得将其视为此技能的必需项。

Android 开发标准

致谢：由 Peter Bamuhigire 分享，techguypeter.com，+256 784 464178。

适用场景

• 面向 AI Agent 实现的 Android 开发标准。以 Kotlin 为先，使用 Jetpack Compose UI、MVVM + Clean Architecture、Hilt DI，并遵循全面的安全、测试和性能模式。适用于构建或审查 Android 应用……

产出证据

类别	产物	格式	示例
正确性	Android 功能测试计划	Markdown 文档，涵盖单元测试、插桩测试和 Compose 测试	docs/android/feature-tests-checkout.md
UX 质量	无障碍审计	Markdown 文档，涵盖 TalkBack、语义和对比度	docs/android/a11y-checkout.md

参考资料

• 阅读下面的核心工作流后，可使用 references/ 目录了解详细信息。
• 对于 Room、DataStore、迁移或离线同步，请加载保留的 Android 持久化工作流。
• 对于 Red-Green-Refactor、测试接缝和分层测试设计，请加载保留的 Android TDD 工作流。
• references/android-ai-ml.md：关于设备端 Android AI/ML、ML Kit、LiteRT、MediaPipe、AICore 和 Gemini Nano。
• references/android-biometric-login.md：关于 AndroidX Biometric 启动门槛和由 CryptoObject 支持的身份验证。
• references/android-pdf-export.md：关于原生 PdfDocument 导出和 Android 报告 PDF 生成。

加载顺序

1. 加载 world-class-engineering，了解通用生产环境门槛。
2. 当 Android 应用属于更大型后端或多模块系统的一部分时，加载 system-architecture-design。
3. 加载此技能，了解 Android 实现细节。
4. 对于每个面向用户的 Android 屏幕，尤其是高端、仪表板、引导、报告、表单或营收关键流程，加载 android-ui-ux-design。
5. 按需加载 vibe-security-skill 和特定功能技能。

面向 AI 辅助实现的生产级 Android 开发标准。以 Kotlin 为先，使用 Jetpack Compose，并遵循现代 Android 最佳实践。

核心技术栈： 100% Kotlin | Jetpack Compose（默认 UI 工具包）| MVVM + Clean Architecture | Hilt DI 最低 SDK： 29（Android 10）| 目标 SDK： 35（Android 15） 兼容性： 必须在最低 SDK（支持的最旧版本）和最新稳定版 Android 上都流畅运行 参考应用： Now in Android——Google 官方示例，展示了在生产级代码库中应用这些标准的方式

使用场景

• 构建新的 Android 应用或功能
• 审查 Android 代码的质量和标准合规性
• 通过 AI Agent 生成 Kotlin/Compose 代码
• 设置 Android 项目结构
• 实现安全、测试或性能模式
• 在 Android 客户端中集成 REST API

后端环境

Android 应用连接到部署在三个环境中的 PHP/MySQL 后端：

环境	基础 URL 格式	数据库	说明
开发	http://{LAN_IP}:{port}/DMS_web/api/	MySQL 8.4.7（Windows WAMP）	使用主机的 LAN IP，而非 localhost
预发布	https://staging.{domain}/api/	MySQL 8.x（Ubuntu VPS）	用于 QA 和测试
生产	https://{domain}/api/	MySQL 8.x（Debian VPS）	面向正式用户

使用构建变体（dev、staging、prod）配置基础 URL，确保应用针对每个构建变体连接到正确的后端。所有后端均使用 utf8mb4_unicode_ci 排序规则和 MySQL 8.x。

快速参考

主题	参考文件	涵盖内容
项目结构	references/project-structure.md	目录布局、模块组织
Kotlin 规范	references/kotlin-conventions.md	编码风格、Compose 模式
架构	references/architecture-patterns.md	MVVM、Clean Architecture 分层
依赖注入	references/dependency-injection.md	Hilt 模块、作用域、ViewModel 注入
安全	references/security.md	加密存储、生物识别、网络安全
UI 设计系统	references/ui-design-system.md	设计令牌、组件、Material 3
高级 Android UX	../android-ui-ux-design/SKILL.md	Material 3 精细化设计、移动端人体工学、高级功能门控
屏幕模式	references/screen-patterns.md	完整屏幕模板、状态处理
测试	references/testing.md	单元测试、UI 测试、插桩测试
构建配置	references/build-configuration.md	Gradle KTS、Android Studio 设置、依赖项、构建类型、构建速度调优
API 集成	references/api-integration.md	Retrofit、错误处理、仓库模式
分析与性能	references/analytics-performance.md	Firebase、监控、优化
AI Agent 指南	references/ai-agent-guidelines.md	提示词模板、质量检查清单

架构概览

Presentation Layer (Compose + ViewModels)
         |
    Domain Layer (Use Cases + Repository Interfaces)
         |
    Data Layer (Repository Impl + API + Room)

分层规则

1. 表示层仅依赖领域层
2. 领域层不依赖 Android（纯 Kotlin）
3. 数据层实现领域接口，处理 API/数据库

包结构

com.company.app/
  core/          # Shared: DI, models, repositories, utils
  data/          # Room DB, API services, data sources
  presentation/  # Screens, ViewModels, components, navigation
  theme/         # Design system tokens

关键规范摘要

Kotlin

• 100% 使用 Kotlin，新代码不使用 Java
• 异步操作使用协程 + Flow（绝不使用回调）
• 使用密封类对 UI 状态建模
• 使用扩展函数编写工具代码

Compose

• 所有新屏幕默认使用 Jetpack Compose 作为 UI 工具包
• 仅在与旧版代码互操作或使用仅支持 View 的第三方 SDK 时才允许使用 Views
• 优先使用无状态 composable（将状态提升至 ViewModel）
• 使用 LaunchedEffect 处理副作用，不要在组合过程中处理
• 使用 collectAsStateWithLifecycle() 收集 Flow
• 为 LazyColumn/LazyRow 条目设置稳定键
• 必须使用自适应布局——使用 WindowSizeClass 适配手机/平板/折叠屏设备
• Material 3 自适应库：androidx.compose.material3.adaptive:adaptive

自定义 PNG 图标（必需）

• 仅使用自定义 PNG 图标；不要使用图标库
• 使用 painterResource(R.drawable.<name>) 或 @drawable/<name>
• 在项目根目录维护 PROJECT_ICONS.md

遵循 mobile-platform-operations 技能（其中的 mobile-custom-icons 参考），了解命名、目录规则和跟踪要求。

图表（Vico 标准）

• 所有图表需求（折线图、条形图、柱状图、烛台图等）均使用 Vico
• 新屏幕优先使用 Compose 模块；仅在必要时使用 Views
• 设置和当前版本始终遵循官方指南
• 参考 Vico 示例模块中的模式和样式

报告表格（25 行以上）

• 任何可能超过 25 行的报告都必须以表格呈现，而不是卡片
• 遵循 android-ui-ux-design 技能（行数超过 25 行的业务报告采用表格优先或密集列表模式）获取表格优先的指导；导出的报告表格则遵循 professional-word-output 技能。

三种构建变体（必须）

每个 Android 应用都必须恰好有 3 种构建变体。此要求不可协商。

变体	用途	APK 名称	混淆与优化	安装目标
debug（dev）	本地开发	{AppName}-dev-{version}.apk	否	模拟器（默认）
staging	QA / 预生产	{AppName}-staging-{version}.apk	是（R8）	模拟器（按需）
release（prod）	生产环境 / Play Store	{AppName}-prod-{version}.apk	是（R8）	设备（手动）

规则：

1. 用户必须为每个项目提供 staging 和 production API URL。Debug 始终指向本地开发服务（模拟器使用 http://10.0.2.2/...，或使用主机的 LAN IP）。
2. 在主动开发期间，只构建所需的变体——通常是 debug。不要在每次迭代中都构建 staging 和 release。
3. **默认本地开发循环：**正常编码、UI 工作和设备测试时，使用 ./gradlew installDebug（或 assembleDebug）。
4. 仅在发布验证、QA 交接、CI，或用户明确要求所有构建产物时，才构建全部 3 个 APK：./gradlew assembleDebug assembleStaging assembleRelease
5. 如果用户明确要求测试 staging，则改为安装 staging：./gradlew installStaging
6. APK 命名应为每个应用使用统一前缀（例如 DMS-dev-1.0.0.apk、DMS-staging-1.0.0.apk、DMS-prod-1.0.0.apk）。请通过新版 Android Components Variant API 配置，不要使用已弃用的内部输出类。
7. Staging 继承 release 配置（启用 R8 和资源缩减），但使用 debug 签名配置，以便与 dev 同时安装在同一台设备上。
8. ProGuard 规则必须从 staging 和 release 构建中移除 Log.v、Log.d、Log.i 和 println。
9. 绝不要硬编码 API URL——始终使用按构建类型设置的 BuildConfig.API_BASE_URL（或类似变量）。

完整的 Gradle 配置请参阅 references/build-configuration.md。

始终通过按构建类型或 flavor 设置的 BuildConfig.API_BASE_URL（或类似的生成常量）配置 API 端点。绝不要在应用代码中硬编码服务器 URL。

Android Studio + 构建速度基准

在进行更深入的性能优化之前，先建立以下基准：

1. 保持工具为最新版本——在项目允许的情况下，同时更新 Android Studio、SDK 工具、Gradle 和 AGP。
2. 在库支持的情况下，使用 KSP 替代 kapt。 kapt 应视为旧技术。
3. 固定依赖和插件版本——绝不要使用 2.+ 或 latest.release 之类的动态版本。
4. 除非 Build Analyzer 确认项目仍需要 Jetifier，否则禁用它。
5. 在项目和插件兼容后启用配置缓存。
6. 在 Gradle 脚本中使用配置规避和惰性 API；不要在配置阶段运行开销大的逻辑。
7. 保持 debug 构建的静态性——不要使用会导致完整重建的动态版本名称、清单占位符或生成值。
8. 当应用规模足够大，能够让功能模块或核心模块独立编译时，优先进行模块化。
9. **先使用 Build Analyzer 和 Gradle 性能分析工具，再做判断。**先测量，再优化真正的瓶颈。
10. 尽可能在 API 24+ 设备或模拟器上开发，以加快部署迭代。

设备与 Android 版本兼容性（关键）

我们的应用必须兼容仍在使用旧设备的少数用户，也必须兼容使用较新或最新设备的用户。绝不要只在一个 Android 版本上测试。

强制规则：

1. 必须使用 enableEdgeToEdge() — 在 MainActivity.onCreate() 中、调用 super.onCreate() 之前调用。对于以 SDK 35 为目标版本的应用，Android 15（API 35）会强制启用 edge-to-edge。否则，应用在 Android 15 设备上会立即崩溃。这一点不容妥协。
2. 不要直接设置 window.statusBarColor — 该属性已弃用，且与 edge-to-edge 冲突。让 enableEdgeToEdge() 处理系统栏颜色。仅通过 WindowCompat.getInsetsController().isAppearanceLightStatusBars 控制浅色或深色图标的显示效果。
3. 至少在两个 Android 版本上测试 — 发布前，始终在 minSdk 模拟器（Android 10）和较新的 Android（14/15）模拟器或设备上验证。
4. 对特定版本的 API 做防护 — 使用 minSdk 之后新增的 API 时，用 if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.X) 检查进行封装。
5. 保持 targetSdk 为最新版本 — 以最新的稳定 SDK 为目标版本（目前为 35）。不要落后——Google Play 要求使用较新的 targetSdk，而较新的 Android 版本会对以其为目标版本的应用实施更严格的行为要求。
6. 需要切换语言区域时使用 AppCompatActivity（AppCompatDelegate.setApplicationLocales()）。纯 Compose 应用则优先使用 ComponentActivity。

正确的 MainActivity 模式：

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        installSplashScreen()  // Before super
        enableEdgeToEdge()     // Before super — MANDATORY for targetSdk 35
        super.onCreate(savedInstanceState)
        setContent { ... }
    }
}

安全

• 使用 EncryptedSharedPreferences 存储敏感数据
• 对 API 调用进行证书固定——绝不要使用占位证书固定值（这会导致 SSLPeerUnverifiedException）。启用前，使用 openssl 从服务器提取真实的 SHA-256 固定值。提取命令见 references/security.md。
• 对于 Let's Encrypt 服务器：始终在叶证书固定值之外，同时固定中间 CA（稳定）。叶证书固定值会在每次自动续期时每 90 天轮换；中间 CA 固定值则可跨续期保持有效。
• 使用 ENABLE_CERT_PINNING BuildConfig 标志：开发环境设为 false，预发布/生产环境设为 true
• 固定应用所连接的所有服务器域名（包括预发布环境和生产环境）
• 对敏感操作使用生物识别身份验证
• 不要硬编码机密，使用 BuildConfig 字段
• 发布版本使用 ProGuard/R8

测试

• 为 ViewModel 和 Use Case 编写单元测试（MockK）
• 为屏幕编写 Compose UI 测试（ComposeTestRule）
• 使用 Turbine 测试 Flow
• 在测试中使用 Hilt 测试规则进行 DI

性能

• 在调试版本中启用 StrictMode
• 在延迟加载列表中使用稳定的键
• 对高开销计算使用 derivedStateOf
• 使用带缓存的 Coil 加载图像
• 发布版本启用 ProGuard 和资源缩减
• 正常开发期间仅构建 debug；完整的多变体构建仅用于 QA 或发布检查
• 更改 Gradle 内存、GC 或插件设置前，先使用 Build Analyzer
• 优先使用基于 KSP 的处理器；除非没有受支持的迁移路径，否则移除 kapt
• 除非依赖项审计证明有必要，否则保持 android.enableJetifier=false
• 检查插件兼容性并修复违规项后，再启用配置缓存

发布门槛

在将 Android 功能视为可用于生产环境之前：

• 在 minSdk 和最新版本的 Android 上验证主要用户流程。
• 验证离线、网络缓慢和权限被拒绝时的行为。
• 根据性能预期验证启动、滚动和列表交互。
• 验证崩溃报告、分析和审计敏感操作均已埋点。
• 验证敏感数据绝不会出现在日志、屏幕截图或不安全的存储中。
• 验证 android-ui-ux-design 的高级 UX 检查项，涵盖导航、触控目标、文本缩放、TalkBack、状态完整性以及符合平台原生风格的精致体验。

本地开发网络（WAMP）

• 在本地计算机上开发时（Windows WAMP 或 Ubuntu），Android 模拟器必须通过主机的静态 LAN IP 访问后端，而不是使用 localhost。
• 始终在开发设置说明中记录静态 IP，并在 Android 开发版中将其用于 BASE_URL。
• 确认防火墙规则允许通过 WAMP HTTP 端口接收入站连接。

Google Play 审核准备

• 提交 Play Console 前，使用 mobile-platform-operations 技能（其中的 google-play-store-review 参考资料）。
• 保持 targetSdk 为最新版本，并确保后台工作符合规范。
• 确保 Data Safety 表单与 SDK 和权限相符。
• 提供公开的隐私政策，并在应用内添加链接。
• 验证广告和 IAP 流程是否透明，并让用户能够自主控制。

强制的主题外观设置

每个 Android 应用都必须在其工具/设置部分中包含主题外观选择器。这是一项不可妥协的标准——用户必须能够控制应用的视觉主题。

要求：

1. **三个选项：**系统默认（遵循设备设置）、浅色、深色
2. **默认值：**系统默认——始终遵循用户在设备范围内的偏好设置
3. **位置：**工具或设置中心屏幕中的“外观”部分
4. **持久化：**存储在 SharedPreferences 中（不加密——非敏感数据）
5. **响应性：**主题更改立即生效，无需重启应用（使用 StateFlow）

实现模式：

// 1. ThemePreferences.kt (data/local/prefs/)
enum class ThemeMode(val key: String, val label: String) {
    SYSTEM("system", "System default"),
    LIGHT("light", "Light"),
    DARK("dark", "Dark");
    companion object {
        fun fromKey(key: String): ThemeMode =
            entries.firstOrNull { it.key == key } ?: SYSTEM
    }
}

@Singleton
class ThemePreferences @Inject constructor(
    @ApplicationContext context: Context
) {
    private val prefs = context.getSharedPreferences("theme_prefs", Context.MODE_PRIVATE)
    private val _themeMode = MutableStateFlow(loadThemeMode())
    val themeMode: StateFlow<ThemeMode> = _themeMode.asStateFlow()

    private fun loadThemeMode(): ThemeMode =
        ThemeMode.fromKey(prefs.getString("theme_mode", "system") ?: "system")

    fun setThemeMode(mode: ThemeMode) {
        prefs.edit().putString("theme_mode", mode.key).apply()
        _themeMode.value = mode
    }
}

// 2. MainActivity.kt — resolve ThemeMode to darkTheme boolean
val themeMode by themePreferences.themeMode.collectAsState()
val darkTheme = when (themeMode) {
    ThemeMode.SYSTEM -> isSystemInDarkTheme()
    ThemeMode.LIGHT -> false
    ThemeMode.DARK -> true
}
AppTheme(darkTheme = darkTheme) { /* content */ }

// 3. Tools/Settings screen — FilterChip row for selection
ThemeMode.entries.forEach { mode ->
    FilterChip(
        selected = selected == mode,
        onClick = { viewModel.setThemeMode(mode) },
        label = { Text(mode.label) },
        leadingIcon = if (selected == mode) { { Icon(Icons.Default.Check, null) } } else null
    )
}

SaaS 移动应用的第 1 阶段引导模式

为现有 SaaS 后端构建原生 Android 应用时，始终先实现第 1 阶段：登录 + 仪表板 + 空白标签页。这是添加任何业务功能之前的强制起点。

第 1 阶段交付内容

1. JWT 身份验证 — 登录/登出、带轮换机制的令牌刷新、泄露检测、加密存储
2. 仪表板 — 实际 KPI 统计数据、离线优先的 Room 缓存、下拉刷新、闪烁加载效果
3. 5 标签页导航 — 最多包含 5 个标签页的底部栏，以及用于未来功能的占位屏幕
4. 完整基础设施 — Hilt DI、Retrofit 拦截器链、Room 数据库、Material 3 主题、网络监控器
5. 40 多项单元测试 — 测试 ViewModel、用例、仓库和拦截器

为什么要先实现第 1 阶段

• 验证整个垂直切片（Compose UI → ViewModel → UseCase → Repo → Retrofit → PHP → MySQL）
• 建立所有可复用的基础设施模式
• 立即为用户提供可安装、可运行的应用
• 尽早发现后端集成问题

完整的第 1 阶段计划模板请参阅 android-saas-planning 技能。

KMP 项目

如果这是一个 Kotlin Multiplatform 项目，本技能负责 composeApp/ 模块（Android UI 和平台集成）。shared/ 模块由 kmp-development 技能负责。在 composeApp/ 中使用 Hilt 进行 DI，在 shared/ 中使用 Koin。使用 kmp-development 技能对共享模块进行测试驱动开发。

反模式

• 在 Composable 中编写业务逻辑
• 在 ViewModel 中使用 mutableStateOf 而非 StateFlow
• 硬编码颜色/尺寸，而不使用设计令牌
• 在 UI 中跳过错误状态
• 在主线程上执行网络调用
• 在 LazyColumn 列表项中遗漏 key 参数
• 创建臃肿的 ViewModel（应按功能拆分，而非按屏幕拆分）
• 忽略生命周期（使用 collectAsStateWithLifecycle）
• 只构建适用于手机的 UI——所有屏幕都必须适配平板/折叠屏设备
• 使用硬编码的 isTablet() 检查，而不使用 WindowSizeClass 断点
• 缺少 enableEdgeToEdge()——会导致应用在 Android 15 设备上立即崩溃
• 直接设置 window.statusBarColor——该方式已弃用，且与 edge-to-edge 冲突
• 只在一个 Android 版本上测试——必须在旧版（minSdk）和新版（最新版本）设备上验证

与其他技能集成

feature-planning           -> spec + implementation strategy
  |
android-development        -> Kotlin/Compose implementation
  |
android-ui-ux-design       -> premium Material 3 UX and screen quality
  |
mobile-platform-operations -> Play policy and submission readiness
  |
api-error-handling         -> Backend API error patterns
  |
mysql-best-practices       -> Database schema (backend)
  |
vibe-security-skill        -> Security review

对于联网的 Android 应用，始终与本技能一并应用 vibe-security-skill。 准备 Play Console 提交时使用 mobile-platform-operations。

参考实现

决策规则

条件	选择
新用户界面	使用 Compose；将现有 View 系统隔离在稳定的边界之后
多个屏幕共享的业务规则	纯 Kotlin 领域用例
Android 框架依赖	将其保留在领域层之外
不同环境的发布行为不同	使用类型化的构建变体配置；不要硬编码运行时 URL

降级模式

当构建或设备不可用时，提供可供审查的补丁，并列出仍需执行的确切 Gradle、单元、插桩、无障碍和最低 SDK 检查。不要仅凭静态检查就声称兼容设备。

Google 维护着三个官方参考代码库。请将它们用作权威示例：

Now in Android (github.com/android/nowinandroid)

完整的生产级应用。**适用于：**多模块架构、约定插件、离线优先（Room + 网络同步）、跨模块使用 Hilt、版本目录、Gradle KTS 构建配置。

Architecture Samples (github.com/android/architecture-samples)

采用分层架构的 TODO 应用。**适用于：**清晰的 MVVM 模式、具有双数据源的 Repository 模式、使用 Compose 的单 Activity 导航、产品变体（mock/prod）、全面的测试套件（单元 + 集成 + E2E）、清晰的关注点分离。

Compose Samples (github.com/android/compose-samples)

一组专注于特定场景的 Compose 应用。适用于以下 UI 模式：

示例	用途
JetNews	Material 应用结构、主题设置、Compose 测试
Jetchat	Material 3、动态颜色、导航、状态管理
Jetsnack	自定义设计系统、布局、动画
Jetcaster	Redux 风格架构、动态主题、Room、协程
Reply	自适应 UI（手机/平板/可折叠设备）、Material 3
JetLagged	自定义布局、图形、Canvas/Path 绘制

不确定如何实现时，请先查看这些代码库。

输入

产物	必需？	用途
Android 要求、支持的 API 级别、架构、UX 和后端契约	是	限定实现范围

输出

• 提供 Android 代码或设计，并附上生命周期、无障碍、测试、性能和发布方面的证据。

能力约定

读取、搜索和本地构建遵循任务范围；签名、发布到应用商店、修改后端以及销毁设备数据均需明确授权。