Hexagonal Architecture In Spring Boot

Model the application as use cases that reach the outside world only through interfaces the application itself owns. Spring already supplies a composition root and an injection container, so the real work is deciding which interfaces deserve to exist, binding several implementations to one port unambiguously, and keeping a vendor SDK behind an anti-corruption layer. Add a port only when a second implementation, a volatile dependency, or an expensive test justifies it.

When to use

• Deciding whether a class deserves its own interface, or is a wrapper with one caller.
• One port needs two implementations, such as a real gateway and an in-memory fake.
• A vendor SDK, payment client, or ERP connector is spreading through application code.
• @Qualifier literals are ambiguous, or a bean fails with a type collision.
• A use case test needs a database or HTTP stub and should not.
• A vendor changes their response model, or a second provider is being evaluated.

When not to use

• Ring placement and the dependency rule belong to spring-boot-clean-architecture.
• Aggregate boundaries, value objects, and invariants belong to spring-boot-ddd.
• Package cycle verification and inter-module rules belong to spring-boot-modular-monolith.
• Filter chains, authentication, and authorization belong to spring-boot-security; repositories, projections, and query mechanics belong to spring-boot-data-jpa.