SpringCloud/spring-cloud-contract
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fixed the docs of sagan and the links in overview

Browse Source
This commit is contained in:
Marcin Grzejszczak
2019-08-18 13:22:30 +02:00
parent 6b5d4860b9
commit 6933633129
3 changed files with 149 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/src/main/asciidoc/documentation-overview.adoc
View File

@@ -12,9 +12,9 @@ as a map for the rest of the document.
The {project-full-name} reference guide is available as
* {docs-url}reference/html[Multi-page HTML]
* {docs-url}reference/htmlsingle[Single-page HTML]
* {docs-url}reference/pdf/{project-name}.pdf[PDF]
* {docs-url}/reference/html[Multi-page HTML]
* {docs-url}/reference/htmlsingle[Single-page HTML]
* {docs-url}/reference/pdf/{project-name}.pdf[PDF]
Copies of this document may be made for your own use and for distribution to others,
provided that you do not charge any fee for such copies and further provided that each

162
docs/src/main/asciidoc/sagan-boot.adoc
View File

@@ -1,100 +1,102 @@
== Adding Sleuth to Your Classpath:
== On the Producer Side
This section details how to add Sleuth to your class path for both Maven and Gradle
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.
=== Maven
Then you can add the Spring Cloud Contract Verifier dependency and plugin to your build file, as the following example shows:
To add Sleuth to your classpath with Maven, add the following elements
to your `pom.xml` file:
```xml
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-contract-verifier</artifactId>
<scope>test</scope>
</dependency>
```
====
[source,xml]
----
<dependencyManagement>
<dependencies>
<dependency>
The following listing shows how to add the plugin, which should go in the build/plugins portion of the file:
```xml
<plugin>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<version>${spring-cloud-contract.version}</version>
<extensions>true</extensions>
</plugin>
```
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.
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).
The following example, from pom.xml, shows how to specify the base test class:
```xml
<build>
<plugins>
<plugin>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-sleuth</artifactId>
<version>${spring-cloud-sleuth.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
</dependencies>
----
====
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<version>${spring-cloud-contract.version}</version>
<extensions>true</extensions>
<configuration>
<baseClassForTests>com.example.contractTest.BaseTestClass</baseClassForTests>
</configuration>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
```
=== Gradle
INFO: 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.
To add Sleuth to your classpath with Gradle, add the following
to your `build.gradle` file:
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.
2.2. On the Consumer Side
====
[src,groovy]
----
buildscript {
dependencies {
classpath "io.spring.gradle:dependency-management-plugin:0.5.2.RELEASE"
}
}
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.
apply plugin: "io.spring.dependency-management"
To do so, add the dependency to Spring Cloud Contract Stub Runner, as the following example shows:
dependencyManagement {
imports {
mavenBom "org.springframework.cloud:spring-cloud-sleuth:${springCloudSleuthVersion}"
}
}
dependencies {
compile 'org.springframework.cloud:spring-cloud-starter-sleuth'
}
----
====
```xml
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-contract-stub-runner</artifactId>
<scope>test</scope>
</dependency>
```
As long as Spring Cloud Sleuth is on the classpath, any Spring Boot application can
generate trace data. The following example shows how to do so:
You can get the Producer-side stubs installed in your Maven repository in either of two ways:
====
[src,java]
----
@SpringBootApplication
@RestController
public class Application {
By checking out the Producer side repository and adding contracts and generating the stubs by running the following commands:
private static Logger log = LoggerFactory.getLogger(DemoController.class);
```bash
$ cd local-http-server-repo
$ ./mvnw clean install -DskipTests
```
@RequestMapping("/")
public String home() {
log.info("Handling home");
return "Hello World";
}
The tests are being skipped because the producer-side contract implementation is not in place yet, so the automatically-generated contract tests fail.
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
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:
}
----
====
```yml
stubrunner:
ids: 'com.example:http-server-dsl:+:stubs:8080'
repositoryRoot: https://repo.spring.io/libs-snapshot
```
Now you can run this application and visit the home page. In the logs, you can see
`traceId` and `spanId` populated. If this application calls out to another one (for
example, with `RestTemplate`), it sends the trace data in headers, and, if the receiver is
another Sleuth application, you can see the trace continue there.
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:
IMPORTANT: instead of logging the request in the handler explicitly, you could set
`logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG`
```java
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment=WebEnvironment.NONE)
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"},
stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class LoanApplicationServiceTests {
```
IMPORTANT: If you use Zipkin, you can configure the probability of spans being exported by
setting (for `2.0.x`) `spring.sleuth.sampler.probability` or (up till `2.0.x`)
`spring.sleuth.sampler.percentage` (default: 0.1, which is 10 percent). Otherwise, you
might think that Sleuth is not working because it omits some spans.
Use the `REMOTE` stubsMode when downloading stubs from an online repository and `LOCAL` for offline work.
IMPORTANT: Set `spring.application.name=bar` (for instance) to see the service name as
well as the trace and span IDs.
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.

89
docs/src/main/asciidoc/sagan-index.adoc
View File

@@ -1,30 +1,69 @@
Spring Cloud Sleuth implements a distributed tracing solution for Spring Cloud, borrowing
heavily from https://research.google.com/pubs/pub36356.html[Dapper],
https://github.com/openzipkin/zipkin[Zipkin], and HTrace. For most users, Sleuth should be
invisible, and all your interactions with external systems should be instrumented
automatically. You can capture data in logs or by sending it to a remote collector service.
Spring Cloud Contract is an umbrella project holding solutions that help users in successfully implementing the Consumer Driven Contracts approach. Currently Spring Cloud Contract consists of the Spring Cloud Contract Verifier project.
Spring Cloud Contract Verifier is a tool that enables Consumer Driven Contract (CDC) development of JVM-based applications. It is shipped with Contract Definition Language (DSL) written in Groovy or YAML. Contract definitions are used to produce following resources:
* by default JSON stub definitions to be used by WireMock (HTTP Server Stub) when doing integration testing on the client code (client tests). Test code must still be written by hand, test data is produced by Spring Cloud Contract Verifier.
* Messaging routes if you’re using one. We’re integrating with Spring Integration, Spring Cloud Stream and Apache Camel. You can however set your own integrations if you want to.
* Acceptance tests (by default in JUnit or Spock) used to verify if server-side implementation of the API is compliant with the contract (server tests). Full test is generated by Spring Cloud Contract Verifier.
Spring Cloud Contract Verifier moves TDD to the level of software architecture.
To see how Spring Cloud Contract supports other languages just check out this blog post.
## Features
A span is the basic unit of work. For example, sending an RPC is a new span, as is sending
a response to an RPC. Spans are identified by a unique 64-bit ID for the span and another
64-bit ID for the trace of which the span is a part. Spans also have other data, such as
descriptions, key-value annotations, the ID of the span that caused them, and process IDs
(normally IP addresses). Spans are started and stopped, and they keep track of their
timing information. Once you create a span, you must stop it at some point in the future.
A set of spans (which form a tree-like structure) is called a trace. For example, if you
run a distributed big-data store, a trace might be formed by a `PUT` request.
When trying to test an application that communicates with other services then we could do one of two things:
Spring Cloud Sleuth:
* deploy all microservices and perform end to end tests
* mock other microservices in unit / integration tests
Both have their advantages but also a lot of disadvantages. Let’s focus on the latter.
Deploy all microservices and perform end to end tests
Advantages:
* simulates production
* tests real communication between services
Disadvantages:
* to test one microservice we would have to deploy 6 microservices, a couple of databases etc.
* the environment where the tests would be conducted would be locked for a single suite of tests (i.e. nobody else would be able to run the tests in the meantime).
* long to run
* very late feedback
* extremely hard to debug
Mock other microservices in unit / integration tests
Advantages:
* very fast feedback
* no infrastructure requirements
Disadvantages:
* the implementor of the service creates stubs thus they might have nothing to do with the reality
* you can go to production with passing tests and failing production
To solve the aforementioned issues Spring Cloud Contract Verifier with Stub Runner were created. Their main idea is to give you very fast feedback, without the need to set up the whole world of microservices.
Spring Cloud Contract Verifier features:
* ensure that HTTP / Messaging stubs (used when developing the client) are doing exactly what actual server-side implementation will do
* promote acceptance test driven development method and Microservices architectural style
* to provide a way to publish changes in contracts that are immediately visible on both sides of the communication
* to generate boilerplate test code used on the server side
* Adds trace and span IDs to the Slf4J MDC so that you can extract all the logs from a
given trace or span in a log aggregator.
* Provides an abstraction over common distributed tracing data models: traces, spans
(forming a DAG), annotations, and key-value annotations. This is loosely based on HTrace
but is Zipkin (Dapper) compatible.
* Instruments common ingress and egress points from Spring applications (servlet filter,
rest template, scheduled actions, message channels, zuul filters, and the feign client).
* If `spring-cloud-sleuth-zipkin` is available, the app generates and collects
Zipkin-compatible traces over HTTP. By default, it sends them to a Zipkin collector
service on localhost (port 9411). You can configure the location of the service using
`spring.zipkin.baseUrl`.