Cooking your Ravioli "al dente" with Hexagonal Architecture

Cooking your Ravioli "al dente"
with Hexagonal Architecture

Jeroen Rosenberg
● Software Consultant @ Xebia
● Founder of Amsterdam Scala
● Currently doing Kotlin & Java projects
● Father of three
● I like Italian food :)
@jeroenrosenberg
jeroenr
https://jeroenrosenberg.medium.com

Agenda
● What is Hexagonal Architecture?
● Why should I care?
● How is cooking Ravioli “al dente” relevant?

Domain gets cluttered
● By 3rd party integrations (dependency on API version)
● By dependency on persistence layer and framework
● By using application frameworks or SDKs

@Service
class DepositService(
val userRepo: UserRepository,
val userAccountRepo: UserAccountRepository,
val exchangeApiClient: ExchangeApiClient,
val eventBus: EventBus
) {
fun deposit(userId: String, amount: BigDecimal, currency: String){ ... }
}

@Service
class DepositService(…) {
@Transactional
fun deposit(userId: String, amount: BigDecimal, currency: String){
require(amount > BigDecimal.ZERO) { “Amount must be larger than 0” }
require(Currencies.isSupported(currency)) { “$currency is not supported”}
userRepo.findById(userId)?.let { user ->
userAccountRepo.findByAccountId(user.accountId)?.let { account ->
val rateToUsd = if (currency != “USD”) {
exchangeApiClient.getRate(RateRequest(currency, “USD”)).rate
} else { 1.0 }
val rateToPref = if (account.currency != “USD”) {
exchangeApiClient.getRate(RateRequest(“USD”, account.currency)).rate
} else { 1.0 }
val oldBalance = account.balance
account.balance += amount * rateToUsd.toBigDecimal() * rateToPref.toBigDecimal()
userAccountRepo.save(account)
val update = BalanceUpdate(
userId, oldBalance, account.balance
)
eventBus.publish(ProducerRecord(“balance-updates”, update))
}
}
}
}

@Service
@Transactional
} else { 1.0 }
} else { 1.0 }
)
}
}
}
}
Entity (Proxy)

@Service
@Transactional
} else { 1.0 }
} else { 1.0 }
)
}
}
}
}
Dependency on API version

@Service
@Transactional
} else { 1.0 }
} else { 1.0 }
)
}
}
}
}
Orchestration

Issues
● Testability: not unit testable or requires lots of mocking

Issues
● API/Platform version dependency
○ What if you need to support multiple platform versions?
○ What if API versions change?

Issues
● Orchestration mixed with business logic is hard to maintain

Issues
● Orchestration mixed with business logic is hard to maintain
● Mutability leads to mistakes

Application
Programmable
Interface
Service
Provider
Interface

Ports
● Interface
● Tech agnostic
● Designed around
purpose of
interaction

Adapters
● Allow interaction
through a
particular port
● Use a particular
technology

“so as to be still ﬁrm when bitten”
Al dente
/al ˈdɛnteɪ,al ˈdɛnti/
adverb

When you push modularity too far...
● Coupling is too loose
● Low cohesion
● Bloated call stacks
● Navigation through code will be more difficult
● Transaction management will be hard

How do we determine our domain?

“A particular ﬁeld of thought, activity or interest”
domain
/də(ʊ)ˈmeɪn/
noun

What an organisation does

How an organisation does it

Bounded Context
● A distinct part of the domain
● Split up domain in smaller, independent models with clear boundaries
● No ambiguity
● Could be separate module, jar, microservice
● Context mapping DDD pattern (https://www.infoq.com/articles/ddd-contextmapping/)

Using the building blocks of DDD
● Value objects
● Entities
● Domain services
● Application services

Value objects
● Deﬁned by their value
● Immutable
● Thread-safe and side-effect free
● Small and coherent
● Contain business logic that can be
applied on the object itself
● Contain validation to ensure its value
is valid
● You will likely have many

Value objects
● Deﬁned by their value
● Immutable
● Thread-safe and side-effect free
● Small and coherent
● Contain business logic that can be
applied on the object itself
● Contain validation to ensure its value
is valid
● You will likely have many
enum class Currency { USD, EUR }
data class Money(
val amount: BigDecimal,
val currency: Currency,
) {
fun add(o: Money): Money {
if(currency != o.currency)
throw IllegalArgumentException()
return Money(
amount.add(o.amount),
currency
)
}
}

Entities
● Deﬁned by their identiﬁer
● Mutable
● You will likely have a few

Entities
● Deﬁned by their identiﬁer
● Mutable
● You will likely have a few
@Document
data class UserAccount(
@Id
val _id: ObjectId = ObjectId(),
var name: String,
var createdAt: Instant = Instant.now(),
var updatedAt: Instant
) {
var auditTrail: List<String> = listOf()
fun updateName(name: String) {
this.auditTrail = auditTrail.plus(
“${this.name} -> ${name}”
)
this.name = name
this.updatedAt = Instant.now()
}
}

Domain Services
● Stateless
● Highly cohesive
● Contain business logic that doesn’t naturally ﬁt in value objects

Domain Services
● Stateless
● Highly cohesive
// in Domain Module
interface CurrencyExchangeService {
fun exchange(money: Money, currency: Currency): Money
}

Domain Services
● Stateless
● Highly cohesive
// in Infrastructure Module
class CurrencyExchangeServiceImpl : CurrencyExchangeService {
fun exchange(money: Money, currency: Currency): Money {
val amount = moneta.Money.of(money.amount, money.currency.toString())
val conversion = MonetaryConversions.getConversion(currency.toString())
val converted = amount.with(conversion)
return Money(
converted.number.numberValueExact(BigDecimal::class.java),
Currency.valueOf(converted.currency.currencyCode)
)
}

Application Services
● Stateless
● Orchestrates business operations (no business logic)
○ Transaction control
○ Enforce security
● Communicates through ports
● Use DTOs for communication
○ Little conversion overhead
○ Domain can evolve without having to change clients

Application Services
● Stateless
● Orchestrates business operations (no business logic)
○ Transaction control
○ Enforce security
● Implements a port in the case an external system wants to access your app
● Uses a port (implemented by an adapter) to access an external system
● Use DTOs for communication
○ Little conversion overhead
○ Domain can evolve without having to change clients
@Service
class UserAccountAdminServiceImpl(
private val userRepository: UserRepository
) : UserAccountAdminService {
@Transactional
fun resetPassword(userId: Long) {
val user = userRepository.findById(userId)
user.resetPassword()
userRepository.save()
}
}

Domain Module
● Use simple, safe and consistent value objects to model
your domain
○ Generate with Immutables/Lombok/AutoValue
○ Use Java 14 record types or Kotlin data classes
● Implement core business logic and functional (unit) tests
● No dependencies except itself (and 3rd party libraries with
low impact on domain)
● Expose a clear API / “ports”
○ Communicate using value objects / DTOs
● Could be a separate artifact (maven)

Infrastructure Modules
● Separate module that depends on Core Domain Module
● Speciﬁc for an application platform / library version
○ Easy to write version speciﬁc adapters
● Write adapters
○ Converting to/from entities, DTOs or proxy objects
○ 3rd party integrations
○ REST endpoints
○ DAO’s
● Integration tests if possible

enum class Currency { USD, EUR }
data class ExchangeRate(val rate: BigDecimal, val currency: Currency)
data class Money(val amount: BigDecimal, val currency: Currency) {
val largerThanZero = amount > BigDecimal.ZERO
fun add(o: Money): Money {
if(currency != o.currency) throw IllegalArgumentException()
return Money(amount.add(o.amount), currency)
}
fun convert(exchangeRate: ExchangeRate): Money {
return Money(amount.multiply(exchangeRate.rate), exchangeRate.currency)
}
}
data class UserAccountDTO(val balance: Money)
data class UserDTO(val userAccountId: String, val preferredCurrency: Currency)

// in Domain Module
interface ExchangeRateService {
fun getRate(source: Currency, target: Currency): ExchangeRate
}
class ExchangeRateServiceImpl : ExchangeRateService {
override fun getRate(source: Currency, target: Currency): ExchangeRate {
val rate = MonetaryConversions
.getConversion(source.toString())
.getExchangeRate(moneta.Money.of(1, target.toString()))
return ExchangeRate(
rate.factor.numberValueExact(BigDecimal::class.java),
Currency.valueOf(rate.currency.currencyCode)
)
}
}

// in Domain Module
@Service
class DepositService(val exchangeRateService: ExchangeRateService) {
fun deposit(user: UserDTO, account: UserAccountDTO, amount: Money): UserAccountDTO{
require(amount.largerThanZero) { “Amount must be larger than 0” }
val rateToUsd = if (amount.currency != Currency.USD) {
exchangeRateService.getRate(amount.currency, Currency.USD)
} else { ExchangeRate(BigDecimal.ONE, Currency.USD) }
val rateToPref = if (user.preferredCurrency != Currency.USD) {
exchangeRateService.getRate(Currency.USD, user.preferredCurrency)
} else { ExchangeRate(BigDecimal.ONE, Currency.USD) }
return account.copy(
balance = account.balance.add(
amount
` .convert(rateToUsd)
.convert(rateToPreferred)
)
}
}
}

// in Domain Module
@Service
class DepositOrchestrationService(
val depositService: DepositService,
val userService: UserService,
val userAccountService: UserAccountService,
val eventPublisherService: EventPublisherService,
) {
@Transactional
fun deposit(request: DepositRequest): DepositResponse {
val userDTO = userService.getUser(request.userId)
val accountDTO = userAccountService.getUserAccount(userDTO.userAccountId)
val oldBalance = accountDTO.balance
val updated = depositService.deposit(userDTO, accountDTO, request.amount)
userAccountService.save(accountDTO.copy(balance = updated.balance))
request.userId, oldBalance, updated.balance
)
eventPublisherService.publish(update)
return DepositResponse(request.userId, oldBalance, updated.balance)
}
}

Summary
● Start with isolated and tech agnostic domain
○ Bring value early
○ Delay choices on technical implementation

Summary
● The domain as a stand-alone module with embedded functional tests

Summary
● Modularity
○ As much adapters as needed w/o impacting other parts of the software
○ Tech stack can be changed independently and with low impact on the business

Summary
● Modularity
○ As much adapters as needed w/o impacting other parts of the software
○ Tech stack can be changed independently and with low impact on the business
● Only suitable if you have a real domain
○ overkill when merely transforming data from one format to another

Cooking your Ravioli "al dente" with Hexagonal Architecture

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Cooking your Ravioli "al dente" with Hexagonal Architecture

Similar to Cooking your Ravioli "al dente" with Hexagonal Architecture (20)

More from Jeroen Rosenberg

More from Jeroen Rosenberg (8)

Recently uploaded

Recently uploaded (20)

Cooking your Ravioli "al dente" with Hexagonal Architecture