Java Microservices: A Practical Guide

Imagine you are working for a bank or a fintech start-up. You provide users a mobile app, which they can use to open up a new bank account.

In Java code, this will lead to a controller class that looks, simplified, like the following.

You’ll want to:

Your BankController class will be packaged up, with all your other source code, into a bank.jar or bank.war file for deployment: A good, old monolith, containing all the code you need for your bank to run. (As a rough pointer, initially your .jar/.war file will have a size in the range of 1-100MB).

On your server, you then simply run your .jar file - that’s all you need to do to deploy Java applications.

At its core, there’s nothing wrong with a Java monolith. It is simply that project experience has shown that, if you:

Then your small bank.jar file, turns into a gigabyte large code monster, that everyone fears deploying.

This naturally leads to the question of how to get the monolith smaller. For now, your bank.jar runs in one JVM, one process on one server. Nothing more, nothing less.

Now you could come up with the idea to say: Well, the risk check service is being used by other departments in my company and it doesn’t really have anything to do with my Mono(lithic) Bank domain, so we could try and cut it out of the monolith and deploy it as its own product, or more technically, run it as its own Java process.

In practical terms, this means that instead of calling the riskCheck() method inside your BankController, you will move that method/bean with all its helper classes to its own Maven/Gradle project, put it under source control and deploy it independently from your banking monolith.

That whole extraction process does not make your new RiskCheck module a microservice per se and that is because the definition of microservices is open for interpretation (which leads to a fair amount of discussion in teams and companies).

Instead of theorizing about it, we’ll keep things pragmatic and do two things:

So, to sum up: Before you had one JVM process, one Banking monolith. Now you have a banking monolith JVM process and a RiskCheck microservice, which runs in its own JVM process. And your monolith now has to call that microservice for risk checks.

How do you do that?

You basically have two choices: synchronous communication or asynchronous communication.

Assuming we chose to go with synchronous microservice communication, our Java code from above would then look something like this on a low-level. Low-level, because for microservice communication you usually create client libraries, that abstract the actual HTTP calls away from you.

Looking at the code it becomes clear, that you now must deploy two Java (micro)services. Your Bank and your RiskCheck service. You are going to end up with two JVMs, two processes. The graphic from before will look like this:

That’s all you need to develop a Java Microservices project: Build and deploy smaller pieces (.jar or .war files), instead of one large piece.

But that leaves the question: How exactly do you cut or setup those microservices? What are these smaller pieces? What is the right size?

Let’s do a reality check.

One rather organic idea is to break microservices out of an existing monolith. Note, that "micro" here does not actually mean that the extracted services themselves will, indeed, be micro - they could still be quite large themselves.

Let’s look at some theory.

Things look a bit different when developing new, greenfield Jav aprojects. Now, those three points from above look a bit different:

This leads to various ways that companies try and tackle greenfield Java microservices projects.

The next common approach is, to module your Java microservices after your workflow.

Real-Life example: In Germany, when you go to a (public) doctor he needs to record your appointment in his health software CRM.

To get paid from the insurance he will send in your treatment data and that of all other patients he treated to an intermediary via XML.

The intermediary will have a look at that XML file and (simplified):

If you now try and model this workflow with microservives, you will end up with at least.

Note: Communication between Microservices is irrelevant in this example, but could well be done asynchronously with a message broker like RabbitMQ, as the doctor does not get immediate feedback, anyway.

Again, this is something that looks good on paper, but immediately leads to several questions:

Interestingly, for some architects the above diagram reads simpler, because every service now has its exact, well-defined purpose. Before, it looked like this scary monolith:

While arguments can be made about the simplicity of those diagrams, you now definitely have these additional operational challenges to solve.

You…​

Recommendation:

Unless:

→ Don’t do it.

In less hyperbole, though.

Trying to model microservices after domain boundaries is a very sensible approach. But a domain boundary (say user management vs invoicing) does not mean taking a single workflow and splitting it up into its tiniest individual pieces (receive XML, validate XML, forward XML).

Hence, whenever you are starting out with a new Java microservices project and the domain boundaries are still very vague, try to keep the size of your microservices on the lower end. You can always add more modules later on.

And make sure that you have exceptionally strong DevOps skills across your team/company/division to support your new infrastructure.

There is a third, almost libertarian approach to developing microservices: Giving your teams or even individuals the possibility to implement user stories with as many languages or microservices they want (marketing term: polyglot programming).

So the XML Validation service above could be written in Java, while the Plausibility Microservice is written in Haskell (to make it mathematically sound) and the Insurance Forwarding Microservice should be written in Erlang (because it really needs to scale ;) ).

What might look like fun from a developer’s perspective (developing a perfect system with your perfect language in an isolated setting) is basically never what an organization wants: Homogenization and standardization.

That means a relatively standardized set of languages, libraries and tools so that other developers can keep maintaining your Haskell microservice in the future, once you are off to greener pastures.

What’s interesting: Historically standardization went way too far. Developers in big Fortune 500 companies were sometimes not even allowed to use Spring, because it was 'not in the company’s technology blueprint'. But going full-on polyglot is pretty much the same thing, just the other side of the same coin.

Recommendation : If you are going polyglot, try smaller diversity in the same programming language eco-system. Example: Kotlin and Java (JVM-based with 100% compatibility between each other), not Haskell and Java.

Continuing with the bank example, we ended up with our monobank.jar file (the monolith) and our freshly extracted riskengine.jar (the first microservice).

Let’s also assume that both applications, just like any other application in the world, need a .properties file, be it just the database url and credentials.

A bare minimum deployment could hence consist of just two directories, that look roughly like this:

This leaves open the question: How do you get your .properties and .jar file onto the server?

Unfortunately, there’s a variety of alluring answers to that question.

The boring, but perfectly fine answer to Java microservice deployments is how admins deployed any Java server-side program in companies in the past 20 years. With a mixture of:

If you are not fixated on creating a breathing cloud of ever auto-load-balancing servers, chaos monkeys nuking your machines, or the warm and fuzzy-feeling of seeing ZooKeeper’s leader election working, then this setup will take you very far.

Oldschool, boring, but working.

Back to the alluring choices. A couple of years ago, Docker or the topic of containerization hit the scene.

If you have no previous experience with it, this is what it is all about for end-users or developers:

Interestingly, with the JVM’s portability and backwards compatibility this doesn’t sound like major benefits. You could just download a JVM.zip on any server, Raspberry Pi (or even mobile phone), unzip it and run any .jar file you want.

It looks a bit different for languages like PHP or Python, where version incompatibilities or deployment setups historically were more complex.

Or if your Java application depends on a ton of other installed services (with the right version numbers): Think of a database like Postgres or key-value store like Redis.

So, Docker’s primary benefit for Java microservices, or rather Java applications lies in:

If your deployables look similar or you want to run a nice, little Oracle database on your development machine, give Docker a try.

So, to sum things up, instead of simply scp’ing a .jar file, you will now:

Let’s say you are giving Docker a try. Every time you deploy your Java microservice, you now create a Docker image which bundles your .jar file. You have a couple of these Java microservices and you want to deploy these services to a couple of machines: a cluster.

Now the question arises: How do you manage that cluster, that means run your Docker containers, do health checks, roll out updates, scale (brrrr)?

Two possible answers to that question are Docker Swarm and Kubernetes.

Going into detail on both options is not possible in the scope of this guide, but the reality takeaway is this: Both options in the end rely on you writing YAML files (see Not a question: Yaml Indentation Tales) to manage your cluster. Do a quick search on Twitter if you want to know what feelings that invokes in practice.

So the deployment process for your Java microservices now looks a bit like this:

Let’s assume you solved deploying microservices in production, but how do you integration test your n-microservices during development? To see if a complete workflow is working, not just the single pieces?

In practice, you’ll find three different ways:

Furthermore, in addition to your Java microservices, you’ll likely also need an up and running message broker (think: ActiveMQ or RabbitMQ) or maybe an email server or any other messaging component that your Java microservices need to communicate with each other.

This leads to a fair amount of underestimated complexity on the DevOps side. Have a look at Microservice Testing Libraries to mitigate some of that pain.

In any case, this complexity leads us to common Microservice issues:

To recap, when building microservices, you are essentially swapping out JVM method calls with synchronous HTTP calls or asynchronous messaging.

Whereas a method call execution is basically guaranteed (with the exception of your JVM exiting abruptly), a network call is, by default, unreliable.

It could work, it could also not work for various reasons: From the network being down or congested, to a new firewall rule being implemented to your message broker exploding.

To see what implications that has, let’s have a look at an exemplary BillingService example.

On one hand you have established and very popular choices like Spring Boot, which makes it very easy to build .jar files that come with an embedded web server like Tomcat or Jetty and that you can immediately run anywhere. A perfect fit for building microservice applications.

Recently though, and partially inspired by parallel developments like reactive programming, Kubernetes or GraalVM, a couple of, dedicated microservice frameworks have arisen.

To name a few: Quarkus, Micronaut, Vert.x, Helidon.

In the end, you will have to make your own choice, but this article can give some, maybe unconventional, guidance:

With the exception of Spring Boot, all microservices frameworks generally market themselves as blazingly fast, monumentally quick startup time, low memory footprint, able to scale indefinitely, with impressive graphs comparing themselves against the Spring Boot behemoth or against each other.

This is clearing hitting a nerve with developers who are maintaining legacy projects that sometimes take minutes to boot-up or cloud-native developers who want to start-stop as many micro-containers as they now can or want they need in 50ms.

The issue, however, is that (artificial) bare metal startup times and re-deploy times barely have an effect on a project’s overall success, much less so than a strong framework ecosystem, strong documentation, community and strong developer skills.

You’ll have to look at it this way.

If until now:

Then adding additional Microservice challenges (think: resilience, network, messaging, DevOps, infrastructure) on top will have a much heavier impact on your project, than booting up an empty hello world. And for hot redeploys during development, you finally might want to look into solutions like JRebel or DCEVM.

To go back to Simon Brown’s quote: If people cannot build (fast & efficient) monoliths, they will be having a hard time building (fast & efficient) microservices - no matter the framework.

So, choose your framework wisely.

On to the more practical aspects of calling HTTP REST APIs. On the low-level technical side, you are probably going to end up with one of the following HTTP client libraries:

Java’s own HttpClient (since Java 11), Apache’s HttpClient or OkHttp.

Note that I am saying 'probably' here because there is a gazillion other ways as well, from good old JAX-RS clients to modern WebSocket clients.

In any case, there is a trend towards HTTP client generation, instead of messing around with HTTP calls yourself. For that, you want to have a look at the OpenFeign project and its documentation as a starting point for further reading.

Starting out with asynchronous messaging, you are likely going to end up with either ActiveMQ (Classic or Artemis), RabbitMQ or Kafka. Again, this is just a popular pick.

Here’s a couple of random points, though:

To get a better understanding on when to use RabbitMQ( or traditional message brokers in general) or Kafka, have a look at Pivotal’s matching blog post as a starting point.

In general, though, try to dismiss any artificial performance reasons when choosing your broker. There was a time when teams and online communities argued a ton about how fast RabbitMQ was and how slow ActiveMQ was.

Now you are having the same arguments on RabbitMQ being slow with just a consistent 20-30K/messages every.single.second. Kafka is cited with 100K messages/a second. For one, these kinds of comparisons conveniently leave out that you are, in fact, comparing apples and oranges.

But even more so: Both throughput numbers might be on the lower or medium side for Alibaba Group, but you author has never seen projects of this size (millions of messages every minute) in the real world. They definitely exist, but these numbers are nothing to worry about for the other 99% of regular Java business projects.

So, ignore the hype and choose wisely.

Depending on your stack you might end up using Spring specific tools (Spring ecosystem), or something like Arquillian (JavaEE ecosystem).

(Check out e.g. this course to get a deep dive into the Spring testing ecosystem,a ton of different testing libraries and the corresponding test-driven workflows. Note: I’m affiliated with the author.)

You’ll also want to have a look at Docker and the really good Testcontainers library, that helps you , for example, easily and quickly setup an Oracle database for your local development or integration tests.

For mocking out whole HTTP servers, have a look at Wiremock. For testing asynchronous messaging, try to embedding (ActiveMQ) or dockering (RabbitMQ) and then writing tests with the Awaitility DSL.

Other than that, all your usual suspects apply, like Junit, TestNG to AssertJ and Mockito.

Note that this is by no means a comprehensive list and if you are missing your favorite tool, post it in the comments section and I’ll pick it up in the next revision of this guide.

Logging with microservices is an interesting and rather complex topic. Instead of having one log file that you can less or grep, you now have n-log files, that you would like to see combined.

A great starting point for the whole logging ecosystem is this article. Make sure to read it, especially the Centralized Logging section in terms of microservices.

In practice, you’ll find various approaches:

So far, we kind of assumed that our microservices all know each other, know their corresponding IPS. More of a static setup. So, our banking monolith[ip=192.168.200.1] knows that he has to talk to the risk server[ip=192.168.200.2], which is hardcoded in a properties file.

You can, however, choose to make things much more dynamic:

In general terms, this is what’s called microservice orchestration and another huge topic by itself.

Libraries like Eureka or Zookeeper try to 'solve' these problems, like clients or routers knowing which services are available where. On the other hand, they introduce a whole lot of additional complexity.

Just ask anyone who ever ran a ZooKeeper setup.

Another huge topic, worth its own essay. Again, options range from hardcoded HTTPS basic auth with self-coded security frameworks, to running an Oauth2 setup with your own Authorization Server.

What’s true for non-microservice deployments is also true for microservice deployments. You will try a combination of Docker/Testcontainers as well as scripting/Ansible.

Try and keep it simple.

Making a hard cut from specific library questions, let’s have a quick look at Yaml. It is the file format being used as the de-facto file format to 'write configuration as code'. From simpler tools like Ansible to the mighty Kubernetes.

To experience YAML indentation pain yourself, try and write a simple Ansible files and see how often you need to re-edit the file to get indentation working properly, despite various levels of IDE support. And then come back to finish off this guide.

Unfortunately, those topics didn’t make it in this revision of this guide. Stay tuned for more.

Something that occurs in many microservice projects, is what I would call the frontend-backend microservice mismatch. What does that mean?

That in good old monoliths, frontend developers had one specific source to get data from. In microservice projects, frontend developers suddenly have n-sources to get data from.

Imagine you are building some Java-IoT microservices project. Say, you are surveilling machines, like industry ovens across Europe. And these ovens send you regular status updates with their temperatures etc.

Now sooner or later, you might want to be able to search for ovens in an admin UI, maybe with the help of a "search oven" microservices. Depending on how strict your backend colleagues might interpret domain driven design or microservice laws it could be that the "search oven" microservice only returns you IDs of ovens, no other data, like its type, model or location.

For that, frontend developers might have to do one or n-additional calls (depending on your paging implementation), to a "get oven details" microservice, with the ids they got from the first microservice.

And while this only a simple (but taken from a real-life project(!)) example, it demonstrates the following issue:

Real-life supermarkets got huge acceptance for a reason. Because you don’t have to go to 10 different places to shop vegetables, lemonade, frozen pizza and toilet paper. Instead you go to one place.

It’s simpler and faster. It’s the same for frontend developers and microservices.

This issue is something that is an unfortunate side-effect of individual developers, programming magazines or cloud companies pushing microservices:

Management having the impression that you now can pour in an infinite amount of developers into the (overarching) project, as developers can now work completely independent from each other, everyone on their own microservice. With just some tiny integration work needed, at the very end (i.e. shortly before go-live).

Let’s see why this mindset is such an issue in the next paragraphs.

One rather obvious issue is, that 20 smaller pieces (as in microservices) does not actually mean 20 better pieces. Purely from a technical quality perspective, it could mean that your individual services still execute 400 Hibernate queries to select a User from a database across layers and layers of unmaintainable code.

To go back to Simon Brown’s quote, if people cannot build monoliths properly, they will be having a hard time building proper microservices.

Especially resilience and everything that happens after the go-live is such an afterthought in many microservice projects, that it is somewhat scary to see the microservices running live.

This has a simple reason though: Because Java developers usually are not interested not trained properly in resilience, networking and other related topics.

In addition, there’s the unfortunate tendency for user stories to get more and more technical (and therefore stupid), the more micro and abstracted away from the user they get.

Imagine your microservice team is asked to write a technical, login-against-a-database-microservice which is roughly this:

Now your team might decide (and maybe even convince businesspeople): That is way too simple and boring, instead of a login service, let’s write a really capable UserStateChanged microservice - without any real, tangible business requirements.

And because Java is currently out of fashion, let’s write the UserStateChanged microservice in Erlang. And let’s try to use red-black trees somewhere, because Steve Yegge wrote you need to know them inside-out to apply for Google.

From an integration, maintenance and overall-project perspective, this is just as bad as writing layers of spaghetti code inside the same monolith.

Fabricated and over-the-top example? Yes.

Unfortunately, also not uncommon in real-life.

Then there’s this topic of understanding the complete system, its processes and workflows, if you as a developer are only responsible to work on isolated microservice[95:login-101:updateUserProfile].

It blends in with the previous paragraph, but depending on your organization, trust and communication levels, this can lead to a lot of shoulder-shrugging and blaming, if a random part of the whole microservice chain breaks down - with no-one accepting full responsibility anymore.

Not just insinuating bad faith, but the problem that it actually is really difficult to understand n-amount of isolated pieces and their place in the big picture.

Which blends in with the last issue here: Communication & Maintenance. Which obviously depends heavily on company size, with the general rule: The bigger, the more problematic.

The overarching theme here is, that similarly to DevOps skills, a full-on microservices approach in a bigger, maybe even international company, comes with a ton of additional communication challenges. As a company, you need to be prepared for that.

Going full-on Java microservices is one end of a pendulum. The other end would be something like hundreds of good old Maven modules in a Monolith. You’ll have to strike the right balance.

Especially in greenfield projects there is nothing stopping you from taking a more conservative, monolithic approach and building fewer, better-defined Maven modules instead of immediately starting out with twenty, cloud-ready Microservices.

Keep in mind that, the more microservices you have, and the less really strong DevOps talent you have (no, executing a few Ansible scripts or deploying on Heroku does not count), the more issues you will have later on in production.

Reading through the Common Java Microservice Questions section of this guide is already exhausting. Then think about implementing solutions for all these infrastructure challenges. You’ll suddenly realize that none of this has to do with business programming anymore (what you are paid for), but rather with a fixation of more technology on even more technology.

Siva summed it up perfectly on his blog:

To answer that question, I’d like to end this article with a very cheeky, Google-like interview teaser. If you know the answer to this question by experience even though it seemingly has nothing to do with microservices, then you might be ready for a microservices approach.

If you are still here with me: Thanks for reading!