Common Top-Level Elements

以下部分介绍最常见的顶级元素：

The following sections describe the most common top-level elements:

Description

可以向合同中添加 description。说明为任意文本。以下代码显示一个示例：

You can add a description to your contract. The description is arbitrary text. The following code shows an example:

Groovy
Unresolved directive in common-top-elements.adoc - include::{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[]
YAML
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/yml/contract_rest.yml[]
Java
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[]
Kotlin
Unresolved directive in common-top-elements.adoc - include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[]

Name

可以为合同提供一个名称。假设你提供以下名称：should register a user。如果你这样做，自动生成测试的名称为 validate_should_register_a_user。此外，WireMock 存根中存根的名称为 should_register_a_user.json。

You can provide a name for your contract. Assume that you provide the following name: should register a user. If you do so, the name of the autogenerated test is validate_should_register_a_user. Also, the name of the stub in a WireMock stub is should_register_a_user.json.

您必须确保该名称不包含让生成的测试无法编译的任何字符。另外，请记住，如果您对多个合约提供相同的名称，则自动生成的测试将无法编译，而生成的存根将相互覆盖。

You must ensure that the name does not contain any characters that make the generated test not compile. Also, remember that, if you provide the same name for multiple contracts, your autogenerated tests fail to compile and your generated stubs override each other.

以下示例显示如何向合同中添加名称：

The following example shows how to add a name to a contract:

Groovy
Unresolved directive in common-top-elements.adoc - include::{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[]
YAML
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/yml/contract.yml[]
Java
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[]
Kotlin
Unresolved directive in common-top-elements.adoc - include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[]

Ignoring Contracts

如果要忽略合同，则可以在插件配置中设置一个忽略的合同的值，或在合同本身上设置 ignored 属性。以下示例显示如何执行此操作：

If you want to ignore a contract, you can either set a value for ignored contracts in the plugin configuration or set the ignored property on the contract itself. The following example shows how to do so:

Groovy
Unresolved directive in common-top-elements.adoc - include::{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[]
YAML
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/yml/contract.yml[]
Java
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[]
Kotlin
Unresolved directive in common-top-elements.adoc - include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[]

Contracts in Progress

正在进行的合同不会在生产者一侧生成测试，但允许生成存根。

A contract in progress does not generate tests on the producer side but does allow generation of stubs.

请谨慎使用该功能，因为它可能导致误报，因为您在没有实际拥有可用实现时为您的消费者生成存根。

Use this feature with caution as it may lead to false positives, because you generate stubs for your consumers to use without actually having the implementation in place.

如果要将合同设置为进行中，以下示例显示如何执行此操作：

If you want to set a contract in progress, the following example shows how to do so:

Groovy
Unresolved directive in common-top-elements.adoc - include::{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[]
YAML
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/yml/contract.yml[]
Java
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[]
Kotlin
Unresolved directive in common-top-elements.adoc - include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[]

可以将 failOnInProgress Spring Cloud Contract 插件属性的值设置为确保在你的源中至少有一个正在进行的合同时终止你的构建。

You can set the value of the failOnInProgress Spring Cloud Contract plugin property to ensure that your build breaks when at least one contract in progress remains in your sources.

Passing Values from Files

从版本 1.2.0 开始，你可以传递文件中的值。假设你的项目中具有以下资源：

Starting with version 1.2.0, you can pass values from files. Assume that you have the following resources in your project:

└── src
    └── test
        └── resources
            └── contracts
                ├── readFromFile.groovy
                ├── request.json
                └── response.json

另外假设你的合同如下：

Further assume that your contract is as follows:

Groovy
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/classpath/readFromFile.groovy[]
YAML
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/yml/contract_from_file.yml[]
Java
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/contractsToCompile/contract_rest_from_file.java[]
Kotlin
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/kotlin/readFromFile.kts[]

再假设 JSON 文件如下：

Further assume that the JSON files are as follows:

request.json
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/classpath/request.json[]
response.json
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/classpath/response.json[]

当测试或存根生成发生时，request.json 和 response.json 文件的内容被传递给请求或响应的正文。文件名称需要是驻留合同所在的文件夹的相对位置中的一个文件。

When test or stub generation takes place, the contents of the request.json and response.json files are passed to the body of a request or a response. The name of the file needs to be a file in a location relative to the folder in which the contract resides.

如果你需要以二进制形式传递文件的内容，则可以在编码的 DSL 中使用 fileAsBytes 方法，或在 YAML 中使用 bodyFromFileAsBytes 字段。

If you need to pass the contents of a file in binary form, you can use the fileAsBytes method in the coded DSL or a bodyFromFileAsBytes field in YAML.

以下示例显示如何传递二进制文件的内容：

The following example shows how to pass the contents of binary files:

Groovy
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/body_builder/worksWithPdf.groovy[]
YAML
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/yml/contract_pdf.yml[]
Java
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/contractsToCompile/contract_rest_from_pdf.java[]
Kotlin
Unresolved directive in common-top-elements.adoc - include::{contract_kotlin_spec_path}/src/test/resources/contracts/shouldWorkWithBinaryPayload.kts[]

在您想要处理二进制有效负载时，无论对于 HTTP 还是消息传递，都应该使用这种方法。

You should use this approach whenever you want to work with binary payloads, both for HTTP and messaging.

Metadata

你可以向你的合同添加 metadata。通过元数据，你可以将配置传递给扩展。在下面，你可以找到使用 wiremock 键的示例。它的值是一个映射，其键是 stubMapping，值是 WireMock 的 StubMapping 对象。Spring Cloud Contract 能够用你的自定义代码修补你生成的存根映射的部分。你可能需要这样做，以便添加 Webhook、自定义延迟或与第三方 WireMock 扩展集成。

You can add metadata to your contract. Via the metadata you can pass in configuration to extensions. Below you can find an example of using the wiremock key. Its value is a map whose key is stubMapping and value being WireMock’s StubMapping object. Spring Cloud Contract is able to patch parts of your generated stub mapping with your custom code. You may want to do that in order to add webhooks, custom delays or integrate with third party WireMock extensions.

groovy
Unresolved directive in common-top-elements.adoc - include::{standalone_samples_path}/http-server/src/test/resources/contracts/fraud/shouldReturnFraudStats.groovy[]
yml
Unresolved directive in common-top-elements.adoc - include::{standalone_samples_path}/http-server/src/test/resources/contracts/yml/fraud/shouldReturnFraudStats.yml[]
java
Unresolved directive in common-top-elements.adoc - include::{verifier_root_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[]
kotlin
Unresolved directive in common-top-elements.adoc - include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[]

在以下部分中，你可以找到受支持的元数据项的示例。

In the following sections you can find examples of the supported metadata entries.

Contracts for HTTP

Spring Cloud Contract 让你可以验证使用 REST 或 HTTP 作为通信手段的应用程序。Spring Cloud Contract 验证对于与合同的 request 部分中的条件相匹配的请求，服务器是否提供了与合同的 response 部分相符的响应。随后，这些合同用于生成 WireMock 存根，对于与所提供条件相匹配的任何请求，提供合适的响应。

Spring Cloud Contract lets you verify applications that use REST or HTTP as a means of communication. Spring Cloud Contract verifies that, for a request that matches the criteria from the request part of the contract, the server provides a response that is in keeping with the response part of the contract. Subsequently, the contracts are used to generate WireMock stubs that, for any request matching the provided criteria, provide a suitable response.