入门·消费者驱动的合同

本指南将引导您完成使用合同存根创建Spring REST应用程序以及在其他Spring应用程序中使用合同的过程。spring-cloud-contract项目

你会建立什么

您将设置两个微服务，一个提供其合同，另一个使用该合同，以确保与合同提供者服务的集成符合规范。如果将来生产者服务的合同发生变化，那么消费者服务的测试将无法捕获潜在的不兼容性。

你需要什么

约15分钟
最喜欢的文本编辑器或IDE
JDK 1.8或更高版本
Gradle 4+或Maven 3.2+
您还可以将代码直接导入到IDE中：
- Spring Tool Suite (STS)
- IntelliJ IDEA

如何完成本指南

像大多数Spring 入门指南一样，您可以从头开始并完成每个步骤，也可以绕过您已经熟悉的基本设置步骤。无论哪种方式，您最终都可以使用工作代码。

要从头开始 ，请继续使用Gradle构建。

要跳过基础知识 ，请执行以下操作：

下载并解压缩本指南的源存储库，或使用Git对其进行克隆：git clone https://github.com/spring-guides/gs-contract-rest.git
光盘进入gs-contract-rest/initial
继续创建合同生产者服务。

完成后 ，您可以根据中的代码检查结果gs-contract-rest/complete 。

用Gradle构建

首先，您设置一个基本的构建脚本。在使用Spring构建应用程序时，可以使用任何喜欢的构建系统，但是此处包含使用Gradle和Maven所需的代码。如果您都不熟悉，请参阅使用Gradle 构建Java项目或使用Maven构建Java项目。

创建目录结构

在您选择的项目目录中，创建以下子目录结构；例如， mkdir -p src/main/java/hello在* nix系统上：

└── src
    └── main
        └── java
            └── hello

创建一个Gradle构建文件

以下是最初的Gradle构建文件。

contract-rest-service/build.gradle

buildscript {
	ext {
		springBootVersion = '2.1.6.RELEASE'
		verifierVersion = '2.1.1.RELEASE'
	}
	repositories { mavenCentral() }
	dependencies {
		classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
		classpath "org.springframework.cloud:spring-cloud-contract-gradle-plugin:${verifierVersion}"
	}
}

apply plugin: 'groovy'
apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'
apply plugin: 'spring-cloud-contract'


bootJar {
	baseName = 'contract-rest-service'
	version = '0.0.1-SNAPSHOT'
}
sourceCompatibility = 1.8
targetCompatibility = 1.8

repositories { mavenCentral() }

dependencies {
	compile('org.springframework.boot:spring-boot-starter-web')
	testCompile('org.springframework.boot:spring-boot-starter-test')
	testCompile('org.springframework.cloud:spring-cloud-starter-contract-verifier')
}

dependencyManagement {
	imports {
		mavenBom "org.springframework.cloud:spring-cloud-dependencies:Greenwich.SR1"
	}
}

contracts {
	packageWithBaseClasses = 'hello'
	baseClassMappings {
		baseClassMapping(".*hello.*", "hello.BaseClass")
	}
}

contract-rest-client/build.gradle

buildscript {
	ext { springBootVersion = '2.1.6.RELEASE' }
	repositories { mavenCentral() }
	dependencies {
		classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
	}
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'

bootJar {
	baseName = 'contract-rest-client'
	version = '0.0.1-SNAPSHOT'
}
sourceCompatibility = 1.8
targetCompatibility = 1.8

repositories { mavenCentral() }

dependencies {
	compile('org.springframework.boot:spring-boot-starter-web')
	testCompile('org.springframework.boot:spring-boot-starter-test')
	testCompile('org.springframework.cloud:spring-cloud-starter-contract-stub-runner')
}

dependencyManagement {
	imports {
		mavenBom "org.springframework.cloud:spring-cloud-dependencies:Greenwich.SR1"
	}
}

eclipse {
	classpath {
		containers.remove('org.eclipse.jdt.launching.JRE_CONTAINER')
		containers 'org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8'
	}
}

Spring Boot gradle插件提供了许多方便的功能：

它收集类路径上的所有jar，并构建一个可运行的单个“über-jar”，这使执行和传输服务更加方便。
它搜索public static void main()标记为可运行类的方法。
它提供了一个内置的依赖项解析器，用于设置版本号以匹配Spring Boot依赖项。您可以覆盖所需的任何版本，但是它将默认为Boot选择的一组版本。

用Maven构建

首先，您设置一个基本的构建脚本。使用Spring构建应用程序时，可以使用任何喜欢的构建系统，但是此处包含了使用Maven所需的代码。如果您不熟悉Maven，请参阅使用Maven 构建Java项目。

创建目录结构

在您选择的项目目录中，创建以下子目录结构；例如， mkdir -p src/main/java/hello在* nix系统上：

└── src
    └── main
        └── java
            └── hello

为了快速入门，以下是服务器和客户端应用程序的完整配置：

contract-rest-service/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.example</groupId>
	<artifactId>contract-rest-service</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.1.6.RELEASE</version>
		<relativePath /> <!-- lookup parent from repository -->
	</parent>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<java.version>1.8</java.version>
		<spring-cloud.version>Finchley.SR2</spring-cloud.version>
		<spring-cloud-contract.version>2.0.2.RELEASE</spring-cloud-contract.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

        <!--
		<dependency>
			<groupId>org.springframework.cloud</groupId>
			<artifactId>spring-cloud-starter-contract-verifier</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.cloud</groupId>
			<artifactId>spring-cloud-contract-wiremock</artifactId>
			<scope>test</scope>
		</dependency>
        -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</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>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>

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

		</plugins>
	</build>


</project>

contract-rest-client/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.example</groupId>
	<artifactId>contract-rest-client</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.1.6.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<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>Finchley.SR2</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
	</dependencyManagement>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>


</project>

Spring Boot Maven插件提供了许多方便的功能：

它收集类路径上的所有jar，并构建一个可运行的单个“über-jar”，这使执行和传输服务更加方便。
它搜索public static void main()标记为可运行类的方法。
它提供了一个内置的依赖项解析器，用于设置版本号以匹配Spring Boot依赖项。您可以覆盖所需的任何版本，但是它将默认为Boot选择的一组版本。

使用您的IDE进行构建

阅读如何将本指南直接导入Spring Tool Suite中。
在IntelliJ IDEA中阅读如何使用本指南。

创建合同生产者服务

首先，您需要创建产生合同的服务。这是一个常规的Spring Boot应用程序，提供了非常简单的REST服务。其余服务仅返回一个Person JSON中的对象。

contract-rest-service/src/main/java/hello/ContractRestServiceApplication.java

package hello;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ContractRestServiceApplication {

	public static void main(String[] args) {
		SpringApplication.run(ContractRestServiceApplication.class, args);
	}
}

创建REST服务的合同

REST服务的合同可以定义为.groovy脚本。该合同规定，如果存在GET要求网址/person/1 ，样本数据id=1 ， name=foo和surname=bee代表一个Person实体将在content-type的响应主体中返回application/json 。

contract-rest-service/src/test/resources/contracts/hello/find_person_by_id.groovy

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

Contract.make {
	description "should return person by id=1"

	request {
		url "/person/1"
		method GET()
	}

	response {
		status OK()
		headers {
			contentType applicationJson()
		}
		body (
			id: 1,
			name: "foo",
			surname: "bee"
		)
	}
}

在test阶段，将为groovy文件中指定的合同创建自动测试类。自动生成的测试Java类将扩展hello.BaseClass 。

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

contract-rest-service/src/test/java/hello/BaseClass.java

package hello;

import org.junit.Before;
import org.junit.runner.RunWith;
import org.mockito.Mockito;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.test.context.junit4.SpringRunner;

import io.restassured.module.mockmvc.RestAssuredMockMvc;

@RunWith(SpringRunner.class)
@SpringBootTest(classes = ContractRestServiceApplication.class)
public abstract class BaseClass {

	@Autowired PersonRestController personRestController;

	@MockBean PersonService personService;

	@Before public void setup() {
		RestAssuredMockMvc.standaloneSetup(personRestController);

		Mockito.when(personService.findPersonById(1L))
				.thenReturn(new Person(1L, "foo", "bee"));
	}

}

在此步骤中，执行测试时，测试结果应为绿色，表明REST控制器与合同保持一致，并且您具有正常运行的服务。

检查简单的Person查询业务逻辑

模型类Person.java contract-rest-service/src/main/java/hello/Person.java

package hello;

class Person {

	Person(Long id, String name, String surname) {
		this.id = id;
		this.name = name;
		this.surname = surname;
	}

	private Long id;

	private String name;

	private String surname;

	public Long getId() {
		return id;
	}

	public void setId(Long id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public String getSurname() {
		return surname;
	}

	public void setSurname(String surname) {
		this.surname = surname;
	}
}

服务 bean PersonService.java它只是在内存中填充一些Person实体，并在询问时返回一个。contract-rest-service/src/main/java/hello/PersonService.java

package hello;

import java.util.HashMap;
import java.util.Map;

import org.springframework.stereotype.Service;

@Service
class PersonService {

	private final Map<Long, Person> personMap;

	public PersonService() {
		personMap = new HashMap<>();
		personMap.put(1L, new Person(1L, "Richard", "Gere"));
		personMap.put(2L, new Person(2L, "Emma", "Choplin"));
		personMap.put(3L, new Person(3L, "Anna", "Carolina"));
	}

	Person findPersonById(Long id) {
		return personMap.get(id);
	}
}

RestController bean PersonRestController.java哪个电话PersonService接收到具有ID的人的REST请求时的bean。contract-rest-service/src/main/java/hello/PersonRestController.java

package hello;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
class PersonRestController {

	private final PersonService personService;

	public PersonRestController(PersonService personService) {
		this.personService = personService;
	}

	@GetMapping("/person/{id}")
	public Person findPersonById(@PathVariable("id") Long id) {
		return personService.findPersonById(id);
	}
}

测试合同中止服务应用程序

跑过ContractRestServiceApplication.java类作为Java应用程序或Spring Boot应用程序。服务应从端口开始8000 。

在浏览器中访问服务http://localhost:8000/person/1 ， http://localhost:8000/person/2等

创建合同消费者服务

准备好合同生产者服务之后，现在我们需要创建使用提供的合同的客户端应用程序。这是一个常规的Spring Boot应用程序，提供了非常简单的REST服务。其余服务仅返回一条带有查询的人名的消息，例如Hello Anna 。

contract-rest-client/src/main/java/hello/ContractRestClientApplication.java

package hello;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;

@SpringBootApplication
public class ContractRestClientApplication {

	public static void main(String[] args) {
		SpringApplication.run(ContractRestClientApplication.class, args);
	}
}

@RestController
class MessageRestController {

	private final RestTemplate restTemplate;

	MessageRestController(RestTemplateBuilder restTemplateBuilder) {
		this.restTemplate = restTemplateBuilder.build();
	}

	@RequestMapping("/message/{personId}")
	String getMessage(@PathVariable("personId") Long personId) {
		Person person = this.restTemplate.getForObject("http://localhost:8000/person/{personId}", Person.class, personId);
		return "Hello " + person.getName();
	}

}

创建合同测试

生产者提供的合同应作为简单的Spring测试使用。

contract-rest-client/src/test/java/hello/ContractRestClientApplicationTest.java

package hello;

import org.assertj.core.api.BDDAssertions;
import org.junit.Rule;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.cloud.contract.stubrunner.junit.StubRunnerRule;
import org.springframework.cloud.contract.stubrunner.spring.StubRunnerProperties;
import org.springframework.http.ResponseEntity;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.web.client.RestTemplate;

@RunWith(SpringRunner.class)
@SpringBootTest
public class ContractRestClientApplicationTest {

	@Rule
	public StubRunnerRule stubRunnerRule = new StubRunnerRule()
		.downloadStub("com.example", "contract-rest-service", "0.0.1-SNAPSHOT", "stubs")
		.withPort(8100)
		.stubsMode(StubRunnerProperties.StubsMode.LOCAL);

	@Test
	public void get_person_from_service_contract() {
		// given:
		RestTemplate restTemplate = new RestTemplate();

		// when:
		ResponseEntity<Person> personResponseEntity = restTemplate.getForEntity("http://localhost:8100/person/1", Person.class);

		// then:
		BDDAssertions.then(personResponseEntity.getStatusCodeValue()).isEqualTo(200);
		BDDAssertions.then(personResponseEntity.getBody().getId()).isEqualTo(1l);
		BDDAssertions.then(personResponseEntity.getBody().getName()).isEqualTo("foo");
		BDDAssertions.then(personResponseEntity.getBody().getSurname()).isEqualTo("bee");

	}
}

该测试类将加载合同生产者服务的存根，并确保与服务的集成与合同保持一致。

如果消费者服务的测试与生产者的合同之间的通信出现故障，则测试将失败，并且需要在生产上进行新的更改之前解决问题。

测试合同剩余客户应用程序

跑过ContractRestClientApplication.java类作为Java应用程序或Spring Boot应用程序。服务应从端口开始9000 。

在浏览器中访问服务http://localhost:9000/message/1 ， http://localhost:9000/message/2等

摘要

恭喜你！您刚刚使用Spring来使您的REST服务声明其合同和使用者服务与此合同保持一致。

也可以看看

以下指南也可能会有所帮助：

是否要编写新指南或为现有指南做出贡献？查看我们的贡献准则。

所有指南均以代码的ASLv2许可证和写作的Attribution，NoDerivatives创作共用许可证发布。