合同 DSL

Spring Cloud Contract 支持使用以下语言编写的 DSL：spring-doc.cadn.net.cn

Spring Cloud Contract 支持在单个文件中定义多个契约（在 Groovy 中返回一个列表而非单个契约）。

以下示例显示了一个契约定义：spring-doc.cadn.net.cn

Groovy

org.springframework.cloud.contract.spec.Contract.make {
	request {
		method 'PUT'
		url '/api/12'
		headers {
			header 'Content-Type': 'application/vnd.org.springframework.cloud.contract.verifier.twitter-places-analyzer.v1+json'
		}
		body '''\
	[{
		"created_at": "Sat Jul 26 09:38:57 +0000 2014",
		"id": 492967299297845248,
		"id_str": "492967299297845248",
		"text": "Gonna see you at Warsaw",
		"place":
		{
			"attributes":{},
			"bounding_box":
			{
				"coordinates":
					[[
						[-77.119759,38.791645],
						[-76.909393,38.791645],
						[-76.909393,38.995548],
						[-77.119759,38.995548]
					]],
				"type":"Polygon"
			},
			"country":"United States",
			"country_code":"US",
			"full_name":"Washington, DC",
			"id":"01fbe706f872cb32",
			"name":"Washington",
			"place_type":"city",
			"url": "https://api.twitter.com/1/geo/id/01fbe706f872cb32.json"
		}
	}]
'''
	}
	response {
		status OK()
	}
}

YAML

description: Some description
name: some name
priority: 8
ignored: true
request:
  url: /foo
  queryParameters:
    a: b
    b: c
  method: PUT
  headers:
    foo: bar
    fooReq: baz
  body:
    foo: bar
  matchers:
    body:
      - path: $.foo
        type: by_regex
        value: bar
    headers:
      - key: foo
        regex: bar
response:
  status: 200
  headers:
    foo2: bar
    foo3: foo33
    fooRes: baz
  body:
    foo2: bar
    foo3: baz
    nullValue: null
  matchers:
    body:
      - path: $.foo2
        type: by_regex
        value: bar
      - path: $.foo3
        type: by_command
        value: executeMe($it)
      - path: $.nullValue
        type: by_null
        value: null
    headers:
      - key: foo2
        regex: bar
      - key: foo3
        command: andMeToo($it)

Java

import java.util.Collection;
import java.util.Collections;
import java.util.function.Supplier;

import org.springframework.cloud.contract.spec.Contract;
import org.springframework.cloud.contract.verifier.util.ContractVerifierUtil;

class contract_rest implements Supplier<Collection<Contract>> {

	@Override
	public Collection<Contract> get() {
		return Collections.singletonList(Contract.make(c -> {
			c.description("Some description");
			c.name("some name");
			c.priority(8);
			c.ignored();
			c.request(r -> {
				r.url("/foo", u -> {
					u.queryParameters(q -> {
						q.parameter("a", "b");
						q.parameter("b", "c");
					});
				});
				r.method(r.PUT());
				r.headers(h -> {
					h.header("foo", r.value(r.client(r.regex("bar")), r.server("bar")));
					h.header("fooReq", "baz");
				});
				r.body(ContractVerifierUtil.map().entry("foo", "bar"));
				r.bodyMatchers(m -> {
					m.jsonPath("$.foo", m.byRegex("bar"));
				});
			});
			c.response(r -> {
				r.fixedDelayMilliseconds(1000);
				r.status(r.OK());
				r.headers(h -> {
					h.header("foo2", r.value(r.server(r.regex("bar")), r.client("bar")));
					h.header("foo3", r.value(r.server(r.execute("andMeToo($it)")), r.client("foo33")));
					h.header("fooRes", "baz");
				});
				r.body(ContractVerifierUtil.map().entry("foo2", "bar").entry("foo3", "baz").entry("nullValue", null));
				r.bodyMatchers(m -> {
					m.jsonPath("$.foo2", m.byRegex("bar"));
					m.jsonPath("$.foo3", m.byCommand("executeMe($it)"));
					m.jsonPath("$.nullValue", m.byNull());
				});
			});
		}));
	}

}

Kotlin

import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
import org.springframework.cloud.contract.spec.withQueryParameters

contract {
	name = "some name"
	description = "Some description"
	priority = 8
	ignored = true
	request {
		url = url("/foo") withQueryParameters  {
			parameter("a", "b")
			parameter("b", "c")
		}
		method = PUT
		headers {
			header("foo", value(client(regex("bar")), server("bar")))
			header("fooReq", "baz")
		}
		body = body(mapOf("foo" to "bar"))
		bodyMatchers {
			jsonPath("$.foo", byRegex("bar"))
		}
	}
	response {
		delay = fixedMilliseconds(1000)
		status = OK
		headers {
			header("foo2", value(server(regex("bar")), client("bar")))
			header("foo3", value(server(execute("andMeToo(\$it)")), client("foo33")))
			header("fooRes", "baz")
		}
		body = body(mapOf(
				"foo" to "bar",
				"foo3" to "baz",
				"nullValue" to null
		))
		bodyMatchers {
			jsonPath("$.foo2", byRegex("bar"))
			jsonPath("$.foo3", byCommand("executeMe(\$it)"))
			jsonPath("$.nullValue", byNull)
		}
	}
}

您可以使用以下独立的 Maven 命令将合约编译为存根映射：spring-doc.cadn.net.cn

mvn org.springframework.cloud:spring-cloud-contract-maven-plugin:convert

契约 DSL（领域特定语言）Groovy

如果你不熟悉 Groovy，不用担心。你也可以在 Groovy DSL 文件中使用 Java 语法。spring-doc.cadn.net.cn

如果您决定使用 Groovy 编写契约，即使您之前从未使用过 Groovy 也无需担心。实际上，并不需要掌握该语言的全部知识，因为契约 DSL 仅使用了 Groovy 的极小子集（仅包括字面量、方法调用和闭包）。此外，DSL 是静态类型的，以便在无需了解 DSL 本身的情况下，也能让程序员轻松理解。spring-doc.cadn.net.cn

请记住，在 Groovy 合同文件内部，您必须提供 Contract 类的完整限定名以及 make 静态导入，例如 org.springframework.cloud.spec.Contract.make { … }。您还可以为 Contract 类（import org.springframework.cloud.spec.Contract）提供一个导入语句，然后调用 Contract.make { … }。

合同DSL在Java中

要在 Java 中编写合约定义，您需要创建一个实现 Supplier<Contract> 接口（用于单个合约）或 Supplier<Collection<Contract>> 接口（用于多个合约）的类。spring-doc.cadn.net.cn

您还可以将契约定义编写在 src/test/java（例如，src/test/java/contracts）下，这样就不必修改项目的类路径。在这种情况下，您需要为 Spring Cloud Contract 插件提供新的契约定义位置。spring-doc.cadn.net.cn

以下示例（Maven 和 Gradle）将契约定义置于 src/test/java 下：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>
        <contractsDirectory>src/test/java/contracts</contractsDirectory>
    </configuration>
</plugin>

Gradle

contracts {
	contractsDslDir = new File(project.rootDir, "src/test/java/contracts")
}

Kotlin中的合同DSL

要开始使用 Kotlin 编写契约，您需要从一个（新创建的）Kotlin 脚本文件（.kts）开始。与 Java DSL 类似，您可以将契约放置在任意您选择的目录中。默认情况下，Maven 插件会查找 src/test/resources/contracts 目录，而 Gradle 插件则会查找 src/contractTest/resources/contracts 目录。spring-doc.cadn.net.cn

自 3.0.0 版本起，Gradle 插件也将查找遗留目录 src/test/resources/contracts，以供迁移使用。当在此目录中找到契约（contracts）时，构建过程中将记录一条警告信息。

您需要显式地将 spring-cloud-contract-spec-kotlin 依赖项传递给您的项目插件配置。以下示例（在 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>
        <!-- some config -->
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-contract-spec-kotlin</artifactId>
            <version>${spring-cloud-contract.version}</version>
        </dependency>
    </dependencies>
</plugin>

<dependencies>
        <!-- Remember to add this for the DSL support in the IDE and on the consumer side -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-contract-spec-kotlin</artifactId>
            <scope>test</scope>
        </dependency>
</dependencies>

Gradle

buildscript {
    repositories {
        // ...
    }
	dependencies {
		classpath "org.springframework.cloud:spring-cloud-contract-gradle-plugin:$\{scContractVersion}"
	}
}

dependencies {
    // ...

    // Remember to add this for the DSL support in the IDE and on the consumer side
    testImplementation "org.springframework.cloud:spring-cloud-contract-spec-kotlin"
    // Kotlin versions are very particular down to the patch version. The <kotlin_version> needs to be the same as you have imported for your project.
    testImplementation "org.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:<kotlin_version>"
}

请记住，在 Kotlin 脚本文件内部，您必须提供 ContractDSL 类的完整限定名。通常，您会按如下方式使用其契约函数：org.springframework.cloud.contract.spec.ContractDsl.contract { … }。您还可以为 contract 函数（import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract）提供导入，然后调用 contract { … }。

合同DSL在YAML

要查看 YAML 协议的模式，请访问 YML 模式页面。spring-doc.cadn.net.cn

限制

对验证 JSON 数组大小的支持为实验性功能。如果您希望启用此功能，请将以下系统属性的值设置为 true： spring.cloud.contract.verifier.assert.size。默认情况下，此功能被设置为 false。您还可以在插件配置中设置 assertJsonSize 属性。

由于 JSON 结构可以具有任意形式，当使用 Groovy DSL 和 value(consumer(…), producer(…)) 符号在 GString 中时，可能无法正确解析它。因此，您应使用 Groovy 映射（Map）符号。

一个文件中的多个合同

您可以在一个文件中定义多个契约。此类契约可能类似于以下示例：spring-doc.cadn.net.cn

Groovy

import org.springframework.cloud.contract.spec.Contract

[
	Contract.make {
		name("should post a user")
		request {
			method 'POST'
			url('/users/1')
		}
		response {
			status OK()
		}
	},
	Contract.make {
		request {
			method 'POST'
			url('/users/2')
		}
		response {
			status OK()
		}
	}
]

YAML

---
name: should post a user
request:
  method: POST
  url: /users/1
response:
  status: 200
---
request:
  method: POST
  url: /users/2
response:
  status: 200
---
request:
  method: POST
  url: /users/3
response:
  status: 200

Java

class contract implements Supplier<Collection<Contract>> {

	@Override
	public Collection<Contract> get() {
		return Arrays.asList(
            Contract.make(c -> {
            	c.name("should post a user");
                // ...
            }), Contract.make(c -> {
                // ...
            }), Contract.make(c -> {
                // ...
            })
		);
	}

}

Kotlin

import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract

arrayOf(
    contract {
        name("should post a user")
        // ...
    },
    contract {
        // ...
    },
    contract {
        // ...
    }
}

在前面的示例中，一个契约包含 name 字段，而另一个则不包含。这会导致生成两个如下所示的测试：spring-doc.cadn.net.cn

import com.example.TestBase;
import com.jayway.jsonpath.DocumentContext;
import com.jayway.jsonpath.JsonPath;
import com.jayway.restassured.module.mockmvc.specification.MockMvcRequestSpecification;
import com.jayway.restassured.response.ResponseOptions;
import org.junit.Test;

import static com.jayway.restassured.module.mockmvc.RestAssuredMockMvc.*;
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson;
import static org.assertj.core.api.Assertions.assertThat;

public class V1Test extends TestBase {

	@Test
	public void validate_should_post_a_user() throws Exception {
		// given:
			MockMvcRequestSpecification request = given();

		// when:
			ResponseOptions response = given().spec(request)
					.post("/users/1");

		// then:
			assertThat(response.statusCode()).isEqualTo(200);
	}

	@Test
	public void validate_withList_1() throws Exception {
		// given:
			MockMvcRequestSpecification request = given();

		// when:
			ResponseOptions response = given().spec(request)
					.post("/users/2");

		// then:
			assertThat(response.statusCode()).isEqualTo(200);
	}

}

请注意，对于具有 name 字段的合约，生成的测试方法命名为 validate_should_post_a_user。不具有 name 字段的合约则命名为 validate_withList_1。该名称对应于文件名 WithList.groovy 以及合约在列表中的索引。spring-doc.cadn.net.cn

生成的存根示例如下所示：spring-doc.cadn.net.cn

should post a user.json
1_WithList.json

第一个文件从合约中获取了 name 参数。第二个文件则获取了合约文件的名称（WithList.groovy），并在其前加上索引（本例中，该合约在文件中的合约列表里索引为 1）。spring-doc.cadn.net.cn

命名你的契约会好得多，因为这样能让你的测试更具意义。

有状态契约

有状态的契约（也称为场景）是应按顺序阅读的契约定义。这在以下情况下可能很有用：spring-doc.cadn.net.cn

你想要按照精确定义的顺序调用合同，因为你使用 Spring Cloud Contract 来测试你的状态ful应用程序。spring-doc.cadn.net.cn

我们强烈不建议你这样做，因为契约测试应该是无状态的。

你想要同一端点对相同请求返回不同的结果。spring-doc.cadn.net.cn

要创建具有状态的合同（或方案），您在创建合同时需要使用适当的命名约定。该约定要求在创建您的合同时包含一个顺序号，后面紧跟一个下划线。无论您是与 YAML 还是 Groovy 一起工作，这都可以正常工作。下面的清单显示了一个例子：spring-doc.cadn.net.cn

my_contracts_dir\
  scenario1\
    1_login.groovy
    2_showCart.groovy
    3_logout.groovy

此类树会导致 Spring Cloud Contract Verifier 生成带有名称 scenario1 和以下三个步骤的 WireMock 场景：spring-doc.cadn.net.cn

login, marked as Started pointing to…spring-doc.cadn.net.cn
showCart, marked as Step1 pointing to…spring-doc.cadn.net.cn
logout, marked as Step2 (which closes the scenario).spring-doc.cadn.net.cn

你可以在此找到有关WireMock方案的更多详细信息，请单击此处。spring-doc.cadn.net.cn