android-development

Android 开发

按照 Google 的官方架构指南构建 Android 应用，参考 NowInAndroid 示例应用。

快速参考

任务	参考文件
项目结构与模块	modularization.md
架构层（UI、Domain、Data）	architecture.md
Jetpack Compose 模式	compose-patterns.md
Gradle 与构建配置	gradle-setup.md
测试方法	testing.md

工作流决策树

创建新项目？ → 阅读 modularization.md 了解项目结构 → 使用 assets/templates/ 中的模板

添加新功能？ → 创建包含 api 和 impl 子模块的功能模块 → 遵循 architecture.md 中的模式

构建 UI 屏幕？ → 阅读 compose-patterns.md → 创建 Screen + ViewModel + UiState

设置数据层？ → 阅读 architecture.md 中的数据层部分 → 创建 Repository + DataSource + DAO

核心原则

1. 离线优先：本地数据库是事实来源，与远程端同步
2. 单向数据流：事件向下流动，数据向上流动
3. 响应式流：使用 Kotlin Flow 暴露所有数据
4. 按功能模块化：每个功能都独立封装，边界清晰
5. 设计上易于测试：使用接口和测试替身，不使用模拟库

架构层

┌─────────────────────────────────────────┐
│              UI Layer                    │
│  (Compose Screens + ViewModels)          │
├─────────────────────────────────────────┤
│           Domain Layer                   │
│  (Use Cases - optional, for reuse)       │
├─────────────────────────────────────────┤
│            Data Layer                    │
│  (Repositories + DataSources)            │
└─────────────────────────────────────────┘

模块类型

app/                    # App module - navigation, scaffolding
feature/
  ├── featurename/
  │   ├── api/          # Navigation keys (public)
  │   └── impl/         # Screen, ViewModel, DI (internal)
core/
  ├── data/             # Repositories
  ├── database/         # Room DAOs, entities
  ├── network/          # Retrofit, API models
  ├── model/            # Domain models (pure Kotlin)
  ├── common/           # Shared utilities
  ├── ui/               # Reusable Compose components
  ├── designsystem/     # Theme, icons, base components
  ├── datastore/        # Preferences storage
  └── testing/          # Test utilities

创建新功能

1. 创建带有导航键的 feature:myfeature:api 模块
2. 创建 feature:myfeature:impl 模块，其中包含：
   • MyFeatureScreen.kt - 可组合 UI
   • MyFeatureViewModel.kt - 状态持有者
   • MyFeatureUiState.kt - 表示各状态的密封接口
   • MyFeatureNavigation.kt - 导航设置
   • MyFeatureModule.kt - Hilt DI 模块

标准文件模式

ViewModel 模式

@HiltViewModel
class MyFeatureViewModel @Inject constructor(
    private val myRepository: MyRepository,
) : ViewModel() {

    val uiState: StateFlow<MyFeatureUiState> = myRepository
        .getData()
        .map { data -> MyFeatureUiState.Success(data) }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5_000),
            initialValue = MyFeatureUiState.Loading,
        )
    
    fun onAction(action: MyFeatureAction) {
        when (action) {
            is MyFeatureAction.ItemClicked -> handleItemClick(action.id)
        }
    }
}

UiState 模式

sealed interface MyFeatureUiState {
    data object Loading : MyFeatureUiState
    data class Success(val items: List<Item>) : MyFeatureUiState
    data class Error(val message: String) : MyFeatureUiState
}

Screen 模式

@Composable
internal fun MyFeatureRoute(
    onNavigateToDetail: (String) -> Unit,
    viewModel: MyFeatureViewModel = hiltViewModel(),
) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    MyFeatureScreen(
        uiState = uiState,
        onAction = viewModel::onAction,
        onNavigateToDetail = onNavigateToDetail,
    )
}

@Composable
internal fun MyFeatureScreen(
    uiState: MyFeatureUiState,
    onAction: (MyFeatureAction) -> Unit,
    onNavigateToDetail: (String) -> Unit,
) {
    when (uiState) {
        is MyFeatureUiState.Loading -> LoadingIndicator()
        is MyFeatureUiState.Success -> ContentList(uiState.items, onAction)
        is MyFeatureUiState.Error -> ErrorMessage(uiState.message)
    }
}

Repository 模式

interface MyRepository {
    fun getData(): Flow<List<MyModel>>
    suspend fun updateItem(id: String, data: MyModel)
}

internal class OfflineFirstMyRepository @Inject constructor(
    private val localDataSource: MyDao,
    private val networkDataSource: MyNetworkApi,
) : MyRepository {

    override fun getData(): Flow<List<MyModel>> =
        localDataSource.getAll().map { entities ->
            entities.map { it.toModel() }
        }
    
    override suspend fun updateItem(id: String, data: MyModel) {
        localDataSource.upsert(data.toEntity())
    }
}

关键依赖项

// Gradle version catalog (libs.versions.toml)
[versions]
kotlin = "1.9.x"
compose-bom = "2024.x.x"
hilt = "2.48"
room = "2.6.x"
coroutines = "1.7.x"

[libraries]
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }

构建配置

在 build-logic/ 中使用约定插件以统一配置：

• AndroidApplicationConventionPlugin - 应用模块
• AndroidLibraryConventionPlugin - 库模块
• AndroidFeatureConventionPlugin - 功能模块
• AndroidComposeConventionPlugin - Compose 设置
• AndroidHiltConventionPlugin - Hilt 设置

完整构建配置请参阅 gradle-setup.md。