![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur-layer-1024x1024.png\" "\\"hexagonale_architektur-layer\\"")
<\/figure>\n\n\n\nDie weit verbreitete Schichtenarchitektur mit ihrer dreistufigen Aufteilung in Pr\u00e4sentation, Gesch\u00e4ftslogik und Datenzugriff f\u00fchrt in gr\u00f6\u00dferen Projekten oft zu Problemen:<\/p>\n\n\n\n
- \n
- Technische Abh\u00e4ngigkeiten durchdringen alle Schichten:<\/strong> Greift die Gesch\u00e4ftslogik direkt auf die Datenzugriffsschicht zu, entstehen Abh\u00e4ngigkeiten zu technischen Details, die die Fachlichkeit beeinflussen. H\u00e4ufig zeigt sich das, wenn Datenbankmodelle direkt in der Gesch\u00e4ftslogik genutzt werden. Diese Modelle sind meist nach den Vorgaben der Persistenzschicht entworfen \u2013 z. B. durch Anforderungen von Frameworks wie JPA oder Hibernate, die \u00f6ffentliche Getter und Setter erzwingen. Dadurch k\u00f6nnen fachliche Invarianten unterlaufen werden, und die Logik wird unn\u00f6tig an konkrete Datenbank-Technologien gekoppelt.<\/li>\n\n\n\n
- Schichtengrenzen weichen auf:<\/strong> Unter Zeitdruck neigen Entwickelnde dazu, die Grenzen zwischen den Schichten zu verwischen. Dann kann es passieren, dass Fachlichkeit in der Pr\u00e4sentationsschicht landet oder technische Details in die Gesch\u00e4ftslogik einflie\u00dfen. Der Code der Gesch\u00e4ftslogik wird dadurch zunehmend un\u00fcbersichtlich, wichtige Aspekte sind schwerer erkennbar und k\u00f6nnen bei technischen Anpassungen leicht verloren gehen.<\/li>\n\n\n\n
- Testbarkeit leidet:<\/strong> Gesch\u00e4ftslogik l\u00e4sst sich nicht isoliert ohne technische Abh\u00e4ngigkeiten wie Datenbanken testen.<\/li>\n<\/ul>\n\n\n\n
Das hexagonale Prinzip: Gesch\u00e4ftslogik im Zentrum<\/h2>\n\n\n\n
Genau an diesen Schwachstellen setzt die hexagonale Architektur an und dreht die Perspektive um: Die Gesch\u00e4ftslogik steht im Mittelpunkt, nicht die Daten. Alle technischen Details werden \u00fcber definierte Schnittstellen \u2013 die sogenannten Ports \u2013 nach au\u00dfen abstrahiert und durch Adapter implementiert. Ports sind dabei Teil der Gesch\u00e4ftslogik und werden somit auch fachlich benannt.<\/p>\n\n\n\n
Die Kernidee: Die Anwendung definiert, was sie ben\u00f6tigt (Ports), aber nicht, wie es implementiert wird (Adapter). Dadurch entstehen klare Abh\u00e4ngigkeitsrichtungen: Alle Abh\u00e4ngigkeiten zeigen nach innen zum Anwendungskern. Um das Prinzip greifbarer zu machen, wird zwischen prim\u00e4ren und sekund\u00e4ren Ports unterschieden \u2013 je nachdem, ob die Anwendung gesteuert wird oder selbst andere Systeme ansteuert.<\/p>\n\n\n\n
![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur-grafik001-1024x718.png\" "\\"hexagonale_architektur-grafik001\\"\/")
<\/figure>\n\n\n\nAnwendung<\/h3>\n\n\n\n
In der Praxis bedeutet das: Die Gesch\u00e4ftslogik stellt ihre Use Cases \u00fcber prim\u00e4re Ports bereit und nutzt sekund\u00e4re Ports, um externe Systeme wie bspw. Datenbanken oder Payment-Dienste anzubinden. Dabei bleibt sie vollst\u00e4ndig frei von technischen Abh\u00e4ngigkeiten.<\/p>\n\n\n\n
![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur-grafik002.png-1024x718.png\" "\\"hexagonale_architektur-grafik002.png\\"")
<\/figure>\n\n\n\nBeispiel 1:<\/strong><\/p>\n\n\n\n
\/\/ prim\u00e4rer Port\ninterface UserRegistrationUseCase {\n fun registerUser(user: User): User\n}\n\/\/ sekund\u00e4re Ports\ninterface UserRepository {\n fun add(user: User): User\n fun existsByEmail(email: String): Boolean\n}\ninterface UserNotificationService {\n fun sendWelcomeMessage(user: User)\n}\n\/\/ Gesch\u00e4ftslogik\ndata class User(\n private val id: String,\n private val name: String,\n private val email: String\n) {\n companion object {\n fun create(name: String, email: String): Appointment {\n require(!name.isBlank(), \u201ename must not be blank\u201c)\n require(isMailAddress(email), \u201eemail must be a valid mail adress\u201c)\n return User(UUID.randomUUID().toString(), name, email)\n }\n }\n}\nclass UserRegistrationService(\n private val userRepository: UserRepository,\n private val userNotificationService: UserNotificationService\n) : UserRegistrationUseCase {\n\n override fun registerUser(user: User): User {\n check(!userRepository.existsByEmail(user.email), \"user with that email is already registered\") \n val newUser = userRepository.add(user)\n userNotificationService.sendWelcomeMessage(newUser)\n return newUser\n }\n}<\/code><\/pre>\n\n\n\nAdapter \u2013 Schnittstellen zur Au\u00dfenwelt<\/h3>\n\n\n\n
Adapter setzen die zuvor definierten Ports technisch um. Sie \u00fcbersetzen die fachlichen Schnittstellen der Gesch\u00e4ftslogik in konkrete Technologien \u2013 etwa REST-Controller, Datenbankzugriffe oder Integrationen zu externen Diensten. Damit bleibt die Fachlogik selbst unver\u00e4ndert, auch wenn sich die Infrastruktur oder eingesetzte Frameworks im Laufe der Zeit \u00e4ndern.<\/p>\n\n\n\n
Prim\u00e4re Adapter \u2013 Die Steuerung der Anwendung<\/h4>\n\n\n\n
Prim\u00e4re Adapter bzw. Driving Adapters bilden die technische Anbindung an die Anwendung. Sie steuern den jeweiligen UseCase \u00fcber Aufrufe entsprechender prim\u00e4rer Ports.<\/p>\n\n\n\n
Ein REST-Controller als prim\u00e4rer Adapter \u00fcbersetzt HTTP-Requests in Gesch\u00e4ftsoperationen:<\/p>\n\n\n\n
![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur_bild03-1024x718.png\" "\\"hexagonale_architektur_bild03\\"")
<\/figure>\n\n\n\nBeispiel 2:<\/strong><\/p>\n\n\n\n
@RestController\n@RequestMapping(\"\/api\/users\")\nclass UserRegistrationController(\n private val userRegistrationUseCase: UserRegistrationUseCase\n) {\n\n @PostMapping(\"\/register\")\n fun registerUser(@RequestBody request: UserRegistrationRequest): ResponseEntity<*> {\n try {\n userRegistrationUseCase.registerUser(request.toDomain())\n return ResponseEntity.ok()\n } catch(Exception e) {\n return ResponseEntity.badRequest().body(createErrorResponse(e))\n }\n }\n}<\/code><\/pre>\n\n\n\nSekund\u00e4re Adapter \u2013 Die Anbindung der Infrastruktur<\/h4>\n\n\n\n
Hier kommt das Dependency Inversion Principle zum Einsatz: Die Gesch\u00e4ftslogik definiert die Schnittstelle \u00fcber sekund\u00e4re Ports, die Infrastruktur implementiert sie durch einen sekund\u00e4ren Adapter. Dadurch bleibt die Gesch\u00e4ftslogik unabh\u00e4ngig von konkreten Technologien und kann auch dann bestehen, wenn sich externe Systeme oder Frameworks \u00e4ndern.<\/p>\n\n\n\n
![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur-grafik04.png-scaled.png\" "\\"hexagonale_architektur-grafik04.png\\"\/")
<\/figure>\n\n\n\nBeispiel 3:<\/strong><\/p>\n\n\n\n
class JpaUserRepository(\n private val springDataUserRepository: SpringDataUserRepository\n) : UserRepository {\n\n override fun add(user: User): User {\n val entity = mapToEntity(user)\n val savedEntity = springDataUserRepository.save(entity)\n return savedEntity.toDomain()\n }\n\n override fun existsByEmail(email: String): Boolean {\n return springDataUserRepository.existsByEmail(email) \n }\n}<\/code><\/pre>\n\n\n\nMapping zwischen Schichten \u2013 Eine bewusste Entscheidung<\/h3>\n\n\n\n
Ein zentraler Aspekt der hexagonalen Architektur ist das Mapping zwischen Domain-Objekten und Infrastruktur-Objekten.<\/p>\n\n\n\n
- \n
- Domain-Objekte<\/strong> repr\u00e4sentieren die Fachlogik \u2013 also Begriffe und Regeln aus der Anwendungsdom\u00e4ne, z. B. Order oder Invoice. Sie sind frei von technischen Details.<\/li>\n\n\n\n
- Infrastruktur-Objekte<\/strong> (oder Adapter-Modelle) sind dagegen an Frameworks oder externe Systeme angepasst, z. B. Datenbank-Entities oder DTOs f\u00fcr eine REST-API.<\/li>\n<\/ul>\n\n\n\n
Auch wenn dieses Mapping zun\u00e4chst nach zus\u00e4tzlichem Aufwand aussieht, bietet es entscheidende Vorteile:<\/p>\n\n\n\n
- \n
- Technische Details bleiben au\u00dfen:<\/strong> Annotationen f\u00fcr z. B. Validation-API, JSON-Serialisierung, JPA und andere Framework-spezifische Details sind nur in den Adapter-Modellen vorhanden und beeinflussen nicht die Modelle der Gesch\u00e4ftslogik.<\/li>\n\n\n\n
- Flexibilit\u00e4t bei Technologiewechseln:<\/strong> Ein Wechsel von z. B. REST zu Message-Bus erfordert nur \u00c4nderungen im Adapter.<\/li>\n\n\n\n
- Klare Datenkontrakte:<\/strong> Jede Schicht hat ihre eigenen, optimierten Datenstrukturen.<\/li>\n<\/ul>\n\n\n\n
Allerdings hat dieses Vorgehen auch seinen Preis: F\u00fcr jede Schnittstelle m\u00fcssen Mapping-Logik und Datenkonvertierungen gepflegt werden. In kleineren Projekten kann der Overhead schnell unverh\u00e4ltnism\u00e4\u00dfig wirken \u2013 in komplexeren Anwendungen \u00fcberwiegen jedoch meist die Vorteile.<\/p>\n\n\n\n
Beispiel 4:<\/strong><\/p>\n\n\n\n
data class UserRegistrationRequest(\n @Size(min = 3) val name: String,\n @Email val email: String\n) {\n fun toDomain() = User.create(name = name, email = email)\n}\n\n@Entity\n@Table(name = \"users\")\ndata class UserEntity(\n @Id val id: String,\n @Column(unique = true) val email: String,\n val name: String,\n @Column(name = \"created_at\") val createdAt: LocalDateTime\n) {\n fun toDomain() = User(id = id, name = name, email = email)\n}<\/code><\/pre>\n\n\n\nTesting<\/h3>\n\n\n\n
Ein weiterer Vorteil zeigt sich beim Testen: Durch die klare Abgrenzung lassen sich fachliche Tests unabh\u00e4ngig von der Infrastruktur leicht realisieren.<\/p>\n\n\n\n
Die hexagonale Architektur macht isoliertes Testen elegant m\u00f6glich. Die Gesch\u00e4ftslogik kann vollst\u00e4ndig ohne externe Abh\u00e4ngigkeiten getestet werden, da nur die Port-Schnittstellen durch Mocks ersetzt werden m\u00fcssen.<\/p>\n\n\n\n
Beispiel 5:<\/strong><\/p>\n\n\n\n
class UserRegistrationServiceTest {\n\n private val mockUserRepository = mockk<UserRepository>()\n private val mockUserNotificationService = mockk<UserNotificationService>()\n private val userRegistrationService = UserRegistrationService(\n mockUserRepository, \n mockUserNotificationService\n )\n\n @Test\n fun `sollte Benutzer erfolgreich registrieren`() {\n \/\/ Arrange\n val user = User (email = \"test@example.com\", name = \"Test User\")\n every { mockUserRepository.existsByEmail(user.email) } returns false\n every { mockUserRepository.save(any()) } returnsArgument 0\n every { mockUserNotificationService.sendWelcomeMessage(any()) } just Runs\n\n \/\/ Act\n userRegistrationService.registerUser(user)\n\n \/\/ Assert\n verify { mockUserRepository.save(any()) }\n verify { mockEmailService.sendWelcomeMessage(user) }\n }\n}<\/code><\/pre>\n\n\n\nVorteile f\u00fcr nachhaltige Softwareentwicklung<\/h3>\n\n\n\n
Die hexagonale Architektur bietet konkrete Vorteile f\u00fcr die langfristige Wartbarkeit von Software:<\/p>\n\n\n\n
- \n
- Flexibilit\u00e4t bei Technologie-Entscheidungen:<\/strong> Frameworks oder externe APIs k\u00f6nnen ausgetauscht werden, ohne die Gesch\u00e4ftslogik anzufassen.<\/li>\n\n\n\n
- Bessere Testbarkeit:<\/strong> Gesch\u00e4ftslogik ist vollst\u00e4ndig isoliert testbar.<\/li>\n\n\n\n
- Klarere Strukturen:<\/strong> Fachliche und technische Aspekte sind klar getrennt, insbesondere ist die Gesch\u00e4ftslogik leichter fassbar und damit wartbarer.<\/li>\n\n\n\n
- Parallelentwicklung:<\/strong> Teams k\u00f6nnen parallel an Adaptern und Gesch\u00e4ftslogik arbeiten, sobald die Schnittstellen durch Ports festgelegt sind.<\/li>\n\n\n\n
- Reduzierte technische Schulden:<\/strong> Upgrades und Refactorings werden weniger riskant.<\/li>\n<\/ul>\n\n\n\n
Wann lohnt sich der Einsatz?<\/h3>\n\n\n\n
Trotz dieser Vorteile ist die hexagonale Architektur nicht f\u00fcr jedes Projekt die richtige Wahl. Sie eignet sich besonders f\u00fcr:<\/p>\n\n\n\n
- Bessere Testbarkeit:<\/strong> Gesch\u00e4ftslogik ist vollst\u00e4ndig isoliert testbar.<\/li>\n\n\n\n
- Flexibilit\u00e4t bei Technologiewechseln:<\/strong> Ein Wechsel von z. B. REST zu Message-Bus erfordert nur \u00c4nderungen im Adapter.<\/li>\n\n\n\n
- Infrastruktur-Objekte<\/strong> (oder Adapter-Modelle) sind dagegen an Frameworks oder externe Systeme angepasst, z. B. Datenbank-Entities oder DTOs f\u00fcr eine REST-API.<\/li>\n<\/ul>\n\n\n\n
- Schichtengrenzen weichen auf:<\/strong> Unter Zeitdruck neigen Entwickelnde dazu, die Grenzen zwischen den Schichten zu verwischen. Dann kann es passieren, dass Fachlichkeit in der Pr\u00e4sentationsschicht landet oder technische Details in die Gesch\u00e4ftslogik einflie\u00dfen. Der Code der Gesch\u00e4ftslogik wird dadurch zunehmend un\u00fcbersichtlich, wichtige Aspekte sind schwerer erkennbar und k\u00f6nnen bei technischen Anpassungen leicht verloren gehen.<\/li>\n\n\n\n