Effective Project Structuring for Microservices with Quarkus

In the ever-evolving landscape of software development, the adoption of microservices architecture is rapidly gaining traction due to its scalability, flexibility, and maintainability. Quarkus, as a Java-Native Kubernetes stack tailored for GraalVM and HotSpot, optimizes Java specifically for containers and enables it to become an effective platform for serverless, cloud, and Kubernetes environments.

Key to leveraging Quarkus effectively is understanding how to structure your project correctly. Proper project structuring not only enhances the manageability of the code but also plays a crucial role in the success of deploying microservices architecture.

Microservices architecture distinguishes itself by several defining characteristics that Quarkus enhances:

1. Small and Focused - each service in a microservices architecture is designed to perform a single, well-defined task, promoting simplicity and focus. Quarkus supports this by facilitating lightweight, bootable jars and native compilations, which are ideal for specific tasks.

2. Independent- independence allows services to be developed, deployed, and even scaled without reliance on other services. Quarkus's container-first philosophy ensures that each microservice can run in its isolated environment.

3. Loosely Coupled- services communicate via well-defined APIs, reducing the dependency on internal implementations. Quarkus encourages decoupling through standards like MicroProfile and JAX-RS, making services interaction seamless and efficient.

4. Scalable- efficiently managing increasing workloads is crucial. Quarkus's reactive programming capabilities enable services to be responsive and scalable under varying loads.

5. Flexible- the ability to adapt to changing conditions is facilitated by the dynamic scaling and resilience features of Quarkus, supporting on-the-fly adjustments in a cloud-native environment.

6. Resilient- Quarkus enhances the robustness of microservices with built-in fault tolerance and health-check capabilities, ensuring the services are resistant to failures and recover swiftly from interruptions.

Adopting Maven multi-module project structures has proven effective in managing large-scale Java applications, and Quarkus fully supports this modality. Let's detail the Maven multi-module structure:

A Maven multi-module project consists of an aggregator POM that orchestrates several submodules. This structure is beneficial for dividing a large application into manageable, independently deployable units that can be maintained and updated with ease. Each module typically has a focused responsibility and can be deployed independently from others.

Here’s a simplified layout based on a real-world application:

parent (aggregator pom.xml)
├── api (API interfaces and DTOs)
│   ├── pom.xml
│   └── src
├── core (Business logic)
│   ├── pom.xml
│   └── src
├── data-access (Data layer integration)
│   ├── pom.xml
│   └── src

I've tailored an optimized project structure specifically for Quarkus that enhances scalability, maintainability, and coherence across diverse development teams. The design, which I originally developed in 2018, has seen several refinements to better suit evolving technological trends. Initially, the structure wasn't specifically crafted with Quarkus in mind; however, throughout its application, it has proven exceptionally compatible with Quarkus's philosophy and coding practices. Let us examine this structure as implemented in an IDE like IntelliJ IDEA - though it could be effectively adapted to any other modern IDE.

You can find the full project structure in the GitHub repository

Starting from the top-level, the project is divided into several modules, each with a specific role:

1. api-dtos- this module is crucial for de-coupling the internal representations of data from what is exposed externally through APIs. By separating Data Transfer Objects (DTOs) from domain models, the module ensures that any changes- be they in database schema or business logic- do not directly affect the clients who consume these APIs. This separation enhances API stability and versioning.

2. commons- this utility module acts as a repository for shared logic, constants, and helpers that are used across multiple other modules in the project. Centralizing common functionalities in this way reduces duplication and fosters consistency throughout the application. It’s particularly helpful for storing utilities like data format converters, standard validators, or common business rules.

3. configuration- configuration management is streamlined in this module, which consolidates all configuration settings for the entire application in one place, simplifying access and management. This central repository of configurations ensures that settings are consistently applied and managed, simplifying environment shifts (such as from development to production) and minimizing the potential for errors due to misconfiguration. Beyond simple configuration files, this module is also the ideal location for defining custom managed beans that are essential across the application, such as ObjectMapper for JSON serializing and deserializing, custom deserializers, and other specialized beans.

4. db-entities- dedicated exclusively to database interactions, this module encapsulates all ORM classes or database schemas, ensuring they are separated from the business logic and API layers. Segregating entities in this manner helps maintain clean architecture principles by decoupling data access mechanisms from business rules processing, hence promoting a cleaner and more traceable codebase.

5. services- here lies the core business logic, encapsulated in service classes that operate on domain models and use db-entities for data persistence. Each service focuses on a specific business task, enhancing modularity and reusability. This separation also aids in isolating business operations from direct client interactions, which are handled by controller classes in other modules, thus adhering to the single responsibility principle.

6. resources- amid some debate, this module was named to reflect its alignment with JAX-RS, where classes annotated with JAX-RS are referred to as resources. This module handles the creation of REST endpoints, acting as the communication layer that interfaces with external clients. The name 'resources' was chosen over alternatives like 'rest' or 'controllers' to emphasize standardization and adherence to established RESTful principles as described in the Red Hat resource for building REST APIs with Quarkus. By aligning with standard terminology, the project aims to be intuitive for developers familiar with JAX-RS and REST conventions.

7. application- serves as an umbrella module that brings all the pieces together, ensuring they are correctly wired and ready to deploy.

Each of these modules plays a strategic role tailored to foster ease of maintenance, scalability, and robustness in a Cloud-Native microservice environment using Quarkus.

The above structure is based on the following Architecture layers which is mentioned in the RedHat resources

Much Abstraction is Too Much

When discussing project structures, a common question arises about the need for the layered approach I previously described. Here, I evoke the words of David J. Wheeler:

All problems in computer science can be solved by another level of indirection, except for the problem of too many layers of indirection. - [David J. Wheeler from The C++ Programming Language 4th edition.]