Exposed BOM（exposed-bom）使用指南：用物料清单统一管理 Kotlin SQL 框架的全部模块版本

• ORM
• 后端
• 数据存储

Exposed 是 JetBrains 出品的 Kotlin ORM/SQL 框架，整个项目被拆分成 core、transport、DAO 与大量扩展模块。本文以仓库中的 exposed-bom/README.md 为骨架，讲解如何通过Bill of Materials（BOM，物料清单）在 Maven 与 Gradle 中一次性锁定所有 Exposed 模块的版本，从而彻底告别"每个依赖手写版本号、模块间版本不一致"的维护痛点。读完本文，你将能在自己的项目中用两种构建工具正确引入exposed-bom，并理解它与仓库中另一条依赖管理路线exposed-version-catalog之间的异同与取舍。

为什么 Exposed 需要一张 BOM

Exposed 是一个典型的多模块 Kotlin 项目。从仓库根目录的 settings.gradle.kts 可以看到，它同时构建exposed-core、exposed-dao、exposed-jdbc、exposed-r2dbc、exposed-kotlin-datetime、exposed-crypt、exposed-json、exposed-migration-core、exposed-spring-boot-starter、spring-transaction等二十余个模块。这些模块属于同一个发布体系，共享同一个版本号：例如当前仓库中 BOM 文档与版本目录文档标注的版本均为1.5.0（见 exposed-bom/README.md 与 exposed-version-catalog/README.md）。

这意味着如果你在项目中手动为exposed-core、exposed-dao、exposed-jdbc各自写版本号，很容易出现混用不同版本导致的二进制兼容问题。BOM 的职责就是解决这一点：它是一份只包含<dependencyManagement>版本声明的 POM 文件，本身不携带任何代码，只负责把所有 Exposed 模块的版本集中约束。

从 CHANGELOG.md 可知，Exposed 的 BOM 自0.32.1版本起正式提供（"Bill Of Materials (BOM) available"），并且后续还专门修复过发布流程中 BOM 模块缺失的问题（"fix: exposed-bom module missing when publishing"），足见它在官方模块分发体系中的正式地位。在 build.gradle.kts 中，exposed-bom与exposed-version-catalog一起被列入apiValidation.ignoredProjects，并且不应用 Kotlin JVM 插件——这正是因为它本质上是"纯聚合 POM"，不含任何可被校验的 API 与源码。

在 Maven 中使用 exposed-bom

在 Maven 工程中，BOM 的引入方式是在pom.xml的<dependencyManagement>中加入一条scope=import、type=pom的特殊依赖。完整配置如下（版本号以当前仓库文档使用的1.5.0为例）：

<dependencyManagement> <dependencies> <dependency> <groupId>org.jetbrains.exposed</groupId> <artifactId>exposed-bom</artifactId> <version>1.5.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.jetbrains.exposed</groupId> <artifactId>exposed-core</artifactId> </dependency> <dependency> <groupId>org.jetbrains.exposed</groupId> <artifactId>exposed-dao</artifactId> </dependency> <dependency> <groupId>org.jetbrains.exposed</groupId> <artifactId>exposed-jdbc</artifactId> </dependency> </dependencies>

关键点拆解：

• <scope>import</scope>：告知 Maven 这条依赖不是普通库，而是要把exposed-bomPOM 中<dependencyManagement>声明的版本规则"导入"到当前工程的依赖管理中。
• <type>pom</type>：指明该依赖是 POM 类型的聚合文件。
• 依赖声明省略<version>：一旦导入 BOM，exposed-core、exposed-dao、exposed-jdbc等所有 Exposed 模块的版本号都由 BOM 统一接管，无需也不能再各自手写版本，否则会与 BOM 约束冲突。
• Exposed 官方文档将 Maven Central 作为默认仓库（Maven 默认启用中央仓库，无需额外配置），所有org.jetbrains.exposed制品均从该仓库发布。

在 Gradle 中使用 exposed-bom

Gradle 中的等价写法是使用platform()依赖约束。Kotlin DSL 的完整示例（来自 exposed-bom/README.md）：

repositories { // Versions after 0.33.1 mavenCentral() } dependencies { implementation(platform("org.jetbrains.exposed:exposed-bom:1.5.0")) implementation("org.jetbrains.exposed", "exposed-core") implementation("org.jetbrains.exposed", "exposed-dao") implementation("org.jetbrains.exposed", "exposed-jdbc") }

要点说明：

• platform(...)是 Gradle 对 Maven BOM 的官方支持：它会将该 POM 中<dependencyManagement>的版本约束应用到当前构建，此后声明 Exposed 依赖时同样无需写版本号。
• 仓库配置：文档明确注释"Versions after 0.33.1"使用mavenCentral()，即较新版本的 Exposed 制品发布在 Maven Central，必须在repositories中加入中央仓库；使用 Groovy DSL 的读者把implementation("a", "b")换成implementation "a:b"的字符串形式即可。
• 与其它平台依赖的叠加：platform()不是排他性的，你可以同时引入 Spring Boot BOM、JUnit BOM 等，Gradle 会按"最近声明优先/显式版本优先"的规则合并约束。仓库的 samples/exposed-migration/build.gradle.kts 中testImplementation(platform("org.junit:junit-bom:5.10.0"))就是这种叠加用法的实际例子。

结合模块体系挑选依赖：core + 一个 transport 起步

要正确使用 BOM，还需要知道该往dependencies里放哪些模块。根据仓库官方文档 documentation-website/Writerside/topics/Adding-dependencies.md 与 README.md，Exposed 模块按职责分为四类，BOM 统一管理其中全部模块的版本：

因此最小的依赖集是：exposed-core+ 一个传输模块（如exposed-jdbc）。引入 BOM 后，这些模块的版本全部被统一约束，你只需要在更换版本时修改 BOM 一处。

另外要注意：BOM 只管 Exposed 自身的模块版本，数据库驱动（如 H2、PostgreSQL JDBC、R2DBC 驱动）仍需在工程中单独声明版本；官方文档的示例中 H2 驱动即以com.h2database:h2:2.4.240的形式显式引入。

进阶路线：BOM 与 exposed-version-catalog 的异同

仓库中还有另一条依赖管理路线：Gradle 版本目录（Version Catalog），对应的制品是exposed-version-catalog（说明文档见 exposed-version-catalog/README.md，于 1.4.0 版本引入，见 CHANGELOG.md）。它与 BOM 的目标一致——统一管理全部 Exposed 模块版本，但机制不同：

• BOM（exposed-bom）：Maven/Gradle 通用。通过dependencyManagement/platform()导入，使用标准坐标字符串org.jetbrains.exposed:exposed-core声明依赖，适合 Maven 用户，也适合偏好传统写法的 Gradle 用户。
• 版本目录（exposed-version-catalog）：Gradle 专属。在settings.gradle.kts中导入后，可通过**类型安全的访问器（accessor）**引用模块，例如implementation(exposedLibs.core)、implementation(exposedLibs.jdbc)、implementation(exposedLibs.kotlin.datetime)。访问器命名规则为：去掉exposed-前缀、连字符转为嵌套访问器，例如exposed-kotlin-datetime→exposedLibs.kotlin.datetime、spring7-transaction→exposedLibs.spring7.transaction。

版本目录还支持整体覆盖版本：在导入时通过version("exposed", "1.5.0")即可在单点修改全部模块的版本，这与 BOM 的"改一处"体验一致。仓库中的示例工程 samples/exposed-spring/build.gradle.kts 即采用了exposedLibs.spring.boot4.starter、exposedLibs.jdbc的访问器写法，可作为实践参考。

一个值得注意的细节：官方将目录命名为exposedLibs而非exposed，是因为 Exposed Gradle 插件会注册名为exposed的工程扩展（exposed { migrations { } }DSL），而版本目录也会以目录名注册扩展，二者重名会触发Cannot add extension with name 'exposed'冲突；若你的项目不应用该插件，则完全可以命名为exposed。选用建议：Maven 工程只能走 BOM 路线；Gradle 工程两条路线皆可——想要类型安全的编译期校验就选版本目录，想要与 Maven 工程保持一致的坐标写法则选 BOM。

仓库中的实现与发布依据

以下仓库事实可以帮助你确认 BOM 在 Exposed 构建体系中的位置：

• settings.gradle.kts 第 15 行include("exposed-bom")，确认 BOM 是官方多模块构建的一部分，与exposed-version-catalog（第 28 行）并列。
• build.gradle.kts 将exposed-bom与exposed-version-catalog列入apiValidation.ignoredProjects，并在subprojects中跳过它们（不应用 Kotlin JVM 插件），印证这两个模块是"无源码的聚合制品"：BOM 只产出 POM，不产出 jar 与 API。
• CHANGELOG.md 记录了 BOM 自 0.32.1 引入、以及后续"发布时 BOM 模块缺失"的修复条目，可作为版本演进的时间线证据。
• 版本号说明：本文示例沿用仓库文档标注的1.5.0；实际使用时请以你正在引入的 Exposed 版本为准，BOM 版本号与模块版本号始终一致（如1.4.0对应全模块1.4.0）。

最佳实践小结

1. 版本只写一次：在 Maven 中只维护dependencyManagement里的 BOM 版本；在 Gradle 中只维护platform(...)里的 BOM 版本，其余 Exposed 依赖一律省略版本号。
2. 模块组合保持克制：按官方建议选择exposed-core+ 一个传输模块（exposed-jdbc或exposed-r2dbc），exposed-dao及扩展模块按需添加，避免无谓的体积与冲突面。
3. 驱动与日志另行声明：数据库 JDBC/R2DBC 驱动、SLF4J 实现类依赖不属于 BOM 管辖范围，需单独引入。
4. 升级即"改一处"：需要升级 Exposed 时只更新 BOM/平台依赖的版本号，所有模块自动对齐，从机制上杜绝了跨版本混用的风险。

• ORM
• 后端
• 数据存储