A Three-second Tour

此非常简短的教程介绍了如何使用 Spring Cloud Contract。它包括以下主题：

This very brief tour walks through using Spring Cloud Contract. It consists of the following topics:

您可在 here 中找到更详尽的教程。

You can find a somewhat longer tour here.

以下 UML 图显示了 Spring Cloud Contract 中各部分之间的关系：

The following UML diagram shows the relationship of the parts within Spring Cloud Contract:

"API Producer"->"API Producer": add Spring Cloud \nContract (SCC) plugin
"API Producer"->"API Producer": add SCC Verifier dependency
"API Producer"->"API Producer": define contracts
"API Producer"->"Build": run build
"Build"->"SCC Plugin": generate \ntests, stubs and stubs \nartifact (e.g. stubs-jar)
"Build"->"Stub Storage": upload contracts \nand stubs and the project arifact
"Build"->"API Producer": Build successful
"API Consumer"->"API Consumer": add SCC Stub Runner \ndependency
"API Consumer"->"API Consumer": write a SCC Stub Runner \nbased contract test
"SCC Stub Runner"->"Stub Storage": test asks for [API Producer] stubs
"Stub Storage"->"SCC Stub Runner": fetch the [API Producer] stubs
"SCC Stub Runner"->"SCC Stub Runner": run in memory\n HTTP server stubs
"API Consumer"->"SCC Stub Runner": send a request \nto the HTTP server stub
"SCC Stub Runner"->"API Consumer": communication is correct

On the Producer Side

要开始使用 Spring Cloud Contract，您可以将用 Groovy DSL 或 YAML 表示的 REST 或消息契约文件添加到契约目录中，该目录由 contractsDslDir 属性设置。默认情况下，它是 $rootDir/src/test/resources/contracts。

To start working with Spring Cloud Contract, you can add files with REST or messaging contracts expressed in either Groovy DSL or YAML to the contracts directory, which is set by the contractsDslDir property. By default, it is $rootDir/src/test/resources/contracts.

然后您可以将 Spring Cloud Contract Verifier 依赖项和插件添加到您的构建文件中，如下例所示：

Then you can add the Spring Cloud Contract Verifier dependency and plugin to your build file, as the following example shows:

Unresolved directive in three-second-tour.adoc - include::{samples_path}/standalone/dsl/http-server/pom.xml[]

以下清单显示了如何添加插件，该插件应位于文件的 build/plugin 部分：

The following listing shows how to add the plugin, which should go in the build/plugins portion of the file:

<plugin>
	<groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-contract-maven-plugin</artifactId>
	<version>${spring-cloud-contract.version}</version>
	<extensions>true</extensions>
</plugin>

运行 ./mvnw clean install 将自动生成测试，以验证应用程序是否符合添加的合同。默认情况下，测试会生成在 org.springframework.cloud.contract.verifier.tests. 下。

Running ./mvnw clean install automatically generates tests that verify the application compliance with the added contracts. By default, the tests get generated under org.springframework.cloud.contract.verifier.tests..

由于尚未实现由合同描述的功能，因此测试失败。

As the implementation of the functionalities described by the contracts is not yet present, the tests fail.

要通过它们，必须添加正确实现的 HTTP 请求或消息处理。此外，必须为自动生成的测试向项目添加一个基本测试类。这个类由所有自动生成的测试扩展，它应包含运行它们所需的所有设置信息（例如 RestAssuredMockMvc 控制器设置或消息测试设置）。

To make them pass, you must add the correct implementation of either handling HTTP requests or messages. Also, you must add a base test class for auto-generated tests to the project. This class is extended by all the auto-generated tests, and it should contain all the setup information necessary to run them (for example RestAssuredMockMvc controller setup or messaging test setup).

以下示例来自 pom.xml，展示了如何指定基本测试类：

The following example, from pom.xml, shows how to specify the base test class:

<build>
        <plugins>
            <plugin>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-contract-maven-plugin</artifactId>
                <version>2.1.2.RELEASE</version>
                <extensions>true</extensions>
                <configuration>
                    <baseClassForTests>com.example.contractTest.BaseTestClass</baseClassForTests> 1
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
1 The baseClassForTests element lets you specify your base test class. It must be a child of a configuration element within spring-cloud-contract-maven-plugin.

一旦实现和测试基类就位，则测试通过，并且应用程序和存根工件在本地 Maven 存储库中构建并安装。您现在可以合并更改，并且可以将应用程序和存根工件发布到在线存储库中。

Once the implementation and the test base class are in place, the tests pass, and both the application and the stub artifacts are built and installed in the local Maven repository. You can now merge the changes, and you can publish both the application and the stub artifacts in an online repository.

On the Consumer Side

您可以在集成测试中使用 Spring Cloud Contract Stub Runner 获得正在运行的 WireMock 实例或模拟实际服务的邮件路由。

You can use Spring Cloud Contract Stub Runner in the integration tests to get a running WireMock instance or messaging route that simulates the actual service.

若要执行此操作，添加对 Spring Cloud Contract Stub Runner 的依赖项，如下例所示：

To do so, add the dependency to Spring Cloud Contract Stub Runner, as the following example shows:

Unresolved directive in three-second-tour.adoc - include::{samples_path}/standalone/dsl/http-client/pom.xml[]

您可以采用两种方式之一在您的 Maven 存储库中安装 Producer 端存根：

You can get the Producer-side stubs installed in your Maven repository in either of two ways:

  • By checking out the Producer side repository and adding contracts and generating the stubs by running the following commands:[source, bash]

$ cd local-http-server-repo
$ ./mvnw clean install -DskipTests

测试被跳过，因为生产者端合约实现尚未到位，因此导致自动生成的合约测试失败。

The tests are being skipped because the producer-side contract implementation is not in place yet, so the automatically-generated contract tests fail.

  • By getting already-existing producer service stubs from a remote repository. To do so, pass the stub artifact IDs and artifact repository URL as Spring Cloud Contract Stub Runner properties, as the following example shows:[source, yaml]

Unresolved directive in three-second-tour.adoc - include::{samples_path}/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]

现在您可以使用 @AutoConfigureStubRunner 批注您的测试类。在批注中，提供 Spring Cloud Contract Stub Runner 的 group-id 和 artifact-id 值，以便为您运行协作者的存根，如下例所示：

Now you can annotate your test class with @AutoConfigureStubRunner. In the annotation, provide the group-id and artifact-id values for Spring Cloud Contract Stub Runner to run the collaborators' stubs for you, as the following example shows:

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment=WebEnvironment.NONE)
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"},
		stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class LoanApplicationServiceTests {
	. . .
}

在线储存库中下载存根时，请使用 REMOTE stubsMode，而离线工作时则使 LOCAL。

Use the REMOTE stubsMode when downloading stubs from an online repository and LOCAL for offline work.

现在，在您的集成测试中，您可以收到预期由协作服务发出的 HTTP 响应或消息的存根版本。

Now, in your integration test, you can receive stubbed versions of HTTP responses or messages that are expected to be emitted by the collaborator service.