使用 Spring Cloud Contract

1. 在 Nexus 或 Artifactory 中使用存根进行提供者契约测试

您可以查看 开发您的第一个基于 Spring Cloud Contract 的应用 链接,以了解在 Nexus 或 Artifactory 流程中使用存根进行提供方契约测试。spring-doc.cadn.net.cn

您还可以查看 工作坊页面,获取逐步操作指南,了解如何完成此流程。spring-doc.cadn.net.cn

2. 使用 Git 中的存根进行提供者契约测试

在此流程中,我们执行提供者契约测试(生产者并不了解消费者如何使用其API)。存根被上传到一个独立的仓库(它们不会上传至Artifactory或Nexus)。spring-doc.cadn.net.cn

2.1. 前提条件

在使用 git 中的存根测试提供者契约之前,您必须提供一个包含每个生产者所有存根的 git 仓库。有关此类项目的示例,请参见 此示例此示例。将存根推送到该仓库后,仓库将具有以下结构:spring-doc.cadn.net.cn

$ tree .
└── META-INF
   └── folder.with.group.id.as.its.name
       └── folder-with-artifact-id
           └── folder-with-version
               ├── contractA.groovy
               ├── contractB.yml
               └── contractC.groovy

您还必须提供已配置 Spring Cloud Contract Stub Runner 的消费者代码。有关此类项目的示例,请参见 此示例,并搜索包含 BeerControllerGitTest 的测试。您还必须提供已配置 Spring Cloud Contract 的生产者代码,以及相应的插件。有关此类项目的示例,请参见 此示例spring-doc.cadn.net.cn

2.2. The Flow

流程看起来完全就像在 开始构建第一个基于Spring Cloud Contract的应用程序 中所展示的一样,只是Stub Storage的实现是一个git仓库。spring-doc.cadn.net.cn

您可以阅读更多关于设置 git 仓库以及消费者和生产者一侧的How To 页面的文档。spring-doc.cadn.net.cn

2.3.Consumer设置

为了从 Git 仓库而非 Nexus 或 Artifactory 获取存根(stubs),您需要在 Stub Runner 的 repositoryRoot 属性的 URL 中使用 git 协议。以下示例展示了如何进行配置:spring-doc.cadn.net.cn

注解
@AutoConfigureStubRunner(
stubsMode = StubRunnerProperties.StubsMode.REMOTE,
        repositoryRoot = "git://[email protected]:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git",
        ids = "com.example:artifact-id:0.0.1")
JUnit 4 规则
@Rule
    public StubRunnerRule rule = new StubRunnerRule()
            .downloadStub("com.example","artifact-id", "0.0.1")
            .repoRoot("git://[email protected]:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git")
            .stubsMode(StubRunnerProperties.StubsMode.REMOTE);
JUnit 5 扩展
@RegisterExtension
    public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension()
            .downloadStub("com.example","artifact-id", "0.0.1")
            .repoRoot("git://[email protected]:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git")
            .stubsMode(StubRunnerProperties.StubsMode.REMOTE);

2.4. 设置生产者

若要将桩推送到 Git 仓库而不是 Nexus 或 Artifactory,则需要在插件设置的 URL 中使用 git 协议。此外,您还需要明确告知插件在构建过程结束时推送桩。下面的例子展示了如何操作: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://git://[email protected]: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://git://[email protected]: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 executed
*/
publish.dependsOn("publishStubsToScm")

您可以在文档的如何设置页面中了解有关设置git存储库的更多信息。spring-doc.cadn.net.cn

与外部存储库中的契约一起驱动消费者驱动的契约

在此流程中,我们执行消费者驱动契约测试。契约定义存储在单独的仓库中。spring-doc.cadn.net.cn

查看工作坊页面,了解如何执行此流程的逐步说明。spring-doc.cadn.net.cn

4.1.前提条件

要使用消费者驱动的契约(consumer-driven contracts),并将契约存储在外部仓库中,您需要设置一个 Git 仓库,其内容如下:spring-doc.cadn.net.cn

有关更多信息,请参阅如何部分,其中我们描述了如何设置此类存储库。对于此类项目的示例,请参见此示例spring-doc.cadn.net.cn

您还需要设置有 Spring Cloud Contract Stub Runner 的消费者代码。 对于此类项目的示例,请参见 这个示例。 您还需要设置有 Spring Cloud Contract 及其插件的生产者代码。 对于此类项目的示例,请参见 这个示例。 存档存储是 Nexus 或 Artifactoryspring-doc.cadn.net.cn

从高层来看,流程如下:<br/>spring-doc.cadn.net.cn

  1. 消费者使用来自独立仓库的合同定义spring-doc.cadn.net.cn

  2. 消费者完成工作后,在其侧分支上创建包含有效代码的分支,并向单独存储契约定义的仓库发出拉取请求。spring-doc.cadn.net.cn

  3. 生产者接管拉取请求,将其提交到包含契约定义的独立仓库,并将包含所有契约的JAR本地安装。spring-doc.cadn.net.cn

  4. 生产者从本地存储的JAR文件中生成测试用例,并编写缺失的实现代码,以使测试通过。spring-doc.cadn.net.cn

  5. 一旦生产者的工作完成,对包含合同定义的仓库的拉取请求将被合并。spring-doc.cadn.net.cn

  6. 经过CI工具使用契约定义构建存储库后,契约定义JAR文件将被上传到Nexus或Artifactory。生产者可以合并其分支。spring-doc.cadn.net.cn

  7. 最终,消费者可以切换到在线工作,从远程位置获取生产者的存档,并将分支合并到主分支。spring-doc.cadn.net.cn

4.2. 消费者流

  1. 在生产者发送请求时,写一个测试来捕获该请求。spring-doc.cadn.net.cn

    测试失败,因为没有服务器存在。spring-doc.cadn.net.cn

  2. 克隆包含契约定义的仓库。spring-doc.cadn.net.cn

  3. 在生产者文件夹下,以消费者名称作为子文件夹,设置要求为合同。spring-doc.cadn.net.cn

    例如,对于名为producer的生产者和名为consumer的使用者,这些合同将存储在src/main/resources/contracts/producer/consumer/)下spring-doc.cadn.net.cn

  4. 一旦定义了合同,就会将生产者存档安装到本地存储,如下例所示:spring-doc.cadn.net.cn

    $ cd src/main/resource/contracts/producer
    $ ./mvnw clean install
  5. 为使用者测试设置Spring Cloud Contract (SCC) Stub Runner,以执行以下操作:spring-doc.cadn.net.cn

下图显示了以下 UML 图中显示的消费流:spring-doc.cadn.net.cn

flow overview consumer cdc external consumer

4.3 产者流程

The producer:spring-doc.cadn.net.cn

  1. 接管具有合同定义的仓库的拉取请求。你可以从命令行进行,如下所示spring-doc.cadn.net.cn

    $ git checkout -b the_branch_with_pull_request master
    git pull https://github.com/user_id/project_name.git the_branch_with_pull_request
  2. 安装合同定义,如下所示spring-doc.cadn.net.cn

    $ ./mvnw clean install
  3. 设置插件从 JAR 文件而不是从 src/test/resources/contracts 中获取合同定义,方法如下: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>
            <!-- We want to use the JAR with contracts with the following coordinates -->
            <contractDependency>
                <groupId>com.example</groupId>
                <artifactId>beer-contracts</artifactId>
            </contractDependency>
            <!-- The JAR with contracts should be taken from Maven local -->
            <contractsMode>LOCAL</contractsMode>
            <!-- ... additional configuration -->
        </configuration>
    </plugin>
    Gradle
    contracts {
        // We want to use the JAR with contracts with the following coordinates
        // group id `com.example`, artifact id `beer-contracts`, LATEST version and NO classifier
        contractDependency {
            stringNotation = 'com.example:beer-contracts:+:'
        }
        // The JAR with contracts should be taken from Maven local
        contractsMode = "LOCAL"
        // Additional configuration
    }
  4. 运行构建以生成测试和占位代码,如下:spring-doc.cadn.net.cn

    Maven
    ./mvnw clean install
    Gradle
    ./gradlew clean build
  5. 编写缺失的实现,使测试通过。spring-doc.cadn.net.cn

  6. 合并包含协定定义的存储库中的拉取请求,如下所示:spring-doc.cadn.net.cn

    $ git commit -am "Finished the implementation to make the contract tests pass"
    $ git checkout master
    $ git merge --no-ff the_branch_with_pull_request
    $ git push origin master
  7. CI 系统使用契约定义构建项目,然后将包含契约定义的 JAR 文件上传到 Nexus 或 Artifactory。spring-doc.cadn.net.cn

  8. 切换到远程工作。spring-doc.cadn.net.cn

  9. 设置了插件,以便不再从本地存储中获取合同定义,而是从远程位置获取,如下所示: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>
            <!-- We want to use the JAR with contracts with the following coordinates -->
            <contractDependency>
                <groupId>com.example</groupId>
                <artifactId>beer-contracts</artifactId>
            </contractDependency>
            <!-- The JAR with contracts should be taken from a remote location -->
            <contractsMode>REMOTE</contractsMode>
            <!-- ... additional configuration -->
        </configuration>
    </plugin>
    Gradle
    contracts {
        // We want to use the JAR with contracts with the following coordinates
        // group id `com.example`, artifact id `beer-contracts`, LATEST version and NO classifier
        contractDependency {
            stringNotation = 'com.example:beer-contracts:+:'
        }
        // The JAR with contracts should be taken from a remote location
        contractsMode = "REMOTE"
        // Additional configuration
    }
  10. 将生产者代码与新实现合并。spring-doc.cadn.net.cn

  11. 系统是:spring-doc.cadn.net.cn

下面的UML图显示了生产者过程:spring-doc.cadn.net.cn

flow overview consumer cdc external producer

5. 使用推送到 Git 的生产者端契约的消费者驱动契约

您可以查看逐步指南,了解消费者驱动契约(CDC),其中契约位于生产者端,以了解在生产者端设置契约的消费者驱动契约流程。spring-doc.cadn.net.cn

存档存储实现是git仓库。我们将在描述提供者契约测试中存档的git设置部分。spring-doc.cadn.net.cn

您可以在文档的使用指南页面中找到更多关于为消费者和生产者端设置git存储库的信息。spring-doc.cadn.net.cn

6. 非Spring应用程序在Artifactory中使用存根进行提供者契约测试

6.1. 流程

您可以查看开发基于Spring Cloud Contract的首个应用,了解如何使用Nexus或Artifactory中的存根进行提供者契约测试。spring-doc.cadn.net.cn

6.2. 设置消费者

对于消费者端,您可以使用JUnit规则。这样,您不必启动Spring上下文。下面的列表显示了这样的规则(在JUnit4和JUnit5中);spring-doc.cadn.net.cn

JUnit 4 规则
@Rule
    public StubRunnerRule rule = new StubRunnerRule()
            .downloadStub("com.example","artifact-id", "0.0.1")
            .repoRoot("git://[email protected]:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git")
            .stubsMode(StubRunnerProperties.StubsMode.REMOTE);
JUnit 5 扩展
@Rule
    public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension()
            .downloadStub("com.example","artifact-id", "0.0.1")
            .repoRoot("git://[email protected]:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git")
            .stubsMode(StubRunnerProperties.StubsMode.REMOTE);

6.3. 设置生产者

默认情况下,Spring Cloud Contract 插件为生成的测试使用 Rest Assured 的 MockMvc 设置。由于非 Spring 应用不使用 MockMvc,您可以将 testMode 更改为 EXPLICIT,以向在特定端口上绑定的应用程序发送真实请求。spring-doc.cadn.net.cn

在本示例中,我们使用一个名为 Javalin 的框架来启动一个非 Spring HTTP 服务器。spring-doc.cadn.net.cn

假设我们有以下应用程序:spring-doc.cadn.net.cn

package com.example.demo;

import io.javalin.Javalin;

public class DemoApplication {

    public static void main(String[] args) {
        new DemoApplication().run(7000);
    }

    public Javalin start(int port) {
        return Javalin.create().start(port);
    }

    public Javalin registerGet(Javalin app) {
        return app.get("/", ctx -> ctx.result("Hello World"));
    }

    public Javalin run(int port) {
        return registerGet(start(port));
    }

}

鉴于该应用程序,我们可以设置插件以使用 EXPLICIT 模式(即向真实端口发送请求),如下所示: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>
        <baseClassForTests>com.example.demo.BaseClass</baseClassForTests>
        <!-- This will setup the EXPLICIT mode for the tests -->
        <testMode>EXPLICIT</testMode>
    </configuration>
</plugin>
Gradle
contracts {
    // This will setup the EXPLICIT mode for the tests
    testMode = "EXPLICIT"
    baseClassForTests = "com.example.demo.BaseClass"
}

基类可能类似于以下内容:spring-doc.cadn.net.cn

import io.javalin.Javalin;
import io.restassured.RestAssured;
import org.junit.After;
import org.junit.Before;
import org.springframework.util.SocketUtils;

public class BaseClass {

    Javalin app;

    @Before
    public void setup() {
        // pick a random port
        int port = SocketUtils.findAvailableTcpPort();
        // start the application at a random port
        this.app = start(port);
        // tell Rest Assured where the started application is
        RestAssured.baseURI = "http://localhost:" + port;
    }

    @After
    public void close() {
        // stop the server after each test
        this.app.stop();
    }

    private Javalin start(int port) {
        // reuse the production logic to start a server
        return new DemoApplication().run(port);
    }
}

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

7. 在非JVM世界中使用Artifactory中的存根进行提供者契约测试

在此流程中,我们假设:spring-doc.cadn.net.cn

您可以在此页面上了解有关如何使用Spring Cloud Contract与Docker的更多信息spring-doc.cadn.net.cn

这里,您可以阅读一篇关于如何在多语言环境中使用 Spring Cloud Contract 的博客文章。spring-doc.cadn.net.cn

这里,您可以找到一个使用 Spring Cloud Contract 作为生产者和消费者的 NodeJS 应用程序示例。spring-doc.cadn.net.cn

7.1 生产者流程

从高层次来看,生产者:spring-doc.cadn.net.cn

  1. 编写契约定义(例如,使用 YAML 格式)。spring-doc.cadn.net.cn

  2. 设置构建工具以:spring-doc.cadn.net.cn

    1. 启动在给定端口上使用模拟服务的应用程序。spring-doc.cadn.net.cn

      如果无法进行模拟,您可以设置基础设施并在状态化方式下定义测试。spring-doc.cadn.net.cn

    2. 运行 Spring Cloud Contract Docker 映像,并将正在运行的应用程序的端口作为环境变量传递。spring-doc.cadn.net.cn

SCC Docker镜像:<ul><li>从挂载的卷生成测试。</li><li>针对正在运行的应用程序运行测试。</li></ul>spring-doc.cadn.net.cn

在测试完成之后,存档会被上传到存档仓库(例如Artifactory或Git)。<br>spring-doc.cadn.net.cn

以下UML图显示了生产者流程:spring-doc.cadn.net.cn

flows provider non jvm producer

7.2. 消费者流程

从高层来看,用户:spring-doc.cadn.net.cn

  1. 设置构建工具以:spring-doc.cadn.net.cn

  2. 针对正在运行的存根运行应用程序测试。spring-doc.cadn.net.cn

下图显示了以下 UML 图中显示的消费流:spring-doc.cadn.net.cn

flows provider non jvm consumer

8. 使用 REST Docs 和 Nexus 或 Artifactory 中的存根进行提供者契约测试

在此流程中,我们不使用 Spring Cloud Contract 插件来生成测试和存根。我们编写 Spring RESTDocs,并从中自动生成存根。最后,我们将构建设置为打包存根并将它们上传到存根存储站点——在我们的例子中是 Nexus 或 Artifactory。spring-doc.cadn.net.cn

参见研讨会页面,了解如何使用此流程的分步说明。spring-doc.cadn.net.cn

8.1. 生产者流程

作为生产商,我们:spring-doc.cadn.net.cn

  1. 我们编写API的RESTDocs测试。spring-doc.cadn.net.cn

  2. 我们将 Spring Cloud Contract Stub Runner starter 添加到我们的构建中(spring-cloud-starter-contract-stub-runner),如下所示spring-doc.cadn.net.cn

    Maven
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-contract-stub-runner</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    Gradle
    dependencies {
        testImplementation 'org.springframework.cloud:spring-cloud-starter-contract-stub-runner'
    }
    
    dependencyManagement {
        imports {
            mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
        }
    }
  3. 我们设置构建工具来打包我们的存根,如下所示:spring-doc.cadn.net.cn

    Maven
    <!-- pom.xml -->
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <executions>
                <execution>
                    <id>stub</id>
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>single</goal>
                    </goals>
                    <inherited>false</inherited>
                    <configuration>
                        <attach>true</attach>
                        <descriptors>
                            ${basedir}/src/assembly/stub.xml
                        </descriptors>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
    
    <!-- src/assembly/stub.xml -->
    <assembly
        xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
        <id>stubs</id>
        <formats>
            <format>jar</format>
        </formats>
        <includeBaseDirectory>false</includeBaseDirectory>
        <fileSets>
            <fileSet>
                <directory>${project.build.directory}/generated-snippets/stubs</directory>
                <outputDirectory>META-INF/${project.groupId}/${project.artifactId}/${project.version}/mappings</outputDirectory>
                <includes>
                    <include>**/*</include>
                </includes>
            </fileSet>
        </fileSets>
    </assembly>
    Gradle
    task stubsJar(type: Jar) {
        classifier = "stubs"
        into("META-INF/${project.group}/${project.name}/${project.version}/mappings") {
            include('**/*.*')
            from("${project.buildDir}/generated-snippets/stubs")
        }
    }
    // we need the tests to pass to build the stub jar
    stubsJar.dependsOn(test)
    bootJar.dependsOn(stubsJar)

现在,当我们运行测试时,存根会自动发布并打包。spring-doc.cadn.net.cn

以下UML图显示了生产者流程:spring-doc.cadn.net.cn

flows provider rest docs producer

8.2. 消费者流程

由于消费者流程不受生成桩工具的影响,因此您可以查看开发您的第一个基于Spring Cloud Contract的应用程序,了解在Nexus或Artifactory中使用桩进行提供者合同测试时消费者的流程。spring-doc.cadn.net.cn

9. 接下来阅读什么

你现在应该已经了解了如何使用 Spring Cloud Contract 和一些你应该遵循的最佳实践。你可以继续学习有关特定Spring Cloud Contract 功能,或者跳过并阅读关于 Spring Cloud Contract 高级功能spring-doc.cadn.net.cn