安卓原生项目的结构组织方式直接决定了代码的可维护性与团队协作效率。一个清晰的工程结构能让新成员快速定位到目标文件,也能让构建流程保持稳定可预测。很多项目在初期为了追求开发速度而随意放置文件,等到代码量增长到一定规模后,重构成本会变得极其高昂。理解Android Gradle Plugin对项目结构的约定,是搭建可维护工程的第一步。
Android Studio创建的默认项目结构遵循Gradle的源集(SourceSet)约定,每个源集对应一组特定用途的源码与资源目录。这些约定不是随意的命名规则,而是构建系统在编译期进行资源合并与代码编译的依据。
标准单模块项目通常包含以下核心目录:
src/main/java或src/main/kotlin:存放应用的主要源代码,构建时会被编译为DEX文件src/main/res:存放所有资源文件,包括布局、图片、字符串、颜色、尺寸等src/main/assets:存放需要以原始字节流读取的文件,通过AssetManager访问src/main/AndroidManifest.xml:声明应用组件、权限、硬件特性等元数据src/androidTest:存放需要运行在真实设备或模拟器上的仪器化测试代码src/test:存放运行在本地JVM上的单元测试代码res目录下的子目录命名同样有严格约定。布局文件放在layout目录,图片资源按密度分别存放在drawable-mdpi、drawable-hdpi、drawable-xhdpi等目录,字符串和颜色定义分别放在values/strings.xml与values/colors.xml中。构建系统会根据设备配置自动选择最匹配的资源版本。
多模块拆分的核心原则是按业务边界与复用层次切分,而非按技术分层机械划分。常见的做法是把基础工具、网络层、数据层、通用UI组件下沉为独立模块,业务功能模块依赖这些基础模块,应用主模块只负责组装与导航。
一个可落地的模块划分参考如下:
| 模块类型 | 职责 | 依赖方向 |
|---|---|---|
| app | 应用入口、导航宿主、DI容器装配 | 依赖所有业务模块 |
| feature-* | 具体业务功能页面与逻辑 | 依赖core模块 |
| core-ui | 通用UI组件、主题、自定义View | 不依赖业务模块 |
| core-network | 网络请求封装、拦截器、序列化配置 | 不依赖业务模块 |
| core-data | Repository实现、本地数据库、数据源切换 | 依赖core-network |
| core-common | 扩展函数、常量、工具类 | 不依赖任何模块 |
这种划分方式保证了依赖方向单一,避免模块间循环依赖。业务模块之间不应直接互相依赖,需要通信时通过导航协议或事件总线解耦。
资源目录的组织应兼顾功能归类与配置限定符的正确使用。资源限定符是Android资源系统的核心机制,它允许同一资源在不同设备配置下呈现不同内容,构建时由AAPT2完成资源合并与索引。
常见限定符组合包括:
values-zh-rCN、values-en-rUSlayout-sw600dp用于平板布局values-night存放深色主题下的颜色定义values-v31用于Android 12及以上版本的特定配置在大型项目中,建议将资源按功能模块进一步细分。例如在res/layout下再用命名前缀区分:fragment_home_*.xml、item_order_*.xml、dialog_confirm_*.xml。资源ID的命名前缀能显著提升在代码中查找布局文件的效率。
字符串资源应避免全部堆积在单一strings.xml中。可以按功能拆分为strings_home.xml、strings_order.xml等独立文件,只要它们都位于values目录下,构建系统会自动合并。这种做法在团队协作时能大幅减少合并冲突。
Gradle构建脚本的组织应遵循配置与逻辑分离、版本集中管理的原则。根项目的build.gradle负责声明全局插件与仓库地址,各模块的build.gradle只包含自身特有的配置。
版本集中管理推荐使用gradle/libs.versions.toml版本目录文件,这是Gradle官方推荐的依赖版本声明方式。使用版本目录后,依赖声明从硬编码字符串变为类型安全的访问器,IDE可以提供自动补全与跳转支持。
[versions]
agp = "8.2.0"
kotlin = "1.9.20"
composeBom = "2023.10.01"
[libraries]
compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
material3 = { group = "androidx.compose.material3", name = "material3" }
[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }在模块的build.gradle.kts中引用时,直接使用libs.compose.bom这样的访问器,彻底消除版本号散落各处的问题。
自定义构建逻辑应抽取到buildSrc或独立的Gradle插件模块中。当多个模块需要共享相同的构建配置时(例如统一的编译选项、签名配置、混淆规则),将其封装为约定插件能避免重复代码。约定插件本质上是预编译的Gradle脚本,通过plugins块中的id引用,执行效率高于在每个模块中重复解析脚本。
包结构应按功能划分而非按技术层划分类别。按层划分(如把所有Activity放在一个包、所有Adapter放在另一个包)在业务复杂度提升后会迅速失去可读性,因为修改一个功能时需要跨多个包跳转。
按功能划分时,每个功能包内包含该功能所需的全部组件:页面、ViewModel、数据模型、仓库接口。一个订单列表功能包内可能包含OrderListFragment、OrderListViewModel、OrderListAdapter、OrderRepository、Order数据类。当需要删除或复用一个功能时,直接移动整个包即可,影响范围清晰可控。
跨功能共享的代码应放在common或base包中,并严格限制其增长。共享包中的内容应是经过验证的通用逻辑,而非任意功能的临时存放点。
最常见的结构问题是把Application类当作全局状态容器,导致初始化逻辑膨胀且难以测试。修正方式是将初始化工作按功能维度拆分为独立的Initializer,通过AndroidX Startup库或手动注册机制在Application.onCreate中统一调度,每个Initializer只负责自身模块的初始化。
另一个高频误区是在res/values中定义大量与业务无关的通用尺寸值,导致不同功能模块的尺寸定义互相污染。建议将尺寸值按功能前缀区分,例如home_spacing_page_margin、order_item_card_height,命名中的功能前缀使归属关系一目了然。
资源目录的扁平化堆放也是需要警惕的问题。当drawable目录中包含数百个文件时,查找效率会急剧下降。可以按功能建立子目录,例如drawable/home/、drawable/order/,资源引用时通过R.drawable.home_banner的方式依然可以正常索引,因为AAPT2会递归扫描子目录。
安卓原生开发的项目结构总结起来就是一句话:让目录结构显式表达依赖关系与功能边界。好的结构让构建系统高效运行,让团队成员各司其职,让代码在持续迭代中保持可控的复杂度。
评论
加载中...