Designing Hexagonal Architecture with Java An architects guide to building maintainable and change-tolerant applications with… (Davi Vieira)（Z-Library）

【One-Line Pitch】 A hands-on architecture guide that shows Java developers how to keep business logic independent of frameworks by building a real system with Domain, Application, and Framework hexagons, then shipping it as a cloud-native Quarkus service. Best for architects and intermediate Java developers tired of codebases where every new feature triggers a cascade of refactoring. 【Book Arc】 - **Opening (~0%–10%)**: Frames the problem — technical debt and tangled business/technology code — and introduces Alistair Cockburn's hexagonal idea, the three-hexagon topology, and why change-tolerance and testability matter. - **Early (~10%–35%)**: Builds the Domain hexagon: entities, value objects with constructor guards, specifications and policy patterns, and business rules expressed as plain POJOs rather than container-managed beans. - **Early–Middle (~35%–50%)**: Moves into the Application hexagon — use cases, input ports, and output ports — arguing that ports describe communication with *any* external system, not just databases. - **Middle (~50%–65%)**: Implements adapters on both sides: input adapters exposing features over REST/gRPC/WebSocket, and output adapters (e.g., an H2 persistence adapter) with explicit domain-to-data mapping. - **Late (~65%–85%)**: Explores driving vs. driven operations, integration testing of the hexagonal system, and using Java modules to enforce dependency inversion and hexagon isolation. - **Ending (~85%–100%)**: Turns the application cloud-native with Quarkus — dependency injection for port lifecycles and framework wiring — closing the loop from theory to a deployable system. (Excerpts thin out here; exact chapter boundaries are not fully covered.) 【Key Takeaways】 - **Separate business code from technology code** (Opening): The whole book rests on Cockburn's observation that some code exists only to solve business problems while other code exists only to integrate technologies — mixing them is the root of maintenance pain. - **Three hexagons structure the system** (Early): Domain holds entities and rules, Application holds use cases and ports, Framework holds adapters; each boundary is a seam where technology can be swapped without touching business logic. - **Value objects guard their own validity** (Early): Constructors validate inputs (e.g., IP format, minimum CIDR) so clients never carry validation burden — a small pattern with outsized payoff for domain integrity. - **Specifications and policies make rules composable** (Early): Implementing `Specification` with `AndSpecification` lets business rules be combined and reused, and modeling rules as POJOs avoids the heavyweight EJB-era coupling the author critiques. - **Output ports are broader than repositories** (Middle): A port should express communication with any external system — database, messaging, filesystem — not presume persistence; framework-flavored repository interfaces (e.g., Spring's `JpaRepository`) blur this line. - **Adapters translate, they don't leak** (Middle): Input adapters expose use cases over REST/gRPC/WebSocket; output adapters map between domain objects and data/JSON representations, keeping domain types out of the transport layer. - **Java modules enforce the architecture** (Late): Module boundaries mechanically reinforce dependency inversion and hexagon isolation, turning architectural intent into compiler-checked constraints. - **Quarkus completes the cloud-native story** (Ending): DI manages port and adapter lifecycles, letting the same hexagonal core run as a cloud-native service — the practical payoff of all the decoupling. 【Reading Tips】 - Deep-read the Domain and Application chapters (~10%–50%): the value-object, specification, and port patterns are the reusable core; skim repetitive code listings once you grasp the shape. - Treat the adapter chapters as a template, not a script — the H2/JSON mapping examples are illustrative; adapt the mapping discipline to your own persistence stack. - Watch for the driving-vs-driven distinction (~50%–65%); it's the conceptual hinge for deciding which side a new integration belongs on. - If you're Quarkus-averse, read the final section for the DI/wiring ideas and translate them to Spring or plain Java — the architecture is framework-agnostic even though the book isn't. - Do the exercises/questions at chapter ends; this is a build-along book, and the patterns stick only when typed out. 【Coverage Limits】 Excerpts are uneven — the Domain, ports, and adapter material is well represented, but the Java modules and Quarkus sections are only glimpsed, so this guide cannot detail their specific APIs or chapter structure.