当前位置：首页 > news >正文

《从零搭建现代 Android 模块化架构项目（2025 最新实践）》

news 2025/10/17 7:36:13

🧭 一、前言

过去几年 Android 架构经历了从 MVC → MVP → MVVM → Clean Architecture 的演进。
到了 2025 年，官方推荐的现代架构已经非常明确：

Kotlin + Jetpack Compose + Hilt + Clean Architecture + Gradle Kotlin DSL + 多模块化

这种结构不仅提升构建速度与维护性，还能让团队多人并行开发更加高效。

本文将带你从零搭建一个完整的模块化项目结构，
并附上所有关键代码与配置，开箱即用 ✅。

📚 二、项目目标结构

我们最终要得到一个这样的多模块结构：

project-root/
├── app/                      # 主壳工程（启动入口）
├── core/                     # 核心层
│   ├── core-common/          # 通用工具、常量、扩展函数
│   ├── core-network/         # 网络封装（Retrofit + OkHttp）
│   ├── core-database/        # 数据层（Room / DataStore）
│   └── core-ui/              # 通用 Compose UI 组件
├── feature/                  # 功能模块层
│   ├── feature-login/        # 登录模块
│   ├── feature-home/         # 首页模块
│   └── feature-profile/      # 个人中心模块
├── lib/                      # 通用业务库
│   └── lib-router/           # 路由与模块跳转
└── build-logic/              # Gradle 配置（高级工程化）

⚙️ 三、Step 1：创建项目

1.	打开 Android Studio → New Project
2.	选择 Empty Compose Activity
3.	设置：
•	Language: Kotlin
•	Minimum SDK: 24+
•	Name: ModularApp

完成后运行确认项目可正常启动。

🧱 四、Step 2：配置 Kotlin DSL + 版本统一管理

🧩 settings.gradle.kts

pluginManagement {repositories {google()mavenCentral()}
}dependencyResolutionManagement {repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)repositories {google()mavenCentral()}
}rootProject.name = "ModularApp"
include(":app")

🧩 新建文件 gradle/libs.versions.toml

统一依赖与版本管理：

[versions]
kotlin = "2.2.20"
compose = "1.9.3"
compose-material = "1.4.0"
hilt = "2.57.2"
retrofit = "3.0.0"
coil = "2.7.0"[libraries]
compose-ui = { module = "androidx.compose.ui:ui", version.ref = "compose" }
compose-material3 = { module = "androidx.compose.material3:material3", version.ref = "compose-material" }
hilt-android = { module = "com.google.dagger:hilt-android", version.ref = "hilt" }
hilt-compiler = { module = "com.google.dagger:hilt-compiler", version.ref = "hilt" }
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
coil-compose = { module = "io.coil-kt:coil-compose", version.ref = "coil" }

🧩 五、Step 3：配置主模块（app）

app/build.gradle.kts：

plugins {id("com.android.application")id("org.jetbrains.kotlin.android")id("com.google.dagger.hilt.android")kotlin("kapt")
}android {namespace = "com.example.modularapp"compileSdk = 35defaultConfig {applicationId = "com.example.modularapp"minSdk = 24targetSdk = 35versionCode = 1versionName = "1.0"}buildFeatures {compose = true}composeOptions {kotlinCompilerExtensionVersion = libs.versions.compose.get()}
}dependencies {implementation(libs.compose.ui)implementation(libs.compose.material3)implementation(libs.coil.compose)implementation(libs.retrofit)implementation(libs.hilt.android)kapt(libs.hilt.compiler)
}

🧩 六、Step 4：创建子模块

你可以使用 Android Studio → New → Module，
或手动创建以下结构：

例如：core-common/build.gradle.kts

plugins {id("com.android.library")id("org.jetbrains.kotlin.android")
}android {namespace = "com.example.core.common"compileSdk = 34
}dependencies {implementation(kotlin("stdlib"))
}

然后在 settings.gradle.kts 注册：

include(":core:core-common")
include(":core:core-network")
include(":feature:feature-login")

⸻

🧩 七、Step 5：模块依赖管理规则

模块类型可依赖模块说明
app 所有 feature、core 模块启动入口
feature core 层模块各功能模块独立开发
core 无依赖基础服务
lib 可被 core/feature 使用通用库

示例：

// app/build.gradle.kts

dependencies {implementation(project(":feature:feature-login"))implementation(project(":core:core-common"))
}

🧩 八、Step 6：接入 Hilt 依赖注入

App.kt：

@HiltAndroidApp
class App : Application()

AndroidManifest.xml：

<applicationandroid:name=".App"android:label="@string/app_name"android:theme="@style/Theme.ModularApp" />

🧩 九、Step 7：添加 Compose 界面

MainActivity.kt

@AndroidEntryPoint
class MainActivity : ComponentActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setContent {MaterialTheme {HomeScreen()}}}
}示例 UI：@Composable
fun HomeScreen() {Column(modifier = Modifier.fillMaxSize(),horizontalAlignment = Alignment.CenterHorizontally,verticalArrangement = Arrangement.Center) {Text("Welcome to Modular App")}
}

🧩 十、Step 8：可选 - 路由与组件化（ARouter）

lib-router/build.gradle.kts

dependencies {implementation("com.alibaba:arouter-api:1.5.2")kapt("com.alibaba:arouter-compiler:1.5.2")
}初始化（App.kt）：if (BuildConfig.DEBUG) {ARouter.openLog()ARouter.openDebug()
}
ARouter.init(this)使用：ARouter.getInstance().build("/feature/login").navigation()

🧰 十一、进阶优化建议

方向推荐方案
依赖管理 Gradle Version Catalogs (libs.versions.toml)
构建脚本共享 build-logic 模块
模块通信 Kotlin Flow / SharedFlow
构建提速 Gradle Build Cache / Configuration Cache
CI/CD GitHub Actions / Firebase App Distribution
代码规范 Ktlint + Detekt

📘 十二、最终项目技术栈总结

分类技术栈
语言 Kotlin
UI 框架 Jetpack Compose
架构模式 Clean Architecture + MVVM
依赖注入 Hilt
网络层 Retrofit + OkHttp
数据层 Room + DataStore
图片加载 Coil
模块通信 ARouter / Kotlin Flow
构建系统 Gradle Kotlin DSL + Version Catalogs
工程化模块化 + 组件化 + CI/CD