Spring Cloud Contractを触ってみようと思ったきっかけは、会社での SwaggerでAPI仕様書を書く -> レビュー -> 実装 という開発フロー問題を感じているからです。
このフローには 1.実装とAPI仕様書で乖離してしまう恐れがある 、 2.いちいちAPI仕様書を書くのがめんどくさい 、 3.実装が仕様を満たしている保証はできない という問題があります。
そこで、実装とAPI仕様書が乖離しないいい感じのライブラリを探してたら、「Spring Fox」と「Spring REST Docs」が見つかりました。しかし、どちらもコードからAPI仕様書を生成してくれるライブラリなのですが、微妙だなと感じました。 Spring Foxは、公式でないしプロダクトコードに手を加えないといけないです。Spring REST Docsは理想に近かったのですが、TDD向きで今から始めるには辛いかなと。 このような相談を知り合いのエンジニアに話したら、「Spring Cloud Contract」があるよと教えてくれました。
Spring Cloud Contractとは
Spring Cloud Contractは、CDC(Consumer Driven Contracts)をサポートするためのプロジェクトでマイクロサービス化されたアプリケーションに嬉しいプロジェクトです。
Consumer Driven Contracts testingとは
Consumer Driven Contracts(CDC) testingは主にマイクロサービスに役立つテスト手法です。 Consumer（サービスを使う側）が定義したContract（契約）をProvider（サービスを提供する側）が守らなければなりません。
サンプルアプリケーション
ソースコードはGitHubに置いてあります。ProducerConsumer
サンプルの内容
- ProducerとConsumerを実装
- Spring Cloud Contractを使ってCDC testingできるようにする
サンプルは、Java13、Spring Boot2.2.0で作っています。
Producer
Controllerの実装
BrandController.java
@RestController @RequestMapping("/brands") public class BrandController { @GetMapping public BrandListDto list() { Brand stof = new Brand(); stof.setName("STOF"); stof.setDesigner("Tanita"); BrandListDto listDto = new BrandListDto(); listDto.setBrands(List.of(stof)); return listDto; } }
Spring Cloud Contractを依存関係に追加
pom.xml
<dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-contract-verifier</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.cloud</groupId> <artifactId>spring-cloud-contract-maven-plugin</artifactId> <version>${spring-cloud-contract-maven-plugin.verison}</version> <extensions>true</extensions> <configuration> <!-- 生成するテストがextendsするクラス --> <baseClassForTests> com.b1a9idps.springcloudcontractsample.producer.TestBase </baseClassForTests> <!-- JUnit5で利用できるように（デフォルトはJUnit4） --> <testFramework>JUNIT5</testFramework> </configuration> </plugin> </plugins> </build>
TestBase.java
@ExtendWith(SpringExtension.class) @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK) // DIコンテナを破棄するタイミングをコントロールする @DirtiesContext public abstract class TestBase { @BeforeEach public void setup(WebApplicationContext context) { RestAssuredMockMvc.mockMvc( MockMvcBuilders.webAppContextSetup(context).build()); } }
Contractを追加
GroovyかYAMLで記述します。デフォルトのパスは、 $rootDir/src/test/resources/contracts です。
brand.yml
request: method: GET url: /brands headers: Content-Type: application/json response: status: 200 body: brands: - name: "STOF" designer:: "Tanita" headers: Content-Type: application/json
期待するリクエストとレスポンスをそれぞれ記述します。bodyを別でjsonファイルを定義することもできます。
brand.yml
request: method: GET url: /brands headers: Content-Type: application/json response: status: 200 bodyFromFile: brand_response.json headers: Content-Type: application/json
テストクラスを生成する
./mvnw clean install を実行することでテストクラスが生成して、スタブを作ってローカルレポジトリにインストールします。
... [INFO] Generating server tests source code for Spring Cloud Contract Verifier contract verification [INFO] Will use contracts provided in the folder [/Users/uchitate/study/producer/src/test/resources/contracts] [INFO] Directory with contract is present at [/Users/uchitate/study/producer/src/test/resources/contracts] [INFO] Test Source directory: /Users/uchitate/study/producer/target/generated-test-sources/contracts added. [INFO] Using [com.b1a9idps.springcloudcontractsample.producer.TestBase] as base class for test classes, [null] as base package for tests, [null] as package with base classes, base class mappings [] [INFO] Creating new class file [/Users/uchitate/study/producer/target/generated-test-sources/contracts/com/b1a9idps/springcloudcontractsample/producer/ContractVerifierTest.java] [INFO] Generated 1 test classes. [INFO] [INFO] --- spring-cloud-contract-maven-plugin:2.1.3.RELEASE:convert (default-convert) @ producer --- [INFO] Will use contracts provided in the folder [/Users/uchitate/study/producer/src/test/resources/contracts] [INFO] Copying Spring Cloud Contract Verifier contracts to [/Users/uchitate/study/producer/target/stubs/META-INF/com.b1a9idps.spring-cloud-contract-sample/producer/0.0.1-SNAPSHOT/contracts]. Only files matching [.*] pattern will end up in the final JAR with stubs. [INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] Copying 2 resources [INFO] Converting from Spring Cloud Contract Verifier contracts to WireMock stubs mappings [INFO] Spring Cloud Contract Verifier contracts directory: /Users/uchitate/study/producer/src/test/resources/contracts [INFO] Stub Server stubs mappings directory: /Users/uchitate/study/producer/target/stubs/META-INF/com.b1a9idps.spring-cloud-contract-sample/producer/0.0.1-SNAPSHOT/mappings [INFO] Creating new stub [/Users/uchitate/study/producer/target/stubs/META-INF/com.b1a9idps.spring-cloud-contract-sample/producer/0.0.1-SNAPSHOT/mappings/brand.json] [INFO] [INFO] --- maven-resources-plugin:3.1.0:testResources (default-testResources) @ producer --- [INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] Copying 2 resources [INFO] skip non existing resourceDirectory /Users/uchitate/study/producer/target/generated-test-resources/contracts [INFO] [INFO] --- maven-compiler-plugin:3.8.1:testCompile (default-testCompile) @ producer --- [INFO] Changes detected - recompiling the module! [INFO] Compiling 2 source files to /Users/uchitate/study/producer/target/test-classes [INFO] [INFO] --- maven-surefire-plugin:2.22.2:test (default-test) @ producer --- ... // テスト実行 ... [INFO] --- spring-cloud-contract-maven-plugin:2.1.3.RELEASE:generateStubs (default-generateStubs) @ producer --- [INFO] Files matching this pattern will be excluded from stubs generation [] [INFO] Building jar: /Users/uchitate/study/producer/target/producer-0.0.1-SNAPSHOT-stubs.jar [INFO] [INFO] --- maven-jar-plugin:3.1.2:jar (default-jar) @ producer --- [INFO] Building jar: /Users/uchitate/study/producer/target/producer-0.0.1-SNAPSHOT.jar [INFO] [INFO] --- spring-boot-maven-plugin:2.2.0.RELEASE:repackage (repackage) @ producer --- [INFO] Replacing main artifact with repackaged archive [INFO] [INFO] --- maven-install-plugin:2.5.2:install (default-install) @ producer --- [INFO] Installing /Users/uchitate/study/producer/target/producer-0.0.1-SNAPSHOT.jar to /Users/uchitate/.m2/repository/com/b1a9idps/spring-cloud-contract-sample/producer/0.0.1-SNAPSHOT/producer-0.0.1-SNAPSHOT.jar [INFO] Installing /Users/uchitate/study/producer/pom.xml to /Users/uchitate/.m2/repository/com/b1a9idps/spring-cloud-contract-sample/producer/0.0.1-SNAPSHOT/producer-0.0.1-SNAPSHOT.pom [INFO] Installing /Users/uchitate/study/producer/target/producer-0.0.1-SNAPSHOT-stubs.jar to /Users/uchitate/.m2/repository/com/b1a9idps/spring-cloud-contract-sample/producer/0.0.1-SNAPSHOT/producer-0.0.1-SNAPSHOT-stubs.jar
生成されたテストクラス（ContractVerifierTest.java）
public class ContractVerifierTest extends TestBase { @Test public void validate_brand() throws Exception { // given: MockMvcRequestSpecification request = given() .header("Content-Type", "application/json"); // when: ResponseOptions response = given().spec(request) .get("/brands"); // then: assertThat(response.statusCode()).isEqualTo(200); assertThat(response.header("Content-Type")).isEqualTo("application/json"); // and: DocumentContext parsedJson = JsonPath.parse(response.getBody().asString()); assertThatJson(parsedJson).array("['brands']").contains("['designer']").isEqualTo("Tanita"); assertThatJson(parsedJson).array("['brands']").contains("['name']").isEqualTo("STOF"); } }
Consumer
BrandServiceの実装
BrandServiceImpl.java
@Service public class BrandServiceImpl implements BrandService { private final RestTemplate restTemplate; private final URI producerUrl; public BrandServiceImpl(RestTemplateBuilder restTemplateBuilder, @Value("${producer.url}") String producerUrl) { this.restTemplate = restTemplateBuilder.build(); this.producerUrl = UriComponentsBuilder.fromHttpUrl(producerUrl).build().toUri(); } @Override public BrandListDto list() { HttpHeaders httpHeaders = new HttpHeaders(); httpHeaders.add(HttpHeaders.CONTENT_TYPE, APPLICATION_JSON_VALUE); ResponseEntity<BrandListDto> responseEntity = restTemplate.exchange( producerUrl, HttpMethod.GET, new HttpEntity<>(httpHeaders), new ParameterizedTypeReference<>() {}); return responseEntity.getBody(); } }
Spring Cloud Contractを依存関係に追加
Producer側とほぼ同じなので説明は省略します。
pom.xml
<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> <build> <plugins> <plugin> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-contract-maven-plugin</artifactId> <version>${spring-cloud-contract-maven-plugin.verison}</version> <configuration> <testFramework>JUNIT5</testFramework> </configuration> </plugin> </plugins> </build>
テストを書く
/test/resources/application.yaml
producer: url: http://localhost:8080/brands
BrandServiceImplTest.java
// StubRunnnerExtension.classを登録する @ExtendWith({SpringExtension.class, StubRunnerExtension.class}) @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT) @AutoConfigureStubRunner(ids = {"com.b1a9idps.spring-cloud-contract-sample:producer:+:stubs:8080"}, stubsMode = StubsMode.LOCAL) class BrandServiceImplTest { @Autowired private BrandService brandService; @Test void list() { Assertions.assertThat(brandService.list().getBrands()) .extracting(Brand::getName, Brand::getDesigner) .containsExactly(Tuple.tuple("STOF", "Tanita")); } }
@AutoConfigureStubRunner を付与してスタブ生成の対象を指定します。idsに指定する値は、 [groupId]:artifactId[:version][:classifier][:port] です。.m2レポジトリに .m2/repository/com/b1a9idps/spring-cloud-contract-sample/producer/0.0.1-SNAPSHOT/producer-0.0.1-SNAPSHOT-stubs.jar とjarがインストールされているので、 com.b1a9idps.spring-cloud-contract-sample:producer:+:stubs:8080 と指定します。バージョンを + で指定すると最新バージョンを設定します。
テストを実行
2019-11-19 00:07:15.872 INFO 24517 --- [ main] o.s.c.c.s.AetherStubDownloaderBuilder : Will download stubs and contracts via Aether
2019-11-19 00:07:15.874 INFO 24517 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Remote repos not passed but the switch to work offline was set. Stubs will be used from your local Maven repository.
2019-11-19 00:07:15.984 INFO 24517 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Desired version is [+] - will try to resolve the latest version
2019-11-19 00:07:15.997 INFO 24517 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved version is [0.0.1-SNAPSHOT]
2019-11-19 00:07:16.007 INFO 24517 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved artifact [com.b1a9idps.spring-cloud-contract-sample:producer:jar:stubs:0.0.1-SNAPSHOT] to /Users/uchitate/.m2/repository/com/b1a9idps/spring-cloud-contract-sample/producer/0.0.1-SNAPSHOT/producer-0.0.1-SNAPSHOT-stubs.jar
2019-11-19 00:07:16.010 INFO 24517 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacking stub from JAR [URI: file:/Users/uchitate/.m2/repository/com/b1a9idps/spring-cloud-contract-sample/producer/0.0.1-SNAPSHOT/producer-0.0.1-SNAPSHOT-stubs.jar]
2019-11-19 00:07:16.016 INFO 24517 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacked file to [/var/folders/0z/n7t2zxm566zfmzbtg7qdc6_80000gp/T/contracts17319340210365511943]
2019-11-19 00:07:16.705 INFO 24517 --- [ main] wiremock.org.eclipse.jetty.util.log : Logging initialized @4424ms
2019-11-19 00:07:16.770 INFO 24517 --- [ main] w.org.eclipse.jetty.server.Server : jetty-9.2.z-SNAPSHOT
2019-11-19 00:07:16.784 INFO 24517 --- [ main] w.o.e.j.server.handler.ContextHandler : Started w.o.e.j.s.ServletContextHandler@5c60c08{/__admin,null,AVAILABLE}
2019-11-19 00:07:16.785 INFO 24517 --- [ main] w.o.e.j.server.handler.ContextHandler : Started w.o.e.j.s.ServletContextHandler@212e39ee{/,null,AVAILABLE}
2019-11-19 00:07:16.810 INFO 24517 --- [ main] w.o.e.j.s.NetworkTrafficServerConnector : Started NetworkTrafficServerConnector@173e960b{HTTP/1.1}{0.0.0.0:8080}
2019-11-19 00:07:16.811 INFO 24517 --- [ main] w.org.eclipse.jetty.server.Server : Started @4532ms
2019-11-19 00:07:16.812 INFO 24517 --- [ main] o.s.c.contract.stubrunner.StubServer : Started stub server for project [com.b1a9idps.spring-cloud-contract-sample:producer:0.0.1-SNAPSHOT:stubs] on port 8080
2019-11-19 00:07:17.082 INFO 24517 --- [tp2142521143-31] /__admin : RequestHandlerClass from context returned com.github.tomakehurst.wiremock.http.AdminRequestHandler. Normalized mapped under returned 'null'
2019-11-19 00:07:17.106 INFO 24517 --- [tp2142521143-31] WireMock : Admin request received:
127.0.0.1 - POST /mappings
Connection: [keep-alive]
User-Agent: [Apache-HttpClient/4.5.5 (Java/13)]
Host: [localhost:8080]
Content-Length: [225]
Content-Type: [text/plain; charset=UTF-8]
{
"id" : "a18b18d9-bf53-478a-be02-c4b05d417911",
"request" : {
"url" : "/ping",
"method" : "GET"
},
"response" : {
"status" : 200,
"body" : "OK"
},
"uuid" : "a18b18d9-bf53-478a-be02-c4b05d417911"
}
2019-11-19 00:07:17.180 INFO 24517 --- [tp2142521143-32] WireMock : Admin request received:
127.0.0.1 - POST /mappings
Connection: [keep-alive]
User-Agent: [Apache-HttpClient/4.5.5 (Java/13)]
Host: [localhost:8080]
Content-Length: [227]
Content-Type: [text/plain; charset=UTF-8]
{
"id" : "d4c408f0-344e-4994-9118-f3844404a3fc",
"request" : {
"url" : "/health",
"method" : "GET"
},
"response" : {
"status" : 200,
"body" : "OK"
},
"uuid" : "d4c408f0-344e-4994-9118-f3844404a3fc"
}
2019-11-19 00:07:17.246 INFO 24517 --- [tp2142521143-33] WireMock : Admin request received:
127.0.0.1 - POST /mappings
Connection: [keep-alive]
User-Agent: [Apache-HttpClient/4.5.5 (Java/13)]
Host: [localhost:8080]
Content-Length: [493]
Content-Type: [text/plain; charset=UTF-8]
{
"id" : "3e1ac4f8-4565-42b5-946a-e136e1822941",
"request" : {
"url" : "/brands",
"method" : "GET",
"headers" : {
"Content-Type" : {
"equalTo" : "application/json"
}
}
},
"response" : {
"status" : 200,
"body" : "{\"brands\":[{\"name\":\"STOF\",\"designer\":\"Tanita\"}]}",
"headers" : {
"Content-Type" : "application/json"
},
"transformers" : [ "response-template" ]
},
"uuid" : "3e1ac4f8-4565-42b5-946a-e136e1822941"
}
2019-11-19 00:07:17.313 INFO 24517 --- [ main] o.s.c.c.stubrunner.StubRunnerExecutor : All stubs are now running RunningStubs [namesAndPorts={com.b1a9idps.spring-cloud-contract-sample:producer:0.0.1-SNAPSHOT:stubs=8080}]
2019-11-19 00:07:17.358 INFO 24517 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 53672 (http) with context path ''
2019-11-19 00:07:17.362 INFO 24517 --- [ main] c.b.s.c.s.impl.BrandServiceImplTest : Started BrandServiceImplTest in 3.981 seconds (JVM running for 5.083)
2019-11-19 00:07:17.365 WARN 24517 --- [ main] o.s.c.c.stubrunner.StubRunnerFactory : No stubs to download have been passed. Most likely you have forgotten to pass them either via annotation or a property
2019-11-19 00:07:17.735 INFO 24517 --- [tp2142521143-31] / : RequestHandlerClass from context returned com.github.tomakehurst.wiremock.http.StubRequestHandler. Normalized mapped under returned 'null'
2019-11-19 00:07:17.801 INFO 24517 --- [tp2142521143-31] WireMock : Request received:
127.0.0.1 - GET /brands
Connection: [keep-alive]
User-Agent: [Apache-HttpClient/4.5.9 (Java/13)]
Host: [localhost:8080]
Accept-Encoding: [gzip,deflate]
Accept: [application/json, application/*+json]
Content-Type: [application/json]
Matched response definition:
{
"status" : 200,
"body" : "{\"brands\":[{\"name\":\"STOF\",\"designer\":\"Tanita\"}]}",
"headers" : {
"Content-Type" : "application/json"
},
"transformers" : [ "response-template" ]
}
Response:
HTTP/1.1 200
Content-Type: [application/json]
Matched-Stub-Id: [3e1ac4f8-4565-42b5-946a-e136e1822941]
2019-11-19 00:07:17.913 WARN 24517 --- [ main] .StubRunnerWireMockTestExecutionListener : You've used fixed ports for WireMock setup - will mark context as dirty. Please use random ports, as much as possible. Your tests will be faster and more reliable and this warning will go away
2019-11-19 00:07:17.923 INFO 24517 --- [ main] w.o.e.j.s.NetworkTrafficServerConnector : Stopped NetworkTrafficServerConnector@173e960b{HTTP/1.1}{0.0.0.0:8080}
2019-11-19 00:07:17.924 INFO 24517 --- [ main] w.o.e.j.server.handler.ContextHandler : Stopped w.o.e.j.s.ServletContextHandler@212e39ee{/,null,UNAVAILABLE}
2019-11-19 00:07:17.924 INFO 24517 --- [ main] w.o.e.j.server.handler.ContextHandler : Stopped w.o.e.j.s.ServletContextHandler@5c60c08{/__admin,null,UNAVAILABLE}
2019-11-19 00:07:17.925 WARN 24517 --- [ main] w.o.e.j.util.thread.QueuedThreadPool : qtp2142521143{STOPPING,8<=8<=10,i=3,q=6} Couldn't stop Thread[qtp2142521143-28,5,]
2019-11-19 00:07:17.925 WARN 24517 --- [ main] w.o.e.j.util.thread.QueuedThreadPool : qtp2142521143{STOPPING,8<=8<=10,i=0,q=4} Couldn't stop Thread[qtp2142521143-29,5,]
2019-11-19 00:07:17.926 INFO 24517 --- [ main] o.s.s.concurrent.ThreadPoolTaskExecutor : Shutting down ExecutorService 'applicationTaskExecutor'
Class transformation time: 0.040030372s for 10526 classes or 3.8029994299828998E-6s per class
Process finished with exit code 0
これがテストを実行時に吐き出されるログです。テストが実行されるまでに「1. ローカルレポジトリからstubのjarをインストール」「2. 8080番ポートでモックサーバを起動」が行われています。
まとめ
Producer側では、Contractに基づいたテストが生成され、Consumer側で利用するためのスタブを生成してローカルレポジトリにインストールします。Consumer側では、生成されたスタブを使ってテストを実行します。 Spring Cloud Contractを使えば、Consumerが定義したContractをProviderが守っていることが担保できます。また、Consumerも実サービスに近いテストを行うことができます。とてもよいですね！！！
長くなりすぎたので、別記事でSpring REST Docsとの連携は書きます！
