安卓原生项目目录该怎么组织 一份可落地的模块分层实践

安卓原生项目目录该怎么组织 一份可落地的模块分层实践

1024KB1024KB 移动端开发 2026-11-14 19:26:27 浏览 81978 字数 2051

安卓原生项目的代码组织方式直接决定了后期维护成本,合理的目录结构应围绕功能模块划分而非单纯按文件类型堆放,否则随着业务增长,Activity、Adapter 与工具类会迅速变成难以定位的散沙。一份可落地的项目结构手册,核心目标是让新成员能在短时间内找到任意功能对应的代码位置。

这篇文章从工程实践的视角出发,梳理安卓原生开发中项目结构的组织原则、目录分层方式、模块化拆分边界以及常见的结构踩坑场景,帮助团队在项目初期就建立可扩展的骨架。

按功能分包比按类型分包更能适应业务增长

按功能分包是安卓原生项目结构中最具扩展性的组织方式,它把同一业务功能涉及的界面、数据、状态代码收敛到同一个包内,避免跨包跳转带来的认知负担。

初学者常按照类型把代码分成 activity、adapter、model、util 等目录,这种结构在页面数量少于十个时看起来整齐,但一旦功能膨胀,每个类型目录都会堆满几十个文件,修改一个需求需要在四个目录之间来回切换。

按功能分包的组织方式更接近真实开发路径。以电商应用为例,可以把 feature 作为顶层目录,下面按 home、cart、order、profile 拆分,每个功能包内部再自行划分界面、数据与状态。

对比维度按类型分包按功能分包
定位修改点需跨多个类型目录搜索集中在单个功能包内
模块拆分成本高,代码相互穿插低,功能边界天然清晰
并行开发冲突多个成员修改同一目录各自负责独立功能包
删除废弃功能需逐类型清理残留直接删掉整个功能包

这个对比并非否定类型分包在小型项目中的简洁性,而是指出当页面数量增长后,功能分包带来的可维护性优势会明显压过初期的目录直观性。

一个分层清晰的安卓工程通常包含四个顶层目录

结构良好的安卓原生工程,顶层目录可以清晰地划分为应用壳层、功能层、核心层与构建配置层,四者职责不重叠。

应用壳层通常命名为 app 或 application,只保留 Application 子类、主 Activity、导航图以及依赖注入的入口配置。它不承载具体业务逻辑,扮演装配者的角色。

功能层命名为 feature,以业务模块为单位再分子目录。每个模块内部自包含界面、ViewModel、状态模型与数据仓库,不依赖其他功能模块的具体实现。

核心层命名为 core,收纳跨功能复用的能力,例如网络客户端的统一封装、通用 UI 组件、基础数据类型、日志与异常处理。核心层只被依赖,不主动依赖功能层。

构建配置层由 build-logic 或 gradle 目录承载,用来集中管理插件版本、编译选项与产物变体,避免每个模块的构建脚本重复声明相同配置。

  • app:只做装配,不写业务
  • feature:业务功能,按模块独立成包
  • core:公共能力,被依赖但不反向依赖
  • build-logic:构建脚本的统一入口

模块化拆分的关键在于依赖方向单向收敛

安卓原生项目做到一定规模后必然走向多模块,而模块化能否稳定运转,取决于依赖方向是否严格单向。

依赖方向应是 app → feature → core,任何跨 feature 的直接依赖都会破坏模块的独立性,让两个本应解耦的业务重新耦合在一起。如果 A 功能需要跳转到 B 功能,通常通过导航路由或接口下沉到 core 层来间接完成。

一个常见的判断标准是:删除任意一个 feature 模块,其余模块仍能编译通过。这条规则能有效阻止功能包之间形成隐式依赖网络。

// settings.gradle.kts 中显式声明参与构建的模块
include(":app")
include(":feature:home")
include(":feature:cart")
include(":feature:order")
include(":core:network")
include(":core:ui")
include(":core:common")

把模块清单集中声明,配合构建缓存,多模块工程的增量编译速度反而比单模块更快,因为变更只触发受影响模块的重新编译。

包内结构应保持界面状态数据三层分离

在单个 feature 模块内部,稳定的做法是把包进一步划分为界面层、状态层与数据层,三层各司其职。

界面层只负责渲染与事件分发,通常包含 Compose 的 Screen 函数或 XML 布局对应的 Fragment。它不应直接持有数据请求逻辑,而是从状态层订阅数据。

状态层承载 ViewModel 与不可变的 UI State 数据类,管理业务状态的产生和流转。把状态定义为不可变对象,能让界面重组时的行为更容易预测。

数据层包含 Repository 与数据源,负责缓存策略、网络请求与本地持久化的协调。界面层对数据来源无感知,只消费状态层暴露的数据。

// 每个 feature 包内的典型分层
feature/home/
    ui/          // Screen、组件、预览
    state/       // ViewModel、UiState
    data/        // Repository、RemoteDataSource、LocalDataSource

这种包内三层结构不追求严格的分层框架,而是通过命名与位置约束让代码职责一目了然。

资源与构建配置的目录划分容易被忽视

资源目录与构建配置的组织质量,往往在项目中期才暴露出问题,早期不规划会导致资源命名冲突与构建脚本膨胀。

资源方面,建议在 res 下按功能加前缀命名,例如首页相关图片使用 home_ 前缀,订单相关字符串使用 order_ 前缀。多模块工程中,各模块独立维护自己的资源目录,避免把全部资源集中在 app 模块。

随着项目推进,资源文件数量增长很快,若不按模块隔离,资源合并冲突与重复资源会显著增加包体积。把资源随功能模块下沉,是控制这类问题的有效手段。

构建配置方面,把插件声明、编译 SDK 版本、Java/Kotlin 编译目标等统一抽到 build-logic 的约定插件中,各模块只需应用约定插件,不再重复写版本号。这样升级编译配置时只需改一处。

项目结构手册的价值不在于规定每一层必须叫什么名字,而在于让团队对代码归属形成一致预期,减少每次新增功能时的犹豫成本。

结构失序往往从功能边界的模糊开始

绝大多数结构失序问题,根源都不在目录命名本身,而在于功能边界没有被明确划定。

当某个工具类被随意放进 util 目录,当某个数据模型同时被订单和购物车模块引用却没有下沉到 core,结构就开始失去约束力。等到重构时,这些隐式依赖已经蔓延到大量文件。

可以借助静态检查规则,禁止 feature 模块之间相互依赖,也禁止 core 模块引用 feature。把结构约束编码进构建规则,比靠文档和口头约定更能长期维持目录的整洁。

对于正在扩张的安卓原生团队,先定下顶层四目录与依赖方向,再在 feature 内部固定三层分包,这套组合能覆盖大多数项目的结构需求,并在后续迭代中保持稳定。

分享到:

评论

加载中...
我
还没有评论,快来抢沙发吧~