[spring-projects/spring-boot]在 Gradle 插件文档中提供 Kotlin 示例以及现有的 Groovy 示例

感谢您的公关。这里有很多好东西，但变化比 #14559 更广泛。我们更喜欢集中问题并尽可能缩小请求范围。这在这里尤其重要，因为提议的更​​改依赖于不同版本的 Gradle 中出现的增强功能。例如，插件块仅在 Gradle 4.9 (IIRC) 中开始支持快照。在 Boot 2.1 中，我们支持 Gradle 4.4 及更高版本，我认为文档最好至少提供适用于该版本的 Groovy 示例。如果这对于 Groovy/Kotlin 选项卡不实用，那么我们可能需要重新考虑。通过更小、更孤立的更改集来做到这一点会更容易。

我们能否退后一步，单独考虑每一块变化？其中一些（例如从 移动compile到，甚至可能属于 2.0.x ）。implementation

哦，抱歉。

所有 groovy 测试都通过 gradle 4.4。但实际上，使用 settings.gradle 中的pluginManagement 内容进行快照仅从 4.10 开始有效。

使用plugins块而不是使用apply来应用插件对于 Kotlin 来说很重要，因为否则插件提供的任何扩展在 DSL 中都不可用。这就是为什么我选择一致使用它：如果不使用插件块应用插件，几乎其他 Kotlin 示例都会失败。

所以也许我可以

• 制作一个单独的 PR，仅删除已弃用配置的使用
• 将此 PR 重新设置为新 PR 的基础（以避免在新 kotlin 示例中使用已弃用的配置）
• 添加说明，说明 Groovy 示例兼容 gradle 4.4 及以上版本，所有 Kotlin 示例兼容 gradle 4.10 及以上版本
• 保留所有示例，除了入门部分的 2 个快照和里程碑示例。对于这些示例，我们可以提供两组示例：一组仅适用于以前的groovy，必须用于4.10以下的gradle版本，另一组是我介绍的可用于4.10及以上版本。

请告诉我你的想法。

我添加了一个提交来显示我的想法。它还修复了我通过过于激进地重构 GradleBuild 而破坏的所有非文档测试（废话！）。

上面四个要点中描述的方法对我来说听起来不错。谢谢。

更改已完成。准备审查。

谢谢。现在情况肯定好多了，但是https://github.com/spring-projects/spring-boot/pull/14585/commits/e9b962ff0ae4ce264d2f8518afb0d909a9e12aae仍然有点太宽泛，无法按原样合并。例如，更改插件类路径看起来像是一件好事，但它与应用文档中的 Kotlin 示例无关。它的当前形式也让我感到困惑，因为有时类路径是在测试中配置的，有时类路径是在构建脚本中配置的。我希望类路径在整个模块中配置一致。你有时间进一步分解吗？我真的很想让这个 PR 中的更改仅集中在添加 Kotlin 示例上。

另外，我想知道是否可以采用基于 Suite 的方法来测试文档中包含的 Groovy 和 Kotlin 示例。这将使它们与集成测试中采用的方法保持一致，该方法GradleCompatibilitySuite用于针对不同版本的 Gradle 运行。该套件将使用.gradle文件和文件来运行测试.gradle.kts，并且无需创建单独的测试类来测试每个示例的两种语言。

插件类路径的改变看起来是一件好事，但它与应用文档中的 Kotlin 示例无关

我认为这里有一个误解。我做这个改变并不是为了改变。我这样做有两个原因（第二个是最重要的）：

• 使用命令式方法应用插件apply()（除非您从父项目使用它以将其应用到子项目）现在被视为遗留（请参阅https://docs.gradle.org/current/userguide/plugins.html#sec：旧插件应用程序）。 Gradle 人员可能比我能更好地解释其基本原理 (ping @eriwen)
• 使用命令式方法应用插件apply()并在 buildScript 块中指定其类路径，并不能以与使用 Groovy DSL 相同的惯用方式使用 Kotlin DSL。

我们举个例子来说明第二点。考虑以下使用 Groovy DSL 的示例：

buildscript {
    dependencies {
        classpath files(pluginClasspath.split(','))
    }
}

apply plugin: 'org.springframework.boot'
apply plugin: 'java'

springBoot {
    buildInfo()
}

这在 Groovy 中工作得很好。在 Kotlin 中做同样的事情是：

buildscript {
    dependencies {
        classpath(files((project.property("pluginClasspath") as String).split(",")))
    }
}

apply(plugin = "org.springframework.boot")
apply(plugin = "java")

springBoot {
    buildInfo()
}

但不幸的是，上面的 Kotlin 构建脚本无法编译。因为该springBoot方法将不存在。仅当从父项目应用将扩展添加到项目的springBootSpring Boot 插件，或者使用块以声明方式应用时，该方法才存在（请参阅https://guides.gradle.org/migration-build -logic-from-groovy-to-kotlin/#applying_plugins）。springBootplugins

这是我使用插件块的主要原因。我当然可以保持常规样本不变，但这会使它们与 Kotlin 等效项不一致，我会觉得这很奇怪和令人困惑。

让我们回到 Kotlin 示例。如果我想使用插件块来应用插件，以便能够使用惯用的 DSL（即springBoot { }而不是一些丑陋的解决方法，如the<SpringBootExtension>().apply { }或configure<SpringBootExtension>() { }），因为我们正在记录的插件版本在插件门户中不存在，我们需要使用TestKit来设置类路径。我们无法从构建脚本中设置它。这就是为什么我在测试中设置它而不是在构建脚本中。

有时在测试中配置类路径，有时在构建脚本中配置类路径

我希望上面的解释足够清楚。 AFAIK，如果我们想以惯用的方式使用 Kotlin DSL，则无法使用构建脚本来设置类路径。因此，我们需要将测试中的类路径应用于 Kotlin 示例。为了保持一致性，所有文档示例（包括 Groovy 文档示例）都使用测试中设置的类路径，并且不再在构建脚本中设置类路径。我可以对项目的所有其他示例执行相同的操作，但更改范围会更广，并且会比文档示例走得更远。所以我对非文档样本保持原样。

我想知道是否可以采用基于 Suite 的方法来测试文档中包含的 Groovy 和 Kotlin 示例。

我会尝试研究一下，看看是否可以做类似的事情。但我不确定我能否在一段时间之前做到这一点：从下周五开始我将休假一周？

关于类路径，我希望上述解释有助于理解为什么我这样做。如果您不相信，请告诉我应该做什么。

仅供参考：整个 Gradle 用户指南（在 Gradle 的夜间版本中）现在在 Groovy 和 Kotlin 示例中一致使用插件块而不是 apply 方法。我提出了一个问题（在 gradle Slack 上讨论之后），以便能够使用插件块来应用与启动插件捆绑在一起的依赖管理插件。

我重构了文档测试以使用套件。

是的，这是正确的@jnizet。非常感谢您在这里的 PR。

我的理解是，为了保持类型安全，Gradle 的 Kotlin DSL 会生成访问器（例如springBoot {}），并且只有在使用块时才可能实现plugins {}。 （我现在希望 Gradle 有一个非常好的资源来解释为什么会这样）。

也许 @wilkinsona 提到的 PR 的其他部分，例如需要拆分为单独 PR 的某些格式。

configure<SpringBootExtension> {}话虽如此，在示例中使用是否是不可取的？无论插件如何应用，这都是一致的。我想这个问题也是针对 @eskatos 的，因为他的团队的工作就是为 Kotlin DSL 树立榜样。

感谢您的额外解释，@jnizet。我不认为存在太大的误解，而且我意识到你不仅仅是为了改变事情而改变事情。

我真正想要的是一组更细粒度的更改。如果某个更改本身具有优点，我希望它至少出现在自己的提交中，甚至可能出现在自己的 PR 中，具体取决于更改的范围。我认为，如果一项改变单独来看是有益的，并且是我们可以单独实现的，那么它就具有个人价值。

那么，我该如何分割这个PR呢？根据您之前的评论，我可以想到以下选项。

• 选项 1：制作第一个 PR，其中类路径不再在 groovy 构建脚本中设置，而是在测试中设置，并且仅对文档示例的构建脚本执行此操作，以避免更改范围过大？
• 选项 2：制作第一个 PR，其中类路径不再在 groovy 构建脚本中设置，而是在测试中设置，并对所有构建脚本（包括非文档构建脚本）执行此操作，以避免出现混淆类路径有时在测试中配置，有时在构建脚本中配置？
• 选项 3：其他（但请详细说明）？

选项 2 对我来说最有意义。这是一个有价值的、孤立的改变，同时也保持了事情的一致性。

酷，谢谢。我会尽快尝试去做。

我制作了一个单独的 PR，它设置了 gradle 运行程序的类路径：#14680。此 PR 已基于 #14680 进行了重新修改。

感谢 #14680 中的更改。我已将它们合并到 master 中。您能否在 master 上重新建立基础并强制推送它，以便它只包含与 Kotlin DSL 示例相关的两个提交？

变基完成@wilkinsona

非常感谢，@jnizet。我已将更改合并到 master 中。如果您想看一下，我在https://github.com/spring-projects/spring-boot/commit/a3d2f3f594377a222935641f06a2a3a1f4cead7e中做了一些调整，主要是为了集中处理 DSL 文件扩展名。

好消息。谢谢。 ？

抛光效果很棒。谢谢你让我知道。

我担心将扩展管理放在 GradleBuild 中会迫使我接触所有非文档测试，但我应该更仔细地查看它们的实现。

我已经可以在https://docs.spring.io/spring-boot/docs/2.1.0.BUILD-SNAPSHOT/gradle-plugin/reference/html/看到这一点。干得好，@jnizet，谢谢！