Developing in a Microservice Environment: Part 1
August 19th, 2015
Microservices are a fundamentally different way of creating your application architecture, which involves creating a stand-alone component for every piece of functionality that you may want to scale separately from the rest of your application. If you have identified microservices as the best solution to the technical problems you are facing, then consider the following collection of helpful guidelines to help you get started in the creation of effective microservice architectures—and hopefully bypass some traps which become apparent only when encountered.
Having worked in a microservice environment for about a year, I’ve come to realize that some of the techniques used to build monolithic software products fall short when developing microservices. Some of the things that eventually become apparent in such an environment are:
- Lack of documentation will kill your team’s productivity, but selecting the correct way to document is just as important.
- Consistent use of best practices are necessary to maintain developers’ sanity.
- Effective communication is extremely important, but too much communication is a detriment.
- Setting up a good development environment is as important as (or even more important than) the development itself.
Following these guidelines will make your life—and the lives of your team members—a lot easier.
NOTE: This is the first post in a four-part series that will explore these guidelines one at a time. Subsequent posts will be linked to the greyed-out items above as they become available.
1. Lack of documentation will kill your team’s productivity
In software engineering, documentation is something that you might overlook if you’re working on a single project. However, in the world of microservice architecture, technical teams that are in the habit of writing good, consistent documentation are the winners. From the very beginning, set a tone that when any important decision is made, it has to be documented in a central location accessible to all the teams. If a set of ranking team members are having a conversation or a meeting, and a major decision is made, there can be no excuse not to document the decision. Lack of documentation can cause major bottlenecks.
Pick one and only one location where all the technical documentation will reside. If you have documentation spread around among your hard drive, Google Drive, Sharepoint, Email, and floppy disk, then you’re doing something wrong. It doesn’t matter that much which system you use to store your documentation, but you have to choose just one. This way, when a team member has to look something up, they have exactly one location to search.
Our Solution: Google Drive
Google has created a very rich set of tools around their online storage solution. One can link the online drive to a local folder that auto-updates as somebody modifies or adds a file. Google has also created some great mobile tools for viewing and creating online documents. The ability to look at modification history for key documentation is also extremely helpful.
The next question might be: What level of documentation should I write? What we found worked in practice was to write three different levels of documentation:
High-level design. This involves major components such as databases, messaging systems, the services themselves, and any clients which will be using those services. You may choose to include a diagram describing how the microservice system fits into the overall technical stack of the company. Here’s an example of a good high-level design:
A mid-level document for each of the services that are being created. This document will detail the specifics of the major components of the service. Each team will use this document to understand the way their service operates, and which technologies it needs to interface with in order to perform its intended functionality. Here’s an example of a mid-level diagram:
Low-level documentation. One component of the low-level documentation is in-line documentation (e.g. javadoc and comments) which should be available for any piece of functionality that is non-trivial to understand. If the service exposes RESTful endpoints, it is very important to create a blueprint for the service’s API that details the inputs and outputs for each of the requests and responses. Make sure to communicate any changes to the blueprints to any of the teams that depend on them. Include a thorough README file that details the steps of setting up and running the service locally. The README might include things like the environment in which one can expect the service to run successfully, including the correct language SDK, OS, and native libraries. Link your README to the results of your CI environment builds: here is how to do that if you’re using Jenkins.
In the next post, I’ll discuss how to identify and implement best practices to maintain developers’ sanity. That post will include advice on common request/response pattern for your API’s, as well as configuring your development and production environments.
