Spring Boot Best Practices: 16 Tips for Building Robust Micro‑services

Spring Boot is the most popular Java framework for developing micro‑services. Since 2016 the author has gathered a set of best‑practice recommendations based on personal experience and insights from other Spring Boot experts.

The article lists sixteen best practices, most of which also apply to plain Spring projects.

1. Use a custom BOM to manage third‑party dependencies – Large projects often depend on libraries not covered by Spring Boot’s built‑in management. Creating a platform‑BOM (similar to Spring IO Platform) and importing it in each module lets you upgrade versions in a single place.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.spring.platform</groupId>
            <artifactId>platform-bom</artifactId>
            <version>Cairo-SR3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2. Leverage Spring Boot’s auto‑configuration – Auto‑configuration activates when specific JARs are on the classpath. The simplest way to use it is by adding Spring Boot Starters, e.g., the Redis or MongoDB starters.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>

If you need to exclude a specific auto‑configuration class, use @EnableAutoConfiguration with the exclude attribute, but only when absolutely necessary.

@EnableAutoConfiguration(exclude = {ClassNotToAutoconfigure.class})

3. Start new projects with Spring Initializr – The web UI (https://start.spring.io) generates a ready‑to‑run project with the selected dependencies, ensuring you begin with tested and compatible versions.

4. Create custom auto‑configuration for common organisational concerns – In teams heavily invested in Spring Boot, a shared auto‑configuration library can encapsulate recurring setup, reducing duplication and easing onboarding.

5. Design a clear source‑code package structure – Avoid the default package, keep the main Application.java at the top level, and group controllers and services by feature or functional module.

6. Keep @Controller classes simple and focused – Controllers should be stateless, delegate business logic to services, handle only HTTP concerns, and be organised around use‑cases.

7. Build @Service beans around business capabilities – Name services after the domain concept they implement (e.g., AccountService, UserService) and allow services to call each other when appropriate.

8. Decouple database access from core business logic – Follow “Clean Architecture” principles: treat the database as a detail, hide persistence behind abstractions, and avoid leaking database specifics into services.

9. Protect business logic from Spring‑specific code – Keep core domain code free of Spring annotations so it remains reusable and testable outside the framework.

10. Prefer constructor injection – Constructor injection (optionally with @Autowired) makes beans easier to instantiate in tests without a Spring context.

11. Understand the concurrency model – Controllers and services are singletons; be aware of thread‑pool limits and potential race conditions, especially when using WebFlux/Reactor.

12. Externalise configuration management – Use a configuration server (e.g., Spring Cloud Config) or environment‑variable‑based configuration to manage settings across multiple services.

13. Provide global exception handling – Implement a HandlerExceptionResolver or use @ExceptionHandler on controllers for consistent error responses.

14. Use a proper logging framework – Obtain a logger via SLF4J/Logback instead of System.out.println, allowing flexible log levels. Logger logger = LoggerFactory.getLogger(MyClass.class); 15. Write tests for your code – Unit and integration tests prevent legacy code accumulation and reduce risk when services evolve.

16. Use Spring Boot test slices to focus tests – Test slices load only the parts of the application needed for a particular test, speeding up execution and reducing unnecessary context loading.

By following these practices, developers can create Spring Boot‑based micro‑services that are easier to maintain, scale, and evolve.