In this guide (34 items)

Spring Boot

Spring Boot in Hexagonal Architecture

MANDATORY FOR ALL AI AGENTS: Spring Boot annotations and dependencies MUST be confined to infrastructure and bootstrap layers ONLY. The domain and application layers MUST remain 100% framework-agnostic. Use configuration classes for bean wiring, NEVER annotations on use cases. Transaction management MUST use the Transaction port pattern, NEVER @Transactional on use cases.

This guide covers Spring Boot-specific patterns and configurations for hexagonal architecture projects.

Core Principle

Keep Spring Boot confined to the infrastructure and bootstrap layers. Domain and application layers must remain framework-agnostic.

Module Dependencies

1
domain/
2
  - No Spring dependencies
3
  - No framework dependencies
4

5
application/
6
  - Depends on: domain only
7
  - No Spring dependencies
8
  - Defines ports (interfaces)
9

10
infrastructure/
11
  - Depends on: application, domain
12
  - Spring Boot starters here
13
  - Implements ports
14

15
bootstrap/
16
  - Depends on: all modules
17
  - Spring Boot Application
18
  - Configuration classes

build.gradle.kts example:

1
dependencies {
2
    // No Spring dependencies
3
}
4

5
// application/build.gradle.kts
6
dependencies {
7
    implementation(project(":domain"))
8
    // No Spring dependencies
9
}
10

11
// infrastructure/driven-adapters/jdbc-repository/build.gradle.kts
12
dependencies {
13
    implementation(project(":application"))
14
    implementation(project(":domain"))
15
    implementation("org.springframework.boot:spring-boot-starter-data-jdbc")
16
    implementation("org.liquibase:liquibase-core")
17
}
18

19
// bootstrap/build.gradle.kts
20
dependencies {
21
    implementation(project(":application"))
22
    implementation(project(":domain"))
23
    implementation(project(":infrastructure:entry-points:rest-controller"))
24
    implementation(project(":infrastructure:driven-adapters:jdbc-repository"))
25
    implementation(project(":infrastructure:driven-adapters:kafka-producer"))
26

27
    implementation("org.springframework.boot:spring-boot-starter-web")
28
    implementation("org.springframework.boot:spring-boot-starter-actuator")
29
}

Configuration Strategy

Use Configuration Classes, Not Annotations on Use Cases

❌ BAD - Annotating use cases:

1
@Service  // ❌ Framework coupling in application layer
2
@Transactional  // ❌ Framework annotation in application layer
3
class CreateOrganizationUseCase(
4
    private val repository: OrganizationRepositoryPort
5
) : CreateOrganizationPort {
6
    override fun execute(command: CreateOrganizationCommand): Organization {
7
        return repository.save(command.toOrganization())
8
    }
9
}

✅ GOOD - Configuration in bootstrap:

1
class CreateOrganizationUseCase(  // No annotations
2
    private val transaction: TransactionPort<Organization>,
3
    private val repository: OrganizationRepositoryPort
4
) : CreateOrganizationPort {
5
    override fun execute(command: CreateOrganizationCommand): Organization {
6
        return transaction.run {
7
            repository.save(command.toOrganization())
8
        }
9
    }
10
}
11

12
// bootstrap/config/UseCaseConfig.kt
13
@Configuration
14
class UseCaseConfig {
15

16
    @Bean
17
    fun createOrganizationUseCase(
18
        transaction: TransactionPort<Organization>,
19
        repository: OrganizationRepository
20
    ): CreateOrganizationPort {
21
        return CreateOrganizationUseCase(transaction, repository)
22
    }
23
}

Java:

1
public class CreateOrganizationUseCase implements CreateOrganizationPort {
2

3
    private final TransactionPort<Organization> transaction;
4
    private final OrganizationRepositoryPort repository;
5

6
    public CreateOrganizationUseCase(TransactionPort<Organization> transaction,
7
                                     OrganizationRepositoryPort repository) {
8
        this.transaction = transaction;
9
        this.repository = repository;
10
    }
11

12
    @Override
13
    public Organization execute(CreateOrganizationCommand command) {
14
        return transaction.run(() -> repository.save(command.toOrganization()));
15
    }
16
}
17

18
// bootstrap/config/UseCaseConfig.java
19
@Configuration
20
public class UseCaseConfig {
21

22
    @Bean
23
    public CreateOrganizationPort createOrganizationUseCase(
24
            TransactionPort<Organization> transaction,
25
            OrganizationRepositoryPort repository) {
26
        return new CreateOrganizationUseCase(transaction, repository);
27
    }
28
}

Component Scanning Strategy

Scan by Package or Naming Convention

Option 1: Package-based scanning

⚠️ Anti-pattern in strict hexagonal: component scanning requires a stereotype on the use case (a framework annotation in the application layer). Use Option 2.

1
@Configuration
2
@ComponentScan(
3
    basePackages = ["com.example.platform.usecase"],
4
    includeFilters = [ComponentScan.Filter(
5
        type = FilterType.REGEX,
6
        pattern = [".*UseCase$"]  // Only classes ending with "UseCase"
7
    )],
8
    useDefaultFilters = false
9
)
10
class UseCaseConfig

Option 2: Explicit bean definitions (recommended for clarity)

1
@Configuration
2
class UseCaseConfig(
3
    private val factory: BeanFactory
4
) {
5

6
    @Bean
7
    fun createOrganizationUseCase(
8
        transaction: TransactionPort<Organization>,
9
        repository: OrganizationRepositoryPort,
10
        outboxRepository: OutboxRepositoryPort,          // from codehuntersio-sdk-event-messaging
11
        outboxEventFactory: OutboxEventFactory,          // from codehuntersio-sdk-event-messaging
12
    ): CreateOrganizationPort {
13
        return CreateOrganizationUseCase(transaction, repository, outboxRepository, outboxEventFactory)
14
    }
15

16
    @Bean
17
    @Primary
18
    fun organizationRepository(): OrganizationRepositoryPort {
19
        return buildChain(OrganizationRepositoryPort::class.java)
20
    }
21
}

Transaction Management Pattern

Define Transaction as Port (Application Layer)

1
fun interface TransactionPort<R> {
2
    fun run(callback: TransactionCallbackPort<R>): R
3
}
4

5
fun interface TransactionCallbackPort<R> {
6
    fun call(): R
7
}

Implement with @Transactional (Infrastructure Layer)

1
// NOTE: no @Component on a generic parameterized class — Spring won't instantiate it as a bean.
2
// Expose it by type via @Bean in bootstrap, or use a non-generic callback — not a global @Component on a generic class.
3
class JdbcTransaction<R> : TransactionPort<R> {
4

5
    @Transactional(
6
        propagation = Propagation.REQUIRED,
7
        rollbackFor = [Exception::class]  // Rollback on ALL exceptions
8
    )
9
    override fun run(callback: TransactionCallbackPort<R>): R {
10
        return try {
11
            callback.call()
12
        } catch (exception: SQLException) {
13
            log.error("Database error in transaction", exception)
14
            throw exception
15
        } catch (exception: Exception) {
16
            log.error("Unexpected error in transaction", exception)
17
            throw exception  // re-throw original; rollbackFor=Exception handles rollback, no masking of OrderNotFoundException etc.
18
        }
19
    }
20
}

Java:

1
// NOTE: no @Component on a generic parameterized class — Spring won't instantiate it as a bean.
2
// Expose it by type via @Bean in bootstrap, or use a non-generic callback — not a global @Component on a generic class.
3
public class JdbcTransaction<R> implements TransactionPort<R> {
4

5
    private static final Logger log = LoggerFactory.getLogger(JdbcTransaction.class);
6

7
    @Transactional(
8
        propagation = Propagation.REQUIRED,
9
        rollbackFor = Exception.class  // Rollback on ALL exceptions
10
    )
11
    @Override
12
    public R run(TransactionCallbackPort<R> callback) {
13
        try {
14
            return callback.call();
15
        } catch (SQLException exception) {
16
            log.error("Database error in transaction", exception);
17
            throw exception;
18
        } catch (Exception exception) {
19
            log.error("Unexpected error in transaction", exception);
20
            throw exception;  // re-throw original; rollbackFor=Exception handles rollback, no masking of OrderNotFoundException etc.
21
        }
22
    }
23
}

Key Points:

rollbackFor = [Exception::class] ensures ALL exceptions trigger rollback (not just checked exceptions)
Only SQLException and RuntimeException trigger rollback by default in Spring
Business exceptions should also rollback the transaction

Spring Data JDBC (Preferred over JPA)

Why Spring Data JDBC over JPA?

Lighter weight, less “magic”
No lazy loading issues
No session/detached entity problems
Explicit control over queries
Better for hexagonal architecture (less coupling)

Entity Configuration

1
@Table("organizations")
2
class OrganizationEntity : AuditableEntity(), Persistable<UUID> {
3

4
    @Id
5
    @Column("id")
6
    private var id: UUID? = null
7

8
    @Column("name")
9
    var name: String = ""
10

11
    @Column("status")
12
    var status: String = ""
13

14
    @Transient
15
    private var isNew: Boolean = true
16

17
    override fun getId(): UUID? = id
18

19
    override fun isNew(): Boolean = isNew
20

21
    fun setId(id: UUID) {
22
        this.id = id
23
    }
24

25
    fun markNotNew() {
26
        this.isNew = false
27
    }
28
}

Java:

1
@Table("organizations")
2
public class OrganizationEntity extends AuditableEntity implements Persistable<UUID> {
3

4
    @Id
5
    @Column("id")
6
    private UUID id;
7

8
    @Column("name")
9
    private String name = "";
10

11
    @Column("status")
12
    private String status = "";
13

14
    @Transient
15
    private boolean isNew = true;
16

17
    @Override
18
    public UUID getId() {
19
        return id;
20
    }
21

22
    @Override
23
    public boolean isNew() {
24
        return isNew;
25
    }
26

27
    public void setId(UUID id) {
28
        this.id = id;
29
    }
30

31
    public void markNotNew() {
32
        this.isNew = false;
33
    }
34

35
    public String getName() { return name; }
36
    public void setName(String name) { this.name = name; }
37
    public String getStatus() { return status; }
38
    public void setStatus(String status) { this.status = status; }
39
}

Auditable base class:

1
abstract class AuditableEntity {
2

3
    @CreatedDate
4
    @Column("created_at")
5
    var createdAt: Instant? = null
6

7
    @CreatedBy
8
    @Column("created_by")
9
    var createdBy: String? = null
10

11
    @LastModifiedDate
12
    @Column("updated_at")
13
    var updatedAt: Instant? = null
14

15
    @LastModifiedBy
16
    @Column("updated_by")
17
    var updatedBy: String? = null
18
}

Repository Configuration

1
@Configuration
2
@EnableJdbcRepositories(
3
    basePackages = ["com.example.platform.infrastructure.driven.adapters.jdbc.repository"],
4
    includeFilters = [ComponentScan.Filter(
5
        type = FilterType.ANNOTATION,
6
        classes = [Repository::class]
7
    )]
8
)
9
@EnableJdbcAuditing
10
class JdbcConfig {
11

12
    @Bean
13
    fun transactionManager(dataSource: DataSource): PlatformTransactionManager {
14
        return DataSourceTransactionManager(dataSource)
15
    }
16

17
    @Bean
18
    fun auditorProvider(currentUserPort: CurrentUserPort): AuditorAware<String> {
19
        // CurrentUserPort is defined in application; the adapter resolves the current user.
20
        return AuditorAware { Optional.ofNullable(currentUserPort.currentUserId()) }
21
    }
22
}

Java:

1
@Configuration
2
@EnableJdbcRepositories(
3
    basePackages = "com.example.platform.infrastructure.driven.adapters.jdbc.repository",
4
    includeFilters = @ComponentScan.Filter(
5
        type = FilterType.ANNOTATION,
6
        classes = Repository.class
7
    )
8
)
9
@EnableJdbcAuditing
10
public class JdbcConfig {
11

12
    @Bean
13
    public PlatformTransactionManager transactionManager(DataSource dataSource) {
14
        return new DataSourceTransactionManager(dataSource);
15
    }
16

17
    @Bean
18
    public AuditorAware<String> auditorProvider(CurrentUserPort currentUserPort) {
19
        // CurrentUserPort is defined in application; the adapter resolves the current user.
20
        return () -> Optional.ofNullable(currentUserPort.currentUserId());
21
    }
22
}

Kafka Configuration

Producer Configuration

1
@Configuration
2
@EnableKafka
3
class KafkaConfig {
4

5
    @Bean
6
    fun producerFactory(
7
        @Value("\${spring.kafka.bootstrap-servers}") bootstrapServers: String
8
    ): ProducerFactory<String, String> {
9
        val props = mapOf(
10
            ProducerConfig.BOOTSTRAP_SERVERS_CONFIG to bootstrapServers,
11
            ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG to StringSerializer::class.java,
12
            ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG to StringSerializer::class.java,
13
            ProducerConfig.ACKS_CONFIG to "all",
14
            // enable.idempotence=true already guarantees ordering and safe retries (Kafka manages retries/in-flight)
15
            ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG to true
16
        )
17
        return DefaultKafkaProducerFactory(props)
18
    }
19

20
    @Bean
21
    fun kafkaTemplate(producerFactory: ProducerFactory<String, String>): KafkaTemplate<String, String> {
22
        return KafkaTemplate(producerFactory)
23
    }
24
}

⚠ Bean injection rule (ArchUnit-enforced). A KafkaTemplate<String, String> bean defined here MAY be injected ONLY into a MessagePublisherPort adapter (e.g. KafkaMessagePublisherAdapter) under infrastructure/driven-adapters/kafka-producer/. Injecting it into any class under ..usecase.., ..domain.., ..port.. or any controller violates the outbox-first rule and will fail the ArchUnit brokerTemplatesShouldOnlyLiveInPublisherAdapters test (see hexagonal-architecture.md §ArchUnit). The same applies to RabbitTemplate.

Java:

1
@Configuration
2
@EnableKafka
3
public class KafkaConfig {
4

5
    @Bean
6
    public ProducerFactory<String, String> producerFactory(
7
            @Value("${spring.kafka.bootstrap-servers}") String bootstrapServers) {
8
        Map<String, Object> props = Map.of(
9
            ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers,
10
            ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class,
11
            ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class,
12
            ProducerConfig.ACKS_CONFIG, "all",
13
            // enable.idempotence=true already guarantees ordering and safe retries (Kafka manages retries/in-flight)
14
            ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true
15
        );
16
        return new DefaultKafkaProducerFactory<>(props);
17
    }
18

19
    @Bean
20
    public KafkaTemplate<String, String> kafkaTemplate(ProducerFactory<String, String> producerFactory) {
21
        return new KafkaTemplate<>(producerFactory);
22
    }
23
}

Consumer Configuration

1
@Bean
2
fun consumerFactory(
3
    @Value("\${spring.kafka.bootstrap-servers}") bootstrapServers: String,
4
    @Value("\${spring.kafka.consumer.group-id}") groupId: String
5
): ConsumerFactory<String, String> {
6
    val props = mapOf(
7
        ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG to bootstrapServers,
8
        ConsumerConfig.GROUP_ID_CONFIG to groupId,
9
        ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG to StringDeserializer::class.java,
10
        ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG to StringDeserializer::class.java,
11
        ConsumerConfig.AUTO_OFFSET_RESET_CONFIG to "earliest",
12
        ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG to false
13
    )
14
    return DefaultKafkaConsumerFactory(props)
15
}
16

17
@Bean
18
fun kafkaListenerContainerFactory(
19
    consumerFactory: ConsumerFactory<String, String>
20
): ConcurrentKafkaListenerContainerFactory<String, String> {
21
    val factory = ConcurrentKafkaListenerContainerFactory<String, String>()
22
    factory.consumerFactory = consumerFactory
23
    factory.containerProperties.ackMode = ContainerProperties.AckMode.MANUAL
24
    return factory
25
}

Java:

1
@Bean
2
public ConsumerFactory<String, String> consumerFactory(
3
        @Value("${spring.kafka.bootstrap-servers}") String bootstrapServers,
4
        @Value("${spring.kafka.consumer.group-id}") String groupId) {
5
    Map<String, Object> props = Map.of(
6
        ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers,
7
        ConsumerConfig.GROUP_ID_CONFIG, groupId,
8
        ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class,
9
        ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class,
10
        ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest",
11
        ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false
12
    );
13
    return new DefaultKafkaConsumerFactory<>(props);
14
}
15

16
@Bean
17
public ConcurrentKafkaListenerContainerFactory<String, String> kafkaListenerContainerFactory(
18
        ConsumerFactory<String, String> consumerFactory) {
19
    ConcurrentKafkaListenerContainerFactory<String, String> factory =
20
        new ConcurrentKafkaListenerContainerFactory<>();
21
    factory.setConsumerFactory(consumerFactory);
22
    factory.getContainerProperties().setAckMode(ContainerProperties.AckMode.MANUAL);
23
    return factory;
24
}

Async Configuration

1
@Configuration
2
@EnableAsync
3
class AsyncConfig : AsyncConfigurer {
4

5
    override fun getAsyncExecutor(): Executor {
6
        val executor = ThreadPoolTaskExecutor()
7
        executor.corePoolSize = 5
8
        executor.maxPoolSize = 10
9
        executor.queueCapacity = 100
10
        executor.setThreadNamePrefix("async-")
11
        executor.setRejectedExecutionHandler(ThreadPoolExecutor.CallerRunsPolicy())
12
        executor.initialize()
13
        return executor
14
    }
15

16
    override fun getAsyncUncaughtExceptionHandler(): AsyncUncaughtExceptionHandler {
17
        return AsyncUncaughtExceptionHandler { throwable, method, params ->
18
            log.error("Async execution error in method: ${method.name}", throwable)
19
        }
20
    }
21
}

Java:

1
@Configuration
2
@EnableAsync
3
public class AsyncConfig implements AsyncConfigurer {
4

5
    private static final Logger log = LoggerFactory.getLogger(AsyncConfig.class);
6

7
    @Override
8
    public Executor getAsyncExecutor() {
9
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
10
        executor.setCorePoolSize(5);
11
        executor.setMaxPoolSize(10);
12
        executor.setQueueCapacity(100);
13
        executor.setThreadNamePrefix("async-");
14
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
15
        executor.initialize();
16
        return executor;
17
    }
18

19
    @Override
20
    public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
21
        return (throwable, method, params) ->
22
            log.error("Async execution error in method: " + method.getName(), throwable);
23
    }
24
}

Use @Async in infrastructure only — and NOT for event publishing.

Event publishing is decoupled by the SDK’s OutboxScheduler, not by @Async. There is no per-entity Kafka adapter; there is one broker-agnostic MessagePublisherPort:

1
class KafkaMessagePublisherAdapter(
2
    private val kafkaTemplate: KafkaTemplate<String, String>,
3
) : MessagePublisherPort {
4

5
    override fun publish(topic: String, routingKey: String, payload: String) {
6
        kafkaTemplate.send(topic, routingKey, payload).get(5, TimeUnit.SECONDS)
7
    }
8

9
    override fun publish(topic: String, payload: String) {
10
        kafkaTemplate.send(topic, payload).get(5, TimeUnit.SECONDS)
11
    }
12
}

No @Async, no try/catch-then-outbox: the dispatcher owns the retry policy. Use @Async for genuinely fire-and-forget cross-cutting work (warming caches, sending analytics pings) — never for messaging.

Scheduler Configuration

1
@Configuration
2
@EnableScheduling
3
class ScheduleConfig {
4

5
    @Bean
6
    fun taskScheduler(): TaskScheduler {
7
        val scheduler = ThreadPoolTaskScheduler()
8
        scheduler.poolSize = 5
9
        scheduler.setThreadNamePrefix("scheduled-")
10
        scheduler.initialize()
11
        return scheduler
12
    }
13
}

Use @Scheduled in entry-points/scheduler:

For the outbox dispatcher specifically, do not hand-roll a scheduler — it ships in codehuntersio-sdk-event-messaging as OutboxScheduler. Hand-rolling drifts from the canonical pattern (per-service lock name, claim TTL, exponential backoff) and breaks ArchUnit checks. See messaging.md §4.3.1 for the SDK starter.

When you DO need a custom scheduled job (e.g. cache warmer, reaper) follow the same lock-name-per-service convention:

1
@Component
2
class CacheWarmerScheduler(private val warmCache: WarmCachePort) {
3

4
    @Scheduled(fixedDelayString = "\${cache.warmer.fixed-delay:60000}")
5
    @SchedulerLock(
6
        name = "cache-warmer-\${spring.application.name}",   // per-service lock
7
        lockAtMostFor = "5m",
8
        lockAtLeastFor = "1m",
9
    )
10
    fun tick() = runCatching { warmCache.execute() }
11
        .onFailure { log.error("cache warmer failed", it) }
12
}

Use ShedLock for distributed scheduling:

1
@Configuration
2
@EnableSchedulerLock(defaultLockAtMostFor = "10m")
3
class ShedLockConfig {
4

5
    @Bean
6
    fun lockProvider(dataSource: DataSource): LockProvider {
7
        return JdbcTemplateLockProvider(
8
            JdbcTemplateLockProvider.Configuration.builder()
9
                .withJdbcTemplate(JdbcTemplate(dataSource))
10
                .usingDbTime()
11
                .build()
12
        )
13
    }
14
}
15

16
// Usage
17
@Scheduled(fixedDelay = 2000)
18
@SchedulerLock(name = "publishOutboxBatch", lockAtMostFor = "5m", lockAtLeastFor = "1m")
19
fun publishBatch() {
20
    // Only one instance will run this at a time
21
}

Java:

1
@Configuration
2
@EnableSchedulerLock(defaultLockAtMostFor = "10m")
3
public class ShedLockConfig {
4

5
    @Bean
6
    public LockProvider lockProvider(DataSource dataSource) {
7
        return new JdbcTemplateLockProvider(
8
            JdbcTemplateLockProvider.Configuration.builder()
9
                .withJdbcTemplate(new JdbcTemplate(dataSource))
10
                .usingDbTime()
11
                .build()
12
        );
13
    }
14
}
15

16
// Usage
17
@Scheduled(fixedDelay = 2000)
18
@SchedulerLock(name = "publishOutboxBatch", lockAtMostFor = "5m", lockAtLeastFor = "1m")
19
public void publishBatch() {
20
    // Only one instance will run this at a time
21
}

Observability & Metrics

For comprehensive observability guidance including OTEL, Micrometer, Prometheus, and NewRelic, see Observability Guide.

Key points:

Metrics are implemented as decorator adapters using the Chain of Responsibility pattern.
Use MetricRecorded abstract class in the metrics-publisher module.
OTEL tracing is automatic via micrometer-tracing-bridge-otel.
See Observability Guide for configuration, custom metrics, and step-by-step instructions.

Testing with Spring

Architecture Tests (ArchUnit)

1
@AnalyzeClasses(packages = ["com.example.platform"])
2
class HexagonalArchitectureTest {
3

4
    @ArchTest
5
    val domainShouldNotDependOnInfrastructure = noClasses()
6
        .that().resideInAPackage("..domain..")
7
        .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
8
        .because("Domain must be free from infrastructure dependencies")
9

10
    @ArchTest
11
    val useCasesShouldNotHaveSpringAnnotations = noClasses()
12
        .that().resideInAPackage("..usecase..")
13
        .should().beAnnotatedWith("org.springframework.stereotype.Service")
14
        .orShould().beAnnotatedWith("org.springframework.transaction.annotation.Transactional")
15
        .because("Use cases should be framework-agnostic")
16
}

Integration Tests with Testcontainers

1
@SpringBootTest
2
@Testcontainers
3
@ActiveProfiles("test")
4
class OrganizationRepositoryIntegrationTest {
5

6
    companion object {
7
        @Container
8
        @ServiceConnection
9
        val postgres: PostgreSQLContainer<*> = PostgreSQLContainer("postgres:16-alpine")
10
            .withDatabaseName("testdb")
11
            .withUsername("test")
12
            .withPassword("test")
13
    }
14

15
    @Autowired
16
    private lateinit var repository: OrganizationRepository
17

18
    @Test
19
    fun `should save and retrieve organization`() {
20
        val organization = Organization(
21
            id = UUID.randomUUID(),
22
            name = "Test Org",
23
            status = OrganizationStatus.ACTIVE
24
        )
25

26
        val saved = repository.save(organization)
27
        val retrieved = repository.findById(saved.id)
28

29
        assertThat(retrieved).isNotNull
30
        assertThat(retrieved?.name).isEqualTo("Test Org")
31
    }
32
}

Java:

1
@SpringBootTest
2
@Testcontainers
3
@ActiveProfiles("test")
4
class OrganizationRepositoryIntegrationTest {
5

6
    @Container
7
    @ServiceConnection
8
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
9
        .withDatabaseName("testdb")
10
        .withUsername("test")
11
        .withPassword("test");
12

13
    @Autowired
14
    private OrganizationRepository repository;
15

16
    @Test
17
    void shouldSaveAndRetrieveOrganization() {
18
        Organization organization = new Organization(
19
            UUID.randomUUID(),
20
            "Test Org",
21
            OrganizationStatus.ACTIVE
22
        );
23

24
        Organization saved = repository.save(organization);
25
        Organization retrieved = repository.findById(saved.getId());
26

27
        assertThat(retrieved).isNotNull();
28
        assertThat(retrieved.getName()).isEqualTo("Test Org");
29
    }
30
}

Configuration Management

Environment-specific Configuration

1
# application.yml (base)
2
spring:
3
  application:
4
    name: platform-service
5
  profiles:
6
    active: ${SPRING_PROFILES_ACTIVE:dev}
7

8
# application-dev.yml
9
spring:
10
  datasource:
11
    url: jdbc:postgresql://localhost:5432/platform_dev
12
    username: dev
13
    password: dev
14

15
# application-prod.yml
16
spring:
17
  datasource:
18
    url: ${DATABASE_URL}
19
    username: ${DATABASE_USERNAME}
20
    password: ${DATABASE_PASSWORD}

Externalized Configuration

1
@ConfigurationProperties(prefix = "outbox")
2
data class OutboxProperties(
3
    val batchSize: Int = 100,
4
    val fixedDelay: Long = 2000,
5
    val maxRetries: Int = 10,
6
    val topics: Map<String, String> = emptyMap()
7
)
8

9
@Configuration
10
@EnableConfigurationProperties(OutboxProperties::class)
11
class OutboxConfig

JSON Serialization — JsonMapper over ObjectMapper

MANDATORY: Always use JsonMapper instead of ObjectMapper. Jackson 3.x deprecates ObjectMapper in favor of JsonMapper as the primary entry point. JsonMapper provides a cleaner, type-safe builder API and is the only mapper that should be used in new code.

Bean Configuration

Kotlin:

1
@Configuration
2
class JacksonConfig {
3

4
    @Bean
5
    fun jsonMapper(): JsonMapper {
6
        return JsonMapper.builder()
7
            .addModule(JavaTimeModule())
8
            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
9
            .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
10
            .enable(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES)
11
            .serializationInclusion(JsonInclude.Include.NON_NULL)
12
            .build()
13
    }
14
}

Java:

1
@Configuration
2
public class JacksonConfig {
3

4
    @Bean
5
    public JsonMapper jsonMapper() {
6
        return JsonMapper.builder()
7
            .addModule(new JavaTimeModule())
8
            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
9
            .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
10
            .enable(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES)
11
            .serializationInclusion(JsonInclude.Include.NON_NULL)
12
            .build();
13
    }
14
}

Usage in Adapters

1
// ✅ GOOD — JsonMapper used in the SDK auto-config (bean name "outboxJsonMapper")
2
@Configuration
3
class OutboxSerializationConfig {
4
    @Bean("outboxJsonMapper")
5
    fun outboxJsonMapper(): JsonMapper = JsonMapper.builder()
6
        .addModule(JavaTimeModule())
7
        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
8
        .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
9
        .build()
10
}
11

12
// ✅ GOOD — broker-agnostic adapter; payload already serialized by the SDK
13
class KafkaMessagePublisherAdapter(
14
    private val kafkaTemplate: KafkaTemplate<String, String>,
15
) : MessagePublisherPort {
16
    override fun publish(topic: String, routingKey: String, payload: String) {
17
        kafkaTemplate.send(topic, routingKey, payload).get(5, TimeUnit.SECONDS)
18
    }
19
    override fun publish(topic: String, payload: String) {
20
        kafkaTemplate.send(topic, payload).get(5, TimeUnit.SECONDS)
21
    }
22
}
23

24
// ❌ BAD — ObjectMapper (Jackson 3.x deprecates it; use JsonMapper)
25
class OrganizationKafkaAdapter(
26
    private val objectMapper: ObjectMapper
27
)
28

29
// ❌ BAD — per-entity publisher port + envelope construction in the adapter
30
class OrganizationKafkaAdapter(
31
    private val jsonMapper: JsonMapper,
32
    private val kafkaTemplate: KafkaTemplate<String, String>,
33
) : OrganizationPublisher {
34
    override fun publish(organization: Organization) {
35
        kafkaTemplate.send(topic, organization.id.toString(), jsonMapper.writeValueAsString(organization))
36
    }
37
}
38
// Why bad: per-entity publisher port invites dual-write from the use case;
39
// envelope/serialization belongs to the SDK (`OutboxEventFactory` + `outboxJsonMapper`),
40
// not the adapter. Adapter receives a `String` payload from the dispatcher.

Key Differences

Feature	`ObjectMapper`	`JsonMapper`
Builder API	Mutable, error-prone	Immutable, type-safe
Jackson 3.x	Deprecated	Primary entry point
Thread safety	Requires careful config	Immutable after build
Module registration	Runtime mutations	Builder-time only

Anti-Patterns to Avoid

❌ Spring Annotations in Domain/Application

1
// ❌ BAD — JPA leaks into domain
2
@Entity
3
@Table(name = "organizations")
4
data class Organization(
5
    @Id val id: UUID,
6
    val name: String,
7
)
8

9
// ❌ ALSO BAD — anemic domain (data bag, no behavior, no invariants).
10
// Per DDD/clean-code: entity must own its invariants + state transitions.
11
data class Organization(
12
    val id: UUID,
13
    val name: String,
14
    val status: OrganizationStatus,
15
)
16

17
// ✅ GOOD — framework-free, immutable, invariants enforced, behavior on the entity
18
class Organization private constructor(
19
    val id: UUID,
20
    val name: OrganizationName,
21
    val status: OrganizationStatus,
22
    val version: Long,
23
) {
24
    init {
25
        require(version >= 0) { "version must be non-negative" }
26
    }
27

28
    fun rename(newName: OrganizationName): Organization =
29
        Organization(id, newName, status, version + 1)
30

31
    fun transitionTo(newStatus: OrganizationStatus): Organization {
32
        require(status.canTransitionTo(newStatus)) {
33
            "Illegal transition: $status → $newStatus"
34
        }
35
        return Organization(id, name, newStatus, version + 1)
36
    }
37

38
    companion object {
39
        fun create(id: UUID, name: OrganizationName): Organization =
40
            Organization(id, name, OrganizationStatus.PENDING_APPROVAL, version = 0)
41
    }
42
}

❌ @Autowired Field Injection

1
// ❌ BAD
2
@Component
3
class OrganizationAdapter {
4
    @Autowired
5
    private lateinit var repository: OrganizationJdbcRepository
6
}
7

8
// ✅ GOOD
9
@Component
10
class OrganizationAdapter(
11
    private val repository: OrganizationJdbcRepository  // Constructor injection
12
)

❌ Using Spring Types in Ports

1
// ❌ BAD
2
interface OrganizationPublisher {
3
    fun publish(event: ApplicationEvent)  // Spring type leaking into a port
4
}
5

6
// ❌ BAD — domain-specific publisher port (invites dual-write from the use case)
7
interface OrganizationPublisher {
8
    fun publish(organization: Organization)
9
}
10

11
// ✅ GOOD — use case publishes via the SDK outbox port; no domain publisher port exists
12
class CreateOrganizationUseCase(
13
    private val transaction: TransactionPort<Organization>,
14
    private val organizations: OrganizationRepositoryPort,
15
    private val outbox: OutboxRepositoryPort,         // from codehuntersio-sdk-event-messaging
16
    private val events: OutboxEventFactory,           // from codehuntersio-sdk-event-messaging
17
) : CreateOrganizationPort { /* ... */ }

Outbox messaging starter — use the SDK, do not re-implement

Add the codehuntersio-sdk-event-messaging starter to consume this section’s contract end-to-end. It ships every messaging bean with @ConditionalOnMissingBean; override what you need.

1
# application.yml — defaults shown
2
outbox:
3
  enabled: true
4
  batch-size: 50
5
  max-attempts: 5
6
  task:
7
    fixed-delay: 5000
8
    lock-at-most: 60000
9
    lock-at-least: 10000
10
    lock-name: outbox-${spring.application.name}   # per-service — DO NOT collapse
11
  claim:
12
    ttl-ms: 300000
13
  backoff:
14
    base-delay-ms: 30000
15
    max-delay-ms: 3600000

Beans the SDK provides (override any with @Bean): EventMessageFactory, OutboxEventFactory, OutboxRepositoryPort (OutboxJdbcAdapter), MessagePublisherPort (RabbitMessagePublisherAdapter), SendOutboxMessagesPort (SendOutboxMessagesUseCase), OutboxScheduler, LockProvider (JdbcTemplateLockProvider), outboxJsonMapper.

Swap broker: provide a KafkaMessagePublisherAdapter bean — the SDK Rabbit default skips itself via @ConditionalOnMissingBean. Application code is untouched.

See messaging.md §4.3.1 for the canonical reference.

Summary

Key Principles:

Keep Spring in infrastructure and bootstrap only
Use configuration classes, not annotations on use cases
Define abstractions (ports) in application, implementations in infrastructure
Prefer Spring Data JDBC over JPA for cleaner separation
Use constructor injection everywhere
Externalize configuration with environment variables
Enforce architecture with ArchUnit tests
Use Testcontainers for integration tests

This approach ensures your hexagonal architecture remains clean, testable, and framework-agnostic while still leveraging Spring Boot’s powerful features where appropriate.