4. 架构决策记录（ADR）
📚 公共模块设计 common 模块
🧩 职责 · 基础工具 · 扩展 · 通用组件
Jetpack Compose
多模块架构
① common 模块核心职责
🎯 单一依赖 & 收敛
- 所有业务模块依赖 common，而非互相依赖
- 统一管理第三方库版本 (libs.versions.toml)
- 提供 Base/通用接口，降低耦合
- 放置跨模块共享的数据类、常量
🧱 基础设施层
- 网络/数据库/存储 抽象
- 通用 ViewModel 基类
- 日志、安全、权限封装
- 主题、颜色、尺寸定义
② 基础工具类 & 扩展函数
| 类别 | 工具/扩展 | 说明 |
|---|---|---|
| 🛠️ 工具类 | NetworkUtil | 网络状态监听、类型判断 |
| 🛠️ 工具类 | DateUtil | 时间格式化、相对时间 |
| 🛠️ 工具类 | FileUtil | 缓存目录、文件读写 |
| 🛠️ 工具类 | ScreenUtil | dp / px 转换、屏幕信息 |
| ⚡ 扩展函数 | Context.toast() | 简化 Toast 显示 |
| ⚡ 扩展函数 | String.isValidEmail() | 邮箱格式校验 |
| ⚡ 扩展函数 | Int.dp | Int 转 Dp (Compose) |
| ⚡ 扩展函数 | List | 防御性拷贝 |
| 🎨 Compose扩展 | Modifier.paddingHorizontal() | 快速水平内边距 |
| 🎨 Compose扩展 | Color.complementary() | 获取互补色 |
// ===== 扩展函数示例 (Context + Compose) =====
fun Context.showShortToast(msg: String) {
Toast.makeText(this, msg, Toast.LENGTH_SHORT).show()
}
// Modifier 扩展 —— 通用边距
fun Modifier.commonPadding(): Modifier =
this.padding(horizontal = 16.dp, vertical = 12.dp)
// 字符串扩展 —— 邮箱校验
fun String.isValidEmail(): Boolean {
return !isNullOrBlank() &&
android.util.Patterns.EMAIL_ADDRESS.matcher(this).matches()
}
③ 通用 Composable 组件
📦 常用组件清单
- CommonTopBar — 统一标题栏 + 返回/菜单
- LoadingIndicator — 全屏/内嵌加载动画
- ErrorView — 错误重试占位图
- EmptyState — 空数据提示
- NetworkImage — 带占位/渐变的图片
- CommonButton — 主题按钮 (Filled/Outlined)
- ShimmerPlaceholder — 骨架屏
🧩 组件设计原则
- 参数化配色 & 字体 (遵循 Material3)
- 支持 contentSlot / 自定义行为
- 默认使用 common 主题 token
- 轻量、无业务侵入
- 配合预览 @Preview 多设备
// ===== CommonTopBar 示例 =====
@Composable
fun CommonTopBar(
title: String,
onBack: (() -> Unit)? = null,
actions: @Composable RowScope.() -> Unit = {}
) {
TopAppBar(
title = { Text(title, fontWeight = FontWeight.SemiBold) },
navigationIcon = {
if (onBack != null) {
IconButton(onClick = onBack) {
Icon(Icons.AutoMirrored.Filled.ArrowBack, "返回")
}
}
},
actions = actions,
colors = TopAppBarDefaults.topAppBarColors(
containerColor = MaterialTheme.colorScheme.surface,
titleContentColor = MaterialTheme.colorScheme.onSurface
)
)
}⬆ 多模块依赖关系：所有业务模块仅依赖 :common
④ 通用组件典型场景
📱 页面状态管理
- Loading → ShimmerPlaceholder
- Error → ErrorView + 重试回调
- Empty → EmptyState(icon, message)
- Content → 业务 Composable
🧪 统一交互
- CommonTopBar 自动处理返回/标题
- CommonButton 禁用/加载态
- NetworkImage 配合 Coil/Glide
- 全局 Snackbar / Dialog 封装