企业官网建设流程全解析

• 桌面应用
• 网络

本文基于 ab-download-manager 仓库中compositeBuilds/shared/README.md的核心思路展开，讲解该项目的作者如何借助 Gradle Composite Build（复合构建）与模块坐标依赖，实现同一份代码在buildSrc与主构建（root project）之间双向复用，同时保留模块整体迁出到独立仓库的能力。读完本文，你将掌握这一构建层复用模式的坐标写法、配置落点与实际源码佐证，可直接套用到自己的多模块 Gradle 项目中。

一、问题背景：buildSrc 与主构建的"代码孤岛"

在大型 Gradle 项目中，buildSrc承担构建脚本与插件的定义职责，而主构建（root project）负责业务模块的编译与打包。两者天然是两个相互独立的构建：buildSrc中的代码无法被主构建的普通模块直接引用，主构建模块中的代码也无法在buildSrc中被加载。

ab-download-manager 的构建体系中恰好存在这种双向需求：

• 以 VersionUtil.kt 为例，buildSrc在打包时需要判断当前操作系统（Linux / macOS / Windows / Android）来选择合适的TargetFormat（Deb / Dmg / Msi 等），这就需要一份"平台检测"代码；
• 与此同时，主构建的普通模块（如 shared/utils 等）在做运行时平台判断时，也需要同一份"平台检测"代码。

如果两份代码分别维护，极易产生行为漂移。该项目的解法，正是在compositeBuilds/shared/README.md中阐述的核心模式：把一个共享模块放进独立的 Composite Build，让buildSrc与主构建同时以模块坐标依赖它。

二、核心模式：Composite Build 中的共享模块

原文档指出：compositeBuilds/shared是一个"同时在buildSrc和主构建中使用的共享模块"。其关键结论是，向每个 composite 模块添加依赖时，使用标准的模块坐标写法：

implementation("$definedGroupId:$definedProjectName:$projectVersion")

即group : 模块名 : version三段式坐标。这一写法看似与普通 Maven 坐标无异，但在 Composite Build 场景下，Gradle 会优先解析到本地参与复合构建的模块，而不是从远程仓库拉取，从而实现了"本地共享、无发布依赖"的效果。

2.1 共享模块的自身定义

compositeBuilds/shared/settings.gradle.kts给出了共享模块作为独立构建的完整定义：

• 通过dependencyResolutionManagement.versionCatalogs复用根目录的 gradle/libs.versions.toml 版本目录（from(files("../../gradle/libs.versions.toml"))），保证依赖版本单一来源；
• rootProject.name = "shared-code-between-gradle-and-app"点名了该模块的设计初衷——"在 Gradle 构建与应用之间共享代码"；
• include("platform")声明了内部的platform子模块。

2.2 坐标三要素的实际取值

以仓库中真实的platform模块为例，坐标三要素在 compositeBuilds/shared/platform/build.gradle.kts 中均有明确赋值：

因此实际依赖坐标即为implementation("ir.amirab.util:platform:1")。

三、两种消费方式：buildSrc 与主构建

原文档强调这一模式的两大收益，仓库源码可以逐一印证。

3.1 收益一：buildSrc 与主构建可共享同一份代码

在buildSrc侧消费：buildSrc/build.gradle.kts 的dependencies块中，除了引用一系列版本目录中的插件与semver库之外，明确写入了：

implementation("ir.amirab.util:platform:1")

这正是文档所述坐标写法的落地。buildSrc随即在 VersionUtil.kt 中直接调用Platform.getCurrentPlatform()来按操作系统推断打包格式：

private fun guessTargetFormatBasedOnCurrentOs() = when (Platform.getCurrentPlatform()) { Platform.Desktop.Linux -> TargetFormat.Deb Platform.Desktop.MacOS -> TargetFormat.Dmg Platform.Desktop.Windows -> TargetFormat.Msi Platform.Android -> error("we are executing gradle in desktop :D") }

同一份platform模块同时被主构建侧的 shared/utils 依赖。也就是说，同一套"平台识别"逻辑被两个独立构建共同引用，从根源上避免了双份实现的分叉。

在主构建侧消费：根 settings.gradle.kts 通过includeBuild将共享模块纳入复合构建，并为其命名：

includeBuild("./compositeBuilds/shared") { name = "build-shared" }

includeBuild是 Composite Build 的入口——它告诉 Gradle：请把compositeBuilds/shared当作本地构建参与依赖解析，ir.amirab.util:platform:1这类坐标会优先命中本地模块。同理，仓库还将 compositeBuilds/plugins（内含git-version-plugin、installer-plugin等自定义插件）一并纳入includeBuild，构建层复用是该项目的一贯手法。

3.2 收益二：模块可无修改迁出为独立仓库

这是该模式最值得借鉴的工程价值。因为共享模块本身就是一个自包含的独立 Gradle 构建（有自己的settings.gradle.kts、build.gradle.kts），它不依赖buildSrc的任何内部结构，仅以相对路径../../gradle/libs.versions.toml引用根目录版本目录。

一旦该模块迁往独立仓库，只需把这一处版本目录引用改为指向新仓库自身的libs.versions.toml，其余业务代码与构建脚本可原样保留；消费方也只需把依赖解析从"本地 includeBuild"切换到"远程仓库解析"即可，坐标形式完全不变。这正是原文档所说"可以在不进行任何修改的情况下，把这个模块移到独立仓库"的技术基础。

四、共享模块的代码实质：以 platform 为例

共享模块目前包含一个子模块platform，其职责可以从源码结构中确认，分文件位于 compositeBuilds/shared/platform/src/main/kotlin/ir/amirab/util/platform/：

• Platform.kt：用密封类描述Android与Desktop.Windows / Linux / MacOS，通过System.getProperty("os.name")的lazy惰性探测得到当前平台，并提供isWindows()、isLinux()、isMac()、isAndroid()等便捷判断；
• Arch.kt：描述x64、arm64、x32三种 CPU 架构，支持把amd64、x86_64、aarch64等字符串归一化为标准架构名。

这套代码既服务构建期（如打包格式选择），也可服务于运行期，正是"一份代码、两处消费"的典型样本。

五、模式要点小结

这套模式的适用前提是：共享代码本身足够通用、不依赖消费方内部 API；并且共享模块与根项目之间要保持依赖关系的单向性，才能保证未来"整体迁出、零修改"。对任何在buildSrc与业务模块之间反复复制工具类、平台检测代码的 Gradle 工程，ab-download-manager 的compositeBuilds/shared都是一个值得直接借鉴的轻量级样板。

• 桌面应用
• 网络