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

🧭 一、前言

过去几年 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

groovy 复制代码

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：

groovy 复制代码

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.dagger.hilt.android")
    kotlin("kapt")
}

android {
    namespace = "com.example.modularapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.modularapp"
        minSdk = 24
        targetSdk = 35
        versionCode = 1
        versionName = "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

groovy 复制代码

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 注册：

groovy 复制代码

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

groovy 复制代码

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

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

App.kt：

kotlin 复制代码

@HiltAndroidApp
class App : Application()

AndroidManifest.xml：

xml 复制代码

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

🧩 九、Step 7：添加 Compose 界面

MainActivity.kt

kotlin 复制代码

@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

groovy 复制代码

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

🚀 十三、一句话总结

✅ Compose 时代的现代 Android 工程化项目标准栈：

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

📊 十四、模块依赖架构图（Mermaid 图）

graph TD

A[app] --> B[feature-login]

A --> C[feature-home]

B --> D[core-common]

C --> D

D --> E[core-network]

D --> F[core-ui]

A --> G[lib-router]

✨ 十五、结语

当项目从单体结构演进为模块化架构后，

不仅能提升构建速度与可维护性，

还能让不同业务团队并行开发、独立发布。

如果你正计划重构项目结构，这套 2025 最新模块化模板

可以作为你的最佳起点 🚀。