Spring-cloud-contract: Generate a dependency view of producers and consumers

[marcingrzejszczak]

Dependency Visualization

When keeping contracts in an external repository, and by following the
stubs per consumer feature, we have the full knowledge of who is
calling who within our system. That way we can sketch a graph of dependencies
between applications.

As a reminder, the stubs per consumer feature is all about creating a
consumer subfolder, in each producer's folder. E.g. if consumer baz uses producer foo.bar
then the folder structure would look like this foo/bar/baz/contracts/....

Let's assume that we have such setup (... signifies contract definitions):

├── com
│   └── example
│       └── beer-api-producer-external
│           ├── 1.0.0
│           │   ├── beer-api-consumer
│           │   │   ├── messaging
│           │   │   │   ├── ...
│           │   │   └── rest
│           │   │       ├── ...
│           │   ├── mvnw
│           │   ├── pom.xml
│           └── 2.0.0
│               ├── anotherConsumerOnly
│               │   ├── ...
│               ├── barService
│               │   ├── ...
│               ├── foo.bar.bazService
│               │   ├── ...
│               ├── foo.bar.consumerOnly
│               │   ├── ...
│               ├── foo.bar.fooService.1_2_3
│               │   ├── ...
│               └── pom.xml
└── foo
    └── bar
        ├── barService
        │   ├── pom.xml
        │   └── yetAnotherConsumer
        │       ├── ...
        ├── bazService
        │   ├── bazConsumer1
        │   │   └── rest
        │   │       └── ...
        │   └── pom.xml
        ├── beer-api-consumer
        │   ├── messaging
        │   │   ├── ...
        │   ├── pom.xml
        │   └── rest
        │       ├── ...
        └── fooService
            └── 1.2.3
                ├── ...
                └── pom.xml

We can reason that:

• com.example:beer-api-producer-external in version 2.0.0 is used by 5 consumers
  
  
  
  • foo.bar:bazService
  
  
  • foo.bar:barService
  
  
  • anotherConsumerOnly
  
  
  • foo.bar:fooService in version 1.2.3
  
  
  • foo.bar:consumerOnly
  
  
• com.example:beer-api-producer-external in version 1.0.0 is used by 1 consumer
  
  
  
  • foo.bar:beer-api-consumer
  
  
• foo.bar:bazService is used by 1 consumer
  
  
  
  • bazConsumer1
  
  
• foo.bar:barService is used by 1 consumer
  
  
  
  • yetAnotherConsumer
  
  

This information gives as all data we need to sketch a graph of the dependencies.

_Example of d3 graph_

_Example of Dracula graph_

Storing data

It's enough to execute the https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/master/beer_contracts/src/test/java/docs/GenerateGraphFromContractsTests.java. The test scans the contract structure and builds a graph of relationships between consumers and producers.

It will create a file called relationships.js (https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/master/beer_contracts/relationships.js) that you can source in your HTML file. It will load to a var called relationships the JSON representing the relationships. The JSON consists of source, target pairs where source is the producer and target is the consumer.

There are two example HTML files relationships_d3.html (https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/master/beer_contracts/relationships_d3.html) that uses http://d3js.org/ and relationships_dracula.html (https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/master/beer_contracts/relationships_dracula.html) that uses https://www.graphdracula.net to render the graph.

Assumptions

• You have to use the stubs per consumer feature to sketch a precise graph
  (i.e. each consumer has its own subfolder in the producer's directory)
• If using the producer contract approach (you don't know who your consumers are)
  you can create file .producer_contracts that will tell the test that
  generates data that the subfolders do not represent consumer names
• The folder where the consumers of a given producer lay, needs to have the pom.xml
  or build.gradle file (you need it anyways to, as a consumer, install stubs of the producer)

[ygrenzinger]

Wow very cool (more & more like Pact ;) )
I need to look at the "how to store contracts" (like external repository)

[marcingrzejszczak]

@ygrenzinger the main difference is that you don't need a separate machinery (Pact Broker) to sketch the diagram. We created https://github.com/Codearte/accurest (the predecessor of Spring Cloud Contract) because of the verbosity of Pact and forcing of consumer contract approach. We didn't think that the consumer contract process is efficient.

I'm more than certain that there's a lot of companies where this approach is great and Pact really did an amazing job in promoting Contract Tests. However, we felt we can do sth in a way that better suits our way of doing things.

So in this case, just by following a convention, you can get a graph of dependencies for free. You already use Git, so you don't need to deploy anything else, you don't have to support the code etc. With Spring Cloud Contract we are doing our best to go with as simple solutions as possible. If you're in the Java world you already use Artifactory / Nexus so we just reuse it. With the Git Stub Downloader you don't even need Artifactory / Nexus to store your stubs cause we store it in Git for you.

And for sure that's not the end of enhancements that should be very simple to use and give you more features :)