A Microservice as a House

Introduction

I started working on my first ever microservice during my summer internship after my junior year of college. Back then, I had no idea what a microservice was.

At the end of my internship, I gained some understanding on the topic, but I put my work on pause to complete my college education. I picked it up again as a full-time employee, with the aim of pushing it to production.

After deploying that microservice to production and going through the entire software development life cycle, I thought I'd share some insights around what it means to build a microservice from zero to hero!

Although some explanations might pertain to Golang (which is the programming language I used to build my microservice), this article is targeted to anyone new to microservice development!

Here is a good intro to microservices for those unfamiliar with the concept.

Let's Get Building!

We'll start with the premise that a microservice is a house.

How do we build a house? Here are the high-level steps:

Architecting
Building and inspecting each part iteratively
Final inspection

Let's explore each phase!

Step 1: Architecting

First, what kind of house do we want to build and why? Is it a beach house designed for vacation? A small house for a couple? A mansion for the royal family?

The answers to this question would define the use cases for the project, and the complexity of the project's architecture.

Linking back to our house analogy, an architect's house plan would translate to a software developer's design diagram.

Second, are there any houses similar to what we want to build? If so, don't try to reinvent the wheel. Grab a similar template, move forward with it, and modify it for your own needs. Then, document what components are needed and how they relate to each other.

In my case, my service was a Pulsar subscriber that sends events to the Amazon cloud, so the architecture is straightforward. It's similar to a subscriber service that my colleague has written, so I had a template to move forward with. However, my service has more dependencies than my colleague's. So, having a reference template doesn't mean I can't modify it for my own needs!

Note: learning design patterns also helps prevent developers from unnecessarily reinventing the wheel.

Step 2: Building each part

For simplicity, I'll separate the house into components such as the living room, bedroom, or kitchen.

Each room needs to be carefully built.

First, it needs to have good foundations (pipes, walls, floors, insulation).

Second, the room needs to look pretty.

First, the room needs to have good foundations (pipes, walls, floors, insulation).

A Golang microservice consists of packages, and each package does one task. In the house analogy, a package is similar to a room.

For example, my microservice has a package for subscribing to message, and another package for handling a message.

After working on each part, I need to make sure that my code does what it's supposed to do, which is where unit testing comes into play. More on this in Step 3.

Second, the room needs to look pretty.

Why? We want our rooms to be habitable at the very least. Aesthetic, cozy rooms are a plus.

To start with, the definition of "pretty" is subjective.

But most people would agree that a cluttered room is not pretty. Generally, we don't want five king beds in a small bedroom, and we certainly don't want clothes all over the floor.

Like a house, an application is built by humans, for humans.

A developer wants other developers to understand what they wrote, hence they need to write clean code.

Writing clean code means writing a function (or a library) in place of duplicate code. It also means commenting code where appropriate, and following the coding language's best practices.

Step 3: Inspecting each part

One afternoon at home, I found water dripping on my toes. There was heavy rainfall for the past few days, and the roof was leaking.

Ideally, we should make sure that the roof is water-proof before having anyone live in the house.

To prevent anything like this from happening, we should test an individual part after building it, also known as a unit test.

Moreover, homeowners don't want burglars stealing their stuff. Thus, they may install home alarms that get triggered when an intruder opens the window.

In the coding world, we throw an error when something bad happens.

Back to the house analogy: whenever a burglar tries to open the window, we should make sure that the alarm screams loudly.

Thus, unit tests should also verify that the appropriate error is raised when certain events happen.

Step 4: Repeat Steps 2 and 3

In application development, steps 2 and 3 are done concurrently. Build a part, test it. Then, repeat.

Step 5: Final inspection

Let's say the house is completely built. We've tested each individual part.

In the app development world, there are extra stages to go through before going to production.

I'm going to explain these next steps with house analogies, some of which may not be realistic, but it would be cool if they were!

Functional test

We want the user experience to be seamless.

Functional tests ensure that the sum of the parts work as a whole, without caring how the individual parts work.

For example, we want to make sure that the house entrance and the kitchen are functional.

Thus, a homeowner should be able to open the door with their key, come in to the house, and then cook a meal in the kitchen without anything bad happening.

Security review

Homeowners want a house that is safe.

We want to make sure that the house meets health and safety standards: windows are bulletproof (if need be), the doors have locks, the house is earthquake-proof, and that the home alarms are working.

Load test

This means testing that the house is standing strong under heavy load. Some possible scenarios:

A house party, with more and more people coming inside the house
Simulating rainfall, and gradually increasing its intensity
Simulating earthquakes, and gradually increasing the scale

Recovery test

We want to try to break the house by breaking itself and other things it depends on, and then make sure that the house recovers. An example can help clarify this.

For instance, we could change external factors that adversely affect the house price, like putting the house in a sketchy neighborhood.

Once we see that the house price drops, we return the house to its original location. The house price should return to its normal price.

Now, we can finally put the house for sale!