Kotlin 后端开发常见问题解答
本页面解答了关于使用 Maven 构建、测试和交付 Kotlin 后端应用程序的一些常见问题。 每个回答都附有链接,指向 Kotlin 或外部文档中更详细的说明。
多模块构建、BOM 与版本管理
如何在多模块构建中统一锁定单个 Kotlin 版本?
在父 POM 文件中声明一个 kotlin.version 属性,并在所有位置复用它:
- 在父
pom.xml文件中设置一次kotlin-maven-plugin的版本。为此,请在<properties>部分设置 Kotlin 版本,并在<build><plugins>或<build><pluginManagement>部分将其引用为${kotlin.version}。 有关更多信息,请参阅项目配置。 - 通过 Kotlin BOM 文件保持 Kotlin 库版本一致,确保
kotlin-stdlib、kotlin-reflect、kotlin-test以及其他构件始终解析为相同的发布版本,不会因模块而异。 有关更多信息,请参阅使用 BOM 管理依赖项。
什么是 Kotlin BOM 以及如何使用它?
Kotlin BOM (org.jetbrains.kotlin:kotlin-bom) 是一个特殊的 POM 文件,用于管理 Kotlin 库的版本,以使相关构件始终与相同的 Kotlin 发布版本保持一致,即使它们是作为传递依赖项引入的。
将其导入到 pom.xml 的 <dependencyManagement> 部分,并设置 <type>pom</type> 和 <scope>import</scope>。 随后在声明 Kotlin 依赖项时即可省略 <version>。这些版本将自动从 BOM 文件中获取。
有关更多信息,请参阅使用 BOM 管理依赖项。
我需要保持 Kotlin Maven 插件版本与 Kotlin 库版本一致吗?
是的。将某一编译器版本与不兼容的 Kotlin 库混用可能会导致“Mixed Kotlin versions”(混合 Kotlin 版本)错误和元数据不兼容。保持一致的最简单方法是使用单一定义的相同 Kotlin 版本。例如:
- 在父
pom.xml文件中设置一次kotlin-maven-plugin的版本,然后在所有位置将其引用为${kotlin.version}。 - 导入 Kotlin BOM,使所有 Kotlin 库都遵循相同的发布版本。
如何跨所有模块配置 Kotlin 编译器选项?
要跨所有 Maven 模块配置 Kotlin 编译器,可以通过以下任一方式在父 pom.xml 文件中集中设置选项:
- 在父级的
<properties>部分设置编译器选项,例如kotlin.compiler.languageVersion、kotlin.compiler.apiVersion和kotlin.compiler.jvmTarget。 - 在父
pom.xml文件中共享单个kotlin-maven-plugin的<configuration>(例如额外的<args>),以便所有模块都使用相同的设置进行编译。
模块特定的替换是可行的,但应当尽量少用。有关选项及其属性名称的完整列表,请参阅编译器选项。
为什么在多模块构建中会出现字节码级别不匹配的情况?
你可能会遇到 UnsupportedClassVersionError 及类似错误,这意味着生成的字节码所针对的 JVM 版本高于运行代码所用的版本。为避免此类问题,请在模块和 CI 之间保持以下各项的一致:
- 运行 Maven 的 JDK。
- Java 编译器目标。
- Kotlin 的
jvmTarget选项。
如果在项目中启用了 <extensions> 选项,Kotlin 和 Java 编译器将自动以相同的字节码版本为目标。有关 Kotlin Maven 插件如何根据构建文件中的不同选项解析 JVM 目标版本的更多信息,请参阅 JVM 目标版本。
对于手动配置,可以使用 maven-toolchains-plugin 来配置统一的工具链,以控制整个构建过程中所有插件所使用的 JDK 版本。有关更多信息,请参阅设置 JDK 版本。
测试:Surefire、Failsafe 和 JUnit
为什么 mvn test 会跳过 Kotlin 测试?
尝试运行 mvn test 命令时,你可能会遇到“Tests run: 0”(运行测试:0)错误。最常见的原因包括:
- 测试发现机制:Surefire 会运行符合
*Test命名模式的测试。Failsafe 插件则通过mvn verify命令运行以*IT后缀命名的集成测试。有关更多信息,请参阅运行测试。 - 类路径上缺少引擎:添加 JUnit 测试依赖项,以便 JUnit 能够发现并运行你的测试。 最简单的选择是使用
kotlin-test-junit5,它会自动拉取所需的 JUnit 构件。有关更多信息,请参阅测试库依赖项。 - 测试源代码未编译:确保运行了 Kotlin 的
test-compile执行阶段,以便在测试执行之前完成 Kotlin 测试源代码的编译。
如何配置 Surefire 插件来运行 JUnit 测试?
要配置 Surefire 插件以运行 JUnit 测试:
- 添加一个
<scope>test</scope>的 JUnit 测试依赖项(例如kotlin-test-junit5),以将 JUnit 包含在测试类路径中。 - 将 Surefire 插件添加到你的
pom.xml文件中。 - 检查类路径中是否存在冲突的测试提供程序(test provider),此类冲突会导致“missing engine / wrong provider”(缺少引擎/错误的提供程序)错误。
有关完整设置和示例项目,请参阅使用 Maven 测试 Kotlin 项目。
如何将 Maven Kotlin 后端升级到 JUnit 6?
Kotlin/JVM 支持最新的稳定 JUnit 版本,包括 JUnit 6。 针对 JUnit 6,请在 pom.xml 中保留相同的 kotlin-test-junit5 依赖项。
升级时,请确保:
- 正确设置了新 JUnit 发布版本所需的基线 Java 版本。
- 所有与 JUnit 相关的依赖项版本保持一致。
- 测试代码中没有已弃用的组件。
有关更多信息,请参阅使用 JUnit 创建测试。
如何分离单元测试和集成测试?
将执行流程拆分给两个插件。对于单元测试,在 test 阶段使用 Surefire 插件。 单元测试请采用 *Test 命名约定。
对于集成测试,在 integration-test 和 verify 阶段使用 Failsafe 插件。 集成测试请采用 *IT 命名约定。
仅运行单元测试时执行 mvn test,两者均运行时执行 mvn verify。
有关更多信息,请参阅使用 Maven 测试 Kotlin 项目。
注解处理:kapt 与 KSP
可以在 Maven 中使用 KSP 吗?
由于 KSP 目前仅对 Gradle 提供官方支持,我们建议所有 Maven 项目都使用 kapt。 你也可以尝试社区提供的 KSP Maven 插件,但它们拥有各自独立的支持和维护流程。
Maven 的另一个选择是在某一构建阶段中通过 KSP 的命令行入口点运行它。这意味着需要将 KSP 代码生成接入 Maven 生命周期:在较早的阶段(如 generate-sources)运行 KSP,并将生成的代码输出到一个稳定的目录中。然后将该目录添加到编译源根目录,并确保代码生成在 Kotlin 编译之前运行,以便在编译代码时生成的源代码已存在。
有关更多信息,请参阅在 Kotlin 项目中使用注解处理器。
在基于 Gradle 的 Kotlin 后端中,何时应选用 kapt,何时选用 KSP?
如果想在 Kotlin Gradle 项目中使用现有的 Java 注解处理器,请先检查 KSP 是否已支持它们。 对于不受支持的处理器,请使用 kapt。
如果想编写自己的注解处理器,请使用 KSP。
有关更多信息,请参阅Kotlin 项目中的注解处理器。
如何配置 kapt?
要在 Kotlin Maven 项目中配置 kapt,请在 compile 执行之前添加一个 kotlin-maven-plugin 的 kapt 目标执行配置,并在 <annotationProcessorPaths> 下显式列出注解处理器。这可以确保生成的源代码在引用它们的代码被编译之前生成。
有关更多信息,请参阅在 Maven 中设置 kapt以及将 kapt 与 MapStruct 结合使用的示例。
为什么 kapt 会在较新的 JDK 上失败?
在将现代 JDK 与 kapt 集成用于 Kotlin 项目时,你可能会遇到“IllegalAccessError”或“InaccessibleObjectException”错误。这可能是由内部包的强封装引起的,而 kapt 在进行注解处理时需要访问这些包。
你可以通过将 Kotlin 更新到最新版本,并在运行 Maven 的 JVM 中添加所需的 --add-opens 参数来解决此问题。
--add-opens 参数通知 JVM 开放某个内部 JDK 包以供深度反射访问,而强封装在默认情况下会阻止这种访问。其格式为 --add-opens <module>/<package>=<target-module>,对于从类路径运行的代码(例如构建工具),<target-module> 通常为 ALL-UNNAMED。例如,要向 kapt 授予其所需的编译器内部访问权限:
--add-opens jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED应用这些参数最简单的方法是将它们添加到项目根目录下的仓库级 .mvn/jvm.config 文件中,每行一个 JVM 参数。Maven 会自动将该文件中的每个选项传递给运行构建的 JVM,从而让每位开发者和 CI 运行器都使用相同的设置。
有关 kapt 配置的更多信息,请参阅 kapt 编译器插件。
kapt 在何处生成源代码以及如何修复其 IDE 导入?
kapt 在模块的 target/ 目录中生成源代码,并将它们添加为源根目录,以便作为构建的一部分参与编译。
如果 IDE 中出现“红色”导入错误,请重新导入你的 Kotlin Maven 项目,以便 IDE 能够识别生成源代码的目录。
有关 kapt 配置的更多信息,请参阅 kapt 编译器插件。
质量门:格式设置与覆盖率
如何强制执行 Kotlin 格式设置检查?
在 pom.xml 构建文件中将 ktlint 的 check 目标绑定到 verify 阶段,这样一旦违反格式设置规则,CI 就会构建失败。 将 format 保留为开发者显式触发的操作。你可以在 .editorconfig 文件中调整格式设置规则。
有关更多信息,请参阅使用 ktlint 进行代码格式设置。 你还可以在项目的质量门中添加 detekt 静态分析。
为什么 Kotlin linter 或格式化程序会在 Java 17+ 上失败?
在 Java 17 及更高版本上使用 Kotlin linter 或格式化程序时,你可能会遇到模块访问错误。
这些工具在 Maven JVM 内部运行,因此在较新的 JDK 上,它们可能需要额外的 --add-opens 参数。每个参数均采用 --add-opens <module>/<package>=ALL-UNNAMED 格式,用于开放内部 JDK 包以供反射访问。将这些参数逐行放入仓库级的 .mvn/jvm.config 文件中,这样相同的设置就会被提交到仓库中,并同时在本地和 CI 中生效。有关更多详细信息,请参阅为什么 kapt 会在较新的 JDK 上失败?。
推荐哪些代码覆盖率工具?
Kover 是 JetBrains 针对 Kotlin 推出的官方覆盖率工具。它能理解 Kotlin 特有的结构,并提供带有内置验证规则的 Maven 插件,因此它是以 Kotlin 为主的项目的首选。
如果已有成熟的 Java 覆盖率流水线和相关报告,另一个选择是使用 JaCoCo。
有关更多信息,请参阅使用 Kover 进行代码覆盖率分析。
如何为多模块项目生成聚合覆盖率报告?
要为 Maven 项目中的所有模块生成覆盖率报告,请从每个模块收集覆盖率数据,并在依赖于其他模块的专用报告模块中进行聚合。通过这种方式,聚合操作会在各个独立模块生成其执行数据之后运行。你可以使用 kover-maven-plugin 来实现该工作流。
有关更多信息,请参阅使用 Kover 进行代码覆盖率分析。
构建应用程序:打包与运行时
如何构建可运行的 JAR 并设置入口点?
要构建可运行的 JAR,需要设置 Main-Class 入口点。它应该是由包含顶级 main() 函数的 Kotlin 文件编译而成的 JVM 类名。例如,Main.kt 文件中的 main() 函数会被编译为 MainKt 类。
通过 maven-jar-plugin 的清单(manifest)配置将该类名设置为 Main-Class 入口点。
有关更多信息,请参阅创建 JAR 文件。
为什么打包好的应用程序会出现主类错误?
在构建应用程序时,尤其是在容器中,你可能会遇到“Could not find or load main class”(找不到或无法加载主类)错误。要排查此问题,请按照以下核对清单进行排查:
- 检查清单中的
Main-Class是否指向正确的已编译类。 - 确保运行的是正确的构件:瘦 JAR 需要在类路径中提供其依赖项,而自包含 JAR 则打包了这些依赖项。
- 检查容器入口点是否使用了正确的
java -jar命令和类路径。
如何将 Kotlin 运行时类一起构建到 Fat JAR 中?
要构建 fat (uber) JAR 并避免缺少 Kotlin 运行时类,请构建一个打包了依赖项的自包含 JAR,并确保 Kotlin 标准库位于运行时类路径中。由于 fat JAR 包含了依赖项,因此将 kotlin-stdlib 声明为依赖项即可确保 Kotlin 运行时被打包在内。
有关更多信息,请参阅创建自包含 JAR 文件。
JVM 参数应该放在哪里?
将用于 Maven 构建过程、测试 JVM 和运行时的 JVM 参数划分到三个不同的位置:
- Maven 构建 JVM:将共享参数放入仓库级的
.mvn/jvm.config文件中。 - 测试 JVM:将它们放置在 Surefire 和 Failsafe 插件的配置部分。
- 运行时:在启动已打包应用程序的容器命令或部署配置中设置它们。
发布库:源代码与签名
发布到 Maven Central 有哪些要求?
要将 Kotlin 库发布到 Maven Central:
准备构件:构建主构件、源码 JAR 和文档 (Javadoc) JAR。
完善 POM 元数据:名称、描述、许可证、开发者和 SCM 信息。
签署构件:以对 CI 友好的方式为每个构件生成 GPG 签名。
部署构件:结合使用
central-publishing-maven-plugin运行mvn deploy,以生成部署包并上传到 Maven Central 进行验证。该插件不会自动生成源码 JAR、Javadoc JAR 或 GPG 签名,因此你需要单独配置这些前置要求。
请注意,Maven Central 的发布版本是不可变的:版本一旦发布,便无法替换。
有关生成文档 JAR 的更多信息,请参阅 Dokka 文档引擎。 有关完整的发布流程和要求,请参阅官方 Sonatype 文档。
如何附加并部署源码 JAR?
要为基于 Maven 的 Kotlin 库附加并部署源码 JAR,请将 maven-source-plugin 绑定到构建生命周期,以便自动附加源码构件并与主构件一起部署。
如果你的项目同时发布多个协同发布的库,建议提供自己的 BOM 文件,以便使用者能够像对齐 Kotlin 构件一样对齐各库的版本。
如何以对 CI 友好的方式为 Maven Central 签署构件?
要以对 CI 友好的方式为 Maven Central 构件进行配置,我们建议:
- 使用
maven-gpg-plugin对项目所有附加的构件进行签名。 - 通过 CI 密钥(secrets)或环境变量提供密钥内容和密码短语,切勿将它们提交到代码库中。
- 确保签名步骤在部署(deploy)步骤之前运行,以便所有发布的构件(包括源码和 Javadoc JAR)都完成签名。
故障排除
如何修复在 JDK 17 上的插件失败问题?
在 JDK 17 上,你可能会遇到 Kotlin Maven 插件执行失败,并收到建议在运行 Maven 的 JVM 中添加 --add-opens 参数的提示。
要在项目级别修复此问题,请将所需的 JVM 参数逐行放入仓库级的 .mvn/jvm.config 文件中,以便每位开发者和 CI 运行器都使用相同的设置,并保持你的 Kotlin 版本为最新。这可以保证本地与 CI 的行为一致。
每个 --add-opens 参数都遵循 --add-opens <module>/<package>=ALL-UNNAMED 格式,用于开放内部 JDK 包以供反射访问。有关更多详细信息,请参阅为什么 kapt 会在较新的 JDK 上失败?。
为什么会出现 Kotlin 或 API 版本不匹配的错误?
你可能会遇到“API version X is no longer supported”(不再支持 API 版本 X)或“module was compiled with an incompatible version of Kotlin”(模块是用不兼容的 Kotlin 版本编译的)错误。它们表明 Kotlin 编译器与类路径上的 Kotlin 库之间存在不匹配。要解决此问题:
- 保持编译器与所有 Kotlin 库使用的版本一致。在
<properties>部分声明一次 Kotlin 版本,使用${kotlin.version}引用它,并使用 Kotlin BOM 文件。 - 移除使用不兼容版本的旧版传递 Kotlin 构件。
- 对照你希望作为目标的 Kotlin 版本,检查
languageVersion和apiVersion。
