我如何将 Git 用作契约和存根的存储库？

在多语言世界中，存在不使用二进制存储的编程语言，如 Artifactory 和 Nexus 所采用的方式。从 Spring Cloud Contract 2.0.0 版本开始，我们提供了将契约（contracts）和存根（stubs）存储在 SCM（源代码管理）仓库中的机制。目前，唯一支持的 SCM 是 Git。spring-doc.cadn.net.cn

仓库必须具有以下设置（您可以从此处查看）：spring-doc.cadn.net.cn

.
└── META-INF
    └── com.example
        └── beer-api-producer-git
            └── 0.0.1-SNAPSHOT
                ├── contracts
                │   └── beer-api-consumer
                │       ├── messaging
                │       │   ├── shouldSendAcceptedVerification.groovy
                │       │   └── shouldSendRejectedVerification.groovy
                │       └── rest
                │           ├── shouldGrantABeerIfOldEnough.groovy
                │           └── shouldRejectABeerIfTooYoung.groovy
                └── mappings
                    └── beer-api-consumer
                        └── rest
                            ├── shouldGrantABeerIfOldEnough.json
                            └── shouldRejectABeerIfTooYoung.json

在 META-INF 文件夹下：spring-doc.cadn.net.cn

我们将应用程序按 groupId 分组（例如 com.example）。spring-doc.cadn.net.cn
每个应用程序由其 artifactId 表示（例如，beer-api-producer-git）。spring-doc.cadn.net.cn
接下来，每个应用按其版本进行组织（例如 0.0.1-SNAPSHOT）。从 Spring Cloud Contract 版本 2.1.0 开始，您可以按如下方式指定版本（假设您的版本遵循语义化版本控制）：spring-doc.cadn.net.cn
- + 或 latest：用于查找您存根（stubs）的最新版本（假设快照版本始终是给定修订号的最新构件）。这意味着：spring-doc.cadn.net.cn
  - 如果您有 1.0.0.RELEASE、2.0.0.BUILD-SNAPSHOT 和 2.0.0.RELEASE，我们假定最新的为 2.0.0.BUILD-SNAPSHOT。spring-doc.cadn.net.cn
  - 如果您有 1.0.0.RELEASE 和 2.0.0.RELEASE，我们假设最新的是 2.0.0.RELEASE。spring-doc.cadn.net.cn
  - 如果您有一个名为 latest 或 + 的版本，我们将选择该文件夹。spring-doc.cadn.net.cn
- release: 用于查找您的存根（stubs）的最新发布版本。这意味着：spring-doc.cadn.net.cn
  - 如果您有 1.0.0.RELEASE、2.0.0.BUILD-SNAPSHOT 和 2.0.0.RELEASE，我们假定最新的是 2.0.0.RELEASE。spring-doc.cadn.net.cn
  - 如果您有一个名为 release 的版本，我们将选择该文件夹。spring-doc.cadn.net.cn

最后，还有两个文件夹：spring-doc.cadn.net.cn

contracts: 最佳实践是将每个消费者所需的契约存储在以消费者名称命名的文件夹中（例如 beer-api-consumer）。这样，您就可以使用 stubs-per-consumer 功能。后续的目录结构是任意的。spring-doc.cadn.net.cn
mappings: Maven 或 Gradle Spring Cloud Contract 插件将存根服务器映射推送到此文件夹。在消费者端，Stub Runner 会扫描此文件夹以启动带有存根定义的存根服务器。该文件夹结构是复制了在 contracts 子文件夹中创建的结构。spring-doc.cadn.net.cn

协议约定

要控制契约的来源类型和位置（是二进制存储还是 SCM 仓库），您可使用仓库 URL 中的协议。Spring Cloud Contract 会遍历已注册的协议解析器，并尝试通过插件获取契约（contract），或从 Stub Runner 获取存根（stubs）。spring-doc.cadn.net.cn

对于 SCM 功能，目前我们支持 Git 仓库。要使用它，在需要放置仓库 URL 的属性中，您必须在连接 URL 前加上 git://。以下列表展示了一些示例：spring-doc.cadn.net.cn

git://file:///foo/bar
git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git
git://[email protected]:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git

生产者

对于生产者而言，若要使用 SCM（源代码管理）方法，我们可以复用用于外部契约的相同机制。我们通过将 Spring Cloud Contract 配置为使用从以 git:// 协议开头的 URL 获取的 SCM 实现来实现这一点。spring-doc.cadn.net.cn

您必须手动在 Maven 中添加 pushStubsToScm 目标，或在 Gradle 中使用（绑定）pushStubsToScm 任务。我们不会将存根推送到您 Git 仓库的 origin 中。

以下列表包含了Maven和Gradle构建文件中的相关部分：spring-doc.cadn.net.cn

Maven

<plugin>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-contract-maven-plugin</artifactId>
    <version>${spring-cloud-contract.version}</version>
    <extensions>true</extensions>
    <configuration>
        <!-- Base class mappings etc. -->

        <!-- We want to pick contracts from a Git repository -->
        <contractsRepositoryUrl>git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git</contractsRepositoryUrl>

        <!-- We reuse the contract dependency section to set up the path
        to the folder that contains the contract definitions. In our case the
        path will be /groupId/artifactId/version/contracts -->
        <contractDependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>${project.artifactId}</artifactId>
            <version>${project.version}</version>
        </contractDependency>

        <!-- The contracts mode can't be classpath -->
        <contractsMode>REMOTE</contractsMode>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <!-- By default we will not push the stubs back to SCM,
                you have to explicitly add it as a goal -->
                <goal>pushStubsToScm</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Gradle

contracts {
	// We want to pick contracts from a Git repository
	contractDependency {
		stringNotation = "${project.group}:${project.name}:${project.version}"
	}
	/*
	We reuse the contract dependency section to set up the path
	to the folder that contains the contract definitions. In our case the
	path will be /groupId/artifactId/version/contracts
	 */
	contractRepository {
		repositoryUrl = "git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git"
	}
	// The mode can't be classpath
	contractsMode = "REMOTE"
	// Base class mappings etc.
}

/*
In this scenario we want to publish stubs to SCM whenever
the `publish` task is invoked
*/
publish.dependsOn("publishStubsToScm")

您还可以进一步自定义 publishStubsToScm Gradle 任务。在以下示例中，该任务被配置为从本地 Git 仓库中选取契约：spring-doc.cadn.net.cn

Gradle

publishStubsToScm {
	// We want to modify the default set up of the plugin when publish stubs to scm is called
	// We want to pick contracts from a Git repository
	contractDependency {
		stringNotation = "${project.group}:${project.name}:${project.version}"
	}
	/*
	We reuse the contract dependency section to set up the path
	to the folder that contains the contract definitions. In our case the
	path will be /groupId/artifactId/version/contracts
	 */
	contractRepository {
		repositoryUrl = "git://file://${new File(project.rootDir, "../target")}/contract_empty_git/"
	}
	// We set the contracts mode to `LOCAL`
	contractsMode = "LOCAL"
	}

重要: 从 2.3.0.RELEASE 开始，先前用于 publishStubsToScm 自定义的 customize{} 闭包已不再可用。设置应直接在 publishStubsToScm 闭包内应用，如前面示例所示。spring-doc.cadn.net.cn

采用这种配置：spring-doc.cadn.net.cn

一个 git 项目被克隆到临时目录spring-doc.cadn.net.cn
SCM 存根下载器会前往 META-INF/groupId/artifactId/version/contracts 文件夹以查找合约。例如，对于 com.example:foo:1.0.0，路径将为 META-INF/com.example/foo/1.0.0/contracts。spring-doc.cadn.net.cn
测试由契约生成。spring-doc.cadn.net.cn
存根是从契约中生成的。spring-doc.cadn.net.cn
测试通过后，存根将提交到克隆的仓库中。spring-doc.cadn.net.cn
最后，向该仓库的 origin 发送了一次推送。spring-doc.cadn.net.cn

本地存储契约的生产者

另一种将 SCM 用作存根和契约目标的方法是，将契约本地存储在生产者（producer）端，仅将契约和存根推送到 SCM。以下项目展示了如何使用 Maven 和 Gradle 实现此设置。spring-doc.cadn.net.cn

采用这种配置：spring-doc.cadn.net.cn

默认 src/test/resources/contracts 目录中的契约将被选取。spring-doc.cadn.net.cn
测试由契约生成。spring-doc.cadn.net.cn
存根是从契约中生成的。spring-doc.cadn.net.cn
一旦测试通过：spring-doc.cadn.net.cn
- git 项目被克隆到一个临时目录。spring-doc.cadn.net.cn
- 存根和契约已提交到克隆的仓库中。spring-doc.cadn.net.cn
最后，将一次推送操作执行到该仓库的 origin 分支上。spring-doc.cadn.net.cn

将合约与生产者及存根保存在外部仓库中

您还可以将契约保留在生产者仓库中，但将存根存储在外部 Git 仓库中。这在您希望使用基础的消费者-生产者协作流程，但无法使用构件仓库来存储存根时最为有用。spring-doc.cadn.net.cn

为此，请使用常规的生产者设置，然后添加 pushStubsToScm 目标，并将 contractsRepositoryUrl 设置为存放存根的仓库。spring-doc.cadn.net.cn

消费者

在消费者端，当通过 repositoryRoot 参数传递时，该参数可来自 @AutoConfigureStubRunner 注解、JUnit 4 规则、JUnit 5 扩展或属性配置，您可将带有 git:// 协议前缀的 SCM 仓库 URL 作为参数传入。以下示例展示了如何操作：spring-doc.cadn.net.cn

@AutoConfigureStubRunner(
    stubsMode="REMOTE",
    repositoryRoot="git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git",
    ids="com.example:bookstore:0.0.1.RELEASE"
)

采用这种配置：spring-doc.cadn.net.cn

git 项目被克隆到一个临时目录。spring-doc.cadn.net.cn
SCM 存根下载器会前往 META-INF/groupId/artifactId/version/ 文件夹以查找存根定义和契约。例如，对于 com.example:foo:1.0.0，路径将是 META-INF/com.example/foo/1.0.0/。spring-doc.cadn.net.cn
存根服务器已启动并加载了映射数据。spring-doc.cadn.net.cn
消息定义在消息测试中被读取并使用。spring-doc.cadn.net.cn