Best Practices

Kotlin Coroutines + Spring Boot Best Practices

Comprehensive performance optimization and best practices for Spring Boot applications with Kotlin Coroutines. 48 rules across 8 categories based on Spring Framework 7.0, Spring Boot 4.0, Kotlin 2.x coroutines, and R2DBC async patterns.

Activation Triggers

This skill activates when:

• Writing new controllers, services, or repositories with coroutines
• Implementing Flow patterns and reactive streams
• Optimizing async performance with WebFlux
• Reviewing or refactoring Kotlin coroutine code
• Debugging scope, cancellation, or flow issues
• Implementing authentication/authorization with reactive security
• Writing tests for coroutine-based applications

Rule Categories

Quick Reference - All 48 Rules

Coroutine Basics (CRITICAL) - coroutine-*

Scope Management (CRITICAL) - scope-*

Flow Patterns (HIGH) - flow-*

R2DBC Database (HIGH) - db-*

Error Handling (HIGH) - err-*

Spring WebFlux (MEDIUM) - webflux-*

Security (MEDIUM) - sec-*

Testing (MEDIUM) - test-*

Detailed Rules by Category

1. Coroutine Basics (CRITICAL)

coroutine-suspend - Use Suspend Functions Correctly

Impact: Non-blocking execution, proper coroutine integration

// ❌ INCORRECT - blocking call in suspend function
suspend fun getUser(id: Long): User {
    Thread.sleep(1000)  // BLOCKS the thread!
    return repository.findById(id)  // blocking JDBC
}

// ✅ CORRECT - proper suspend function
suspend fun getUser(id: Long): User {
    delay(1000)  // non-blocking delay
    return repository.findByIdOrNull(id)  // R2DBC suspend
        ?: throw UserNotFoundException(id)
}

// ✅ CORRECT - marking function as suspend when it calls other suspend functions
suspend fun getUserWithOrders(userId: Long): UserWithOrders {
    val user = userRepository.findById(userId)  // suspend call
    val orders = orderRepository.findByUserId(userId)  // suspend call
    return UserWithOrders(user, orders)
}

coroutine-dispatcher - Choose Correct Dispatcher

Impact: Optimized thread utilization for CPU vs IO operations

// ❌ INCORRECT - CPU-intensive work on Default/IO dispatcher
suspend fun processImage(data: ByteArray): ByteArray {
    return withContext(Dispatchers.IO) {  // Wrong! IO is for blocking I/O
        heavyImageProcessing(data)  // CPU-bound work
    }
}

// ✅ CORRECT - use appropriate dispatchers
suspend fun processImage(data: ByteArray): ByteArray {
    return withContext(Dispatchers.Default) {  // CPU-bound work
        heavyImageProcessing(data)
    }
}

suspend fun readFile(path: String): String {
    return withContext(Dispatchers.IO) {  // Blocking I/O
        File(path).readText()
    }
}

// ✅ CORRECT - no dispatcher needed for suspend-native operations
suspend fun fetchFromApi(url: String): Response {
    // WebClient is already non-blocking, no withContext needed
    return webClient.get()
        .uri(url)
        .awaitExchange { it.awaitBody() }
}

coroutine-blocking - Never Block in Coroutines

Impact: Prevents thread starvation, maintains concurrency

// ❌ INCORRECT - blocking operations in coroutine
@GetMapping("/data")
suspend fun getData(): Data {
    val result = blockingHttpClient.get(url)  // BLOCKS!
    Thread.sleep(100)  // BLOCKS!
    return result
}

// ✅ CORRECT - use non-blocking alternatives
@GetMapping("/data")
suspend fun getData(): Data {
    val result = webClient.get()
        .uri(url)
        .awaitBody<Data>()  // non-blocking
    delay(100)  // non-blocking
    return result
}

// ✅ CORRECT - if blocking is unavoidable, use withContext(Dispatchers.IO)
suspend fun legacyOperation(): Result {
    return withContext(Dispatchers.IO) {
        legacyBlockingClient.execute()  // isolated on IO dispatcher
    }
}

coroutine-context - Understand CoroutineContext

Impact: Proper context propagation for logging, tracing, auth

// ❌ INCORRECT - losing context elements
suspend fun processWithLogging() {
    // MDC context lost when switching dispatchers
    withContext(Dispatchers.Default) {
        logger.info("Processing")  // MDC context may be empty!
    }
}

// ✅ CORRECT - propagate context elements
suspend fun processWithLogging() {
    val mdcContext = MDCContext()
    withContext(Dispatchers.Default + mdcContext) {
        logger.info("Processing")  // MDC context preserved
    }
}

// ✅ CORRECT - Spring Boot 4.0 automatic context propagation
// application.properties: spring.reactor.context-propagation=auto
@GetMapping("/trace")
suspend fun tracedEndpoint(): Response {
    // Tracing context automatically propagated
    return service.process()
}

coroutine-async - Use async/await for Parallel Execution

Impact: Concurrent execution, reduced latency

// ❌ INCORRECT - sequential execution (3x latency)
suspend fun getDashboard(userId: Long): Dashboard {
    val user = userService.getUser(userId)        // 100ms
    val orders = orderService.getOrders(userId)   // 100ms
    val notifications = notificationService.get() // 100ms
    return Dashboard(user, orders, notifications) // Total: 300ms
}

// ✅ CORRECT - parallel execution with coroutineScope
suspend fun getDashboard(userId: Long): Dashboard = coroutineScope {
    val user = async { userService.getUser(userId) }
    val orders = async { orderService.getOrders(userId) }
    val notifications = async { notificationService.get() }

    Dashboard(
        user = user.await(),
        orders = orders.await(),
        notifications = notifications.await()
    )  // Total: ~100ms (max of all)
}

// ✅ CORRECT - with structured error handling
suspend fun getDashboardSafe(userId: Long): Dashboard = supervisorScope {
    val user = async { userService.getUser(userId) }
    val orders = async {
        runCatching { orderService.getOrders(userId) }
            .getOrDefault(emptyList())
    }
    val notifications = async {
        runCatching { notificationService.get() }
            .getOrDefault(emptyList())
    }

    Dashboard(user.await(), orders.await(), notifications.await())
}

coroutine-withContext - Use withContext for Dispatcher Switch

Impact: Clean context switching without nested scopes

// ❌ INCORRECT - unnecessary scope creation
suspend fun processData(data: Data): Result {
    return CoroutineScope(Dispatchers.Default).async {
        heavyProcessing(data)
    }.await()  // Creates new scope, loses parent context!
}

// ✅ CORRECT - use withContext
suspend fun processData(data: Data): Result {
    return withContext(Dispatchers.Default) {
        heavyProcessing(data)
    }  // Maintains parent scope, proper cancellation
}

// ✅ CORRECT - combine context elements
suspend fun processWithTimeout(data: Data): Result {
    return withContext(Dispatchers.Default + CoroutineName("processor")) {
        withTimeout(5000) {
            heavyProcessing(data)
        }
    }
}

2. Scope Management (CRITICAL)

scope-no-global - Never Use GlobalScope

Impact: Prevents memory leaks, enables proper cancellation

// ❌ INCORRECT - GlobalScope leaks and can't be cancelled
@Service
class NotificationService {
    fun sendAsync(notification: Notification) {
        GlobalScope.launch {  // NEVER CANCELLED!
            sendNotification(notification)
        }
    }
}

// ✅ CORRECT - inject scope tied to service lifecycle
@Service
class NotificationService(
    private val scope: CoroutineScope  // injected
) {
    fun sendAsync(notification: Notification) {
        scope.launch {  // cancelled when service destroyed
            sendNotification(notification)
        }
    }
}

// ✅ CORRECT - define scope as Spring bean
@Configuration
class CoroutineConfig {
    @Bean
    fun applicationScope(): CoroutineScope {
        return CoroutineScope(
            SupervisorJob() +
            Dispatchers.Default +
            CoroutineName("app-scope")
        )
    }

    @Bean
    fun cleanupScope(scope: CoroutineScope): DisposableBean {
        return DisposableBean { scope.cancel() }
    }
}

scope-structured - Use Structured Concurrency

Impact: Automatic cleanup, proper parent-child relationships

// ❌ INCORRECT - fire-and-forget without structure
suspend fun processOrders(orders: List<Order>) {
    orders.forEach { order ->
        CoroutineScope(Dispatchers.Default).launch {
            processOrder(order)  // orphaned coroutines!
        }
    }
    // returns immediately, children still running
}

// ✅ CORRECT - structured concurrency waits for children
suspend fun processOrders(orders: List<Order>) = coroutineScope {
    orders.forEach { order ->
        launch {
            processOrder(order)
        }
    }
    // waits for all children to complete
}

// ✅ CORRECT - parallel with result collection
suspend fun processOrders(orders: List<Order>): List<Result> = coroutineScope {
    orders.map { order ->
        async {
            processOrder(order)
        }
    }.awaitAll()
}

scope-coroutineScope - Use coroutineScope for Grouping

Impact: Child coroutine management, exception propagation

// ✅ CORRECT - group related operations
suspend fun updateUserProfile(userId: Long, profile: Profile): User = coroutineScope {
    // Validate in parallel
    val validationDeferred = async { validateProfile(profile) }
    val existingUser = async { userRepository.findById(userId) }

    validationDeferred.await()  // throws if invalid
    val user = existingUser.await() ?: throw UserNotFoundException(userId)

    // Update with validated data
    val updatedUser = user.copy(
        name = profile.name,
        email = profile.email
    )

    // Parallel side effects
    launch { auditService.logUpdate(userId) }
    launch { cacheService.invalidate(userId) }

    userRepository.save(updatedUser)
}

scope-supervisorScope - Use supervisorScope for Isolation

Impact: Fault tolerance, independent child failures

// ❌ INCORRECT - one failure cancels all
suspend fun sendNotifications(users: List<User>) = coroutineScope {
    users.forEach { user ->
        launch {
            sendNotification(user)  // one failure cancels ALL
        }
    }
}

// ✅ CORRECT - isolated failures with supervisorScope
suspend fun sendNotifications(users: List<User>) = supervisorScope {
    users.forEach { user ->
        launch {
            try {
                sendNotification(user)
            } catch (e: Exception) {
                logger.error("Failed to notify ${user.id}", e)
                // continues with other users
            }
        }
    }
}

// ✅ CORRECT - collect results with partial failure handling
suspend fun fetchAllData(): AggregatedData = supervisorScope {
    val users = async {
        runCatching { userService.getAll() }.getOrDefault(emptyList())
    }
    val products = async {
        runCatching { productService.getAll() }.getOrDefault(emptyList())
    }
    val orders = async {
        runCatching { orderService.getAll() }.getOrDefault(emptyList())
    }

    AggregatedData(users.await(), products.await(), orders.await())
}

scope-lifecycle - Tie Scope to Lifecycle

Impact: Proper resource management, no orphaned coroutines

// ✅ CORRECT - scope tied to component lifecycle
@Component
class BackgroundProcessor : DisposableBean {
    private val scope = CoroutineScope(
        SupervisorJob() + Dispatchers.Default
    )

    fun startProcessing() {
        scope.launch {
            while (isActive) {
                processNextItem()
                delay(1000)
            }
        }
    }

    override fun destroy() {
        scope.cancel()  // cleanup on shutdown
    }
}

// ✅ CORRECT - request-scoped with Spring
@RestController
class UserController {
    @GetMapping("/users/{id}")
    suspend fun getUser(@PathVariable id: Long): User {
        // Spring creates request-scoped coroutine context
        return userService.getUser(id)
    }
}

scope-injection - Inject CoroutineScope for Testability

Impact: Easy testing, flexible dispatcher configuration

// ✅ CORRECT - inject scope for testability
@Service
class OrderProcessor(
    private val orderRepository: OrderRepository,
    private val scope: CoroutineScope = CoroutineScope(Dispatchers.Default)
) {
    fun processAsync(orderId: Long): Job {
        return scope.launch {
            val order = orderRepository.findById(orderId)
            processOrder(order)
        }
    }
}

// In tests
@Test
fun `test order processing`() = runTest {
    val testScope = this  // TestScope from runTest
    val processor = OrderProcessor(mockRepository, testScope)

    processor.processAsync(1L)
    advanceUntilIdle()

    coVerify { mockRepository.findById(1L) }
}

3. Flow Patterns (HIGH)

flow-cold - Understand Flow is Cold

Impact: Proper subscription behavior, no unexpected side effects

// ❌ INCORRECT - expecting Flow to run immediately
fun getUpdates(): Flow<Update> = flow {
    println("Starting flow")  // Not printed until collected!
    emit(fetchUpdate())
}

// This doesn't start the flow:
val updates = getUpdates()  // Nothing happens yet

// ✅ CORRECT - collect to start the flow
suspend fun processUpdates() {
    getUpdates().collect { update ->
        println("Received: $update")
    }
}

// ✅ CORRECT - use SharedFlow for hot streams
@Service
class EventService {
    private val _events = MutableSharedFlow<Event>(
        replay = 1,
        extraBufferCapacity = 64
    )
    val events: SharedFlow<Event> = _events.asSharedFlow()

    suspend fun emit(event: Event) {
        _events.emit(event)
    }
}

flow-operators - Use Flow Operators Correctly

Impact: Efficient transformations, proper backpressure handling

// ✅ CORRECT - chain operators efficiently
fun getProcessedOrders(): Flow<ProcessedOrder> {
    return orderRepository.findAllAsFlow()
        .filter { it.status == OrderStatus.PENDING }
        .map { order -> processOrder(order) }
        .catch { e ->
            logger.error("Processing failed", e)
            emit(ProcessedOrder.failed())
        }
        .onCompletion { logger.info("Processing complete") }
}

// ✅ CORRECT - use buffer for slow collectors
fun getNotifications(): Flow<Notification> {
    return notificationSource.asFlow()
        .buffer(capacity = 64)  // buffer if collector is slow
        .map { enrichNotification(it) }
}

// ✅ CORRECT - use conflate for latest-only semantics
fun getPriceUpdates(): Flow<Price> {
    return priceSource.asFlow()
        .conflate()  // keep only latest if collector is slow
}

// ✅ CORRECT - debounce for rate limiting
fun getSearchResults(queries: Flow<String>): Flow<List<Result>> {
    return queries
        .debounce(300)  // wait 300ms of inactivity
        .distinctUntilChanged()
        .flatMapLatest { query ->
            searchService.search(query)
        }
}

flow-stateflow - Use StateFlow for State

Impact: Proper state management, UI updates

// ✅ CORRECT - StateFlow for observable state
@Service
class ConnectionService {
    private val _connectionState = MutableStateFlow(ConnectionState.DISCONNECTED)
    val connectionState: StateFlow<ConnectionState> = _connectionState.asStateFlow()

    suspend fun connect() {
        _connectionState.value = ConnectionState.CONNECTING
        try {
            establishConnection()
            _connectionState.value = ConnectionState.CONNECTED
        } catch (e: Exception) {
            _connectionState.value = ConnectionState.ERROR
        }
    }
}

// ✅ CORRECT - expose immutable StateFlow
class ViewModel {
    private val _uiState = MutableStateFlow(UiState.Initial)
    val uiState: StateFlow<UiState> = _uiState.asStateFlow()

    // Never expose MutableStateFlow directly
}

flow-sharedflow - Use SharedFlow for Events

Impact: Event broadcasting, multiple subscribers

// ✅ CORRECT - SharedFlow for one-time events
@Service
class EventBus {
    private val _events = MutableSharedFlow<AppEvent>(
        extraBufferCapacity = 64,
       
    )
    val events: SharedFlow<AppEvent> = _events.asSharedFlow()

    suspend fun publish(event: AppEvent) {
        _events.emit(event)
    }

    // For fire-and-forget without suspend
    fun tryPublish(event: AppEvent): Boolean {
        return _events.tryEmit(event)
    }
}

// ✅ CORRECT - replay for late subscribers
@Service
class ConfigService {
    private val _config = MutableSharedFlow<Config>(
        replay = 1  // late subscribers get last value
    )
    val config: SharedFlow<Config> = _config.asSharedFlow()
}

flow-flowOn - Use flowOn for Context Switching

Impact: Single context switch point, efficient execution

// ❌ INCORRECT - multiple unnecessary context switches
fun processItems(): Flow<Item> = flow {
    items.forEach { item ->
        val processed = withContext(Dispatchers.Default) {  // switch per item!
            process(item)
        }
        emit(processed)
    }
}

// ✅ CORRECT - single flowOn for upstream
fun processItems(): Flow<Item> = flow {
    items.forEach { item ->
        emit(process(item))
    }
}.flowOn(Dispatchers.Default)  // all upstream on Default

// ✅ CORRECT - multiple flowOn for different stages
fun loadAndProcessData(): Flow<Result> {
    return loadFromDb()
        .flowOn(Dispatchers.IO)  // DB operations on IO
        .map { process(it) }
        .flowOn(Dispatchers.Default)  // processing on Default
}

flow-collect - Collect Safely in Scope

Impact: Prevent leaks, proper cancellation

// ❌ INCORRECT - collecting in GlobalScope
@Service
class EventListener {
    fun startListening() {
        GlobalScope.launch {  // leaks!
            events.collect { handleEvent(it) }
        }
    }
}

// ✅ CORRECT - collect in lifecycle-bound scope
@Service
class EventListener(
    private val scope: CoroutineScope
) : DisposableBean {

    private var job: Job? = null

    fun startListening() {
        job = scope.launch {
            events.collect { handleEvent(it) }
        }
    }

    override fun destroy() {
        job?.cancel()
    }
}

// ✅ CORRECT - use launchIn for cleaner syntax
@Service
class EventListener(
    private val scope: CoroutineScope
) {
    init {
        events
            .onEach { handleEvent(it) }
            .launchIn(scope)
    }
}

4. R2DBC Database (HIGH)

db-r2dbc - Use R2DBC Not JDBC

Impact: Non-blocking database operations

// ❌ INCORRECT - blocking JDBC
@Repository
class UserRepository(
    private val jdbcTemplate: JdbcTemplate
) {
    fun findById(id: Long): User? {
        return jdbcTemplate.queryForObject(...)  // BLOCKS!
    }
}

// ✅ CORRECT - R2DBC with coroutines
@Repository
interface UserRepository : CoroutineCrudRepository<User, Long> {
    suspend fun findByEmail(email: String): User?

    @Query("SELECT * FROM users WHERE status = :status")
    fun findByStatus(status: String): Flow<User>
}

// ✅ CORRECT - configuration
@Configuration
@EnableR2dbcRepositories
class DatabaseConfig : AbstractR2dbcConfiguration() {

    @Bean
    override fun connectionFactory(): ConnectionFactory {
        return ConnectionFactories.get(
            ConnectionFactoryOptions.builder()
                .option(DRIVER, "postgresql")
                .option(HOST, "localhost")
                .option(DATABASE, "mydb")
                .option(USER, "user")
                .option(PASSWORD, "pass")
                .build()
        )
    }
}

db-repository - Use CoroutineCrudRepository

Impact: Native coroutine API, clean suspend functions

// ✅ CORRECT - CoroutineCrudRepository for suspend functions
@Repository
interface OrderRepository : CoroutineCrudRepository<Order, Long> {

    // Suspend function for single result
    suspend fun findByOrderNumber(orderNumber: String): Order?

    // Flow for multiple results
    fun findByUserId(userId: Long): Flow<Order>

    // Custom query with suspend
    @Query("SELECT * FROM orders WHERE status = :status LIMIT :limit")
    suspend fun findTopByStatus(status: String, limit: Int): List<Order>
}

// ✅ CORRECT - use in service
@Service
class OrderService(
    private val orderRepository: OrderRepository
) {
    suspend fun getOrder(id: Long): Order {
        return orderRepository.findById(id)
            ?: throw OrderNotFoundException(id)
    }

    fun getUserOrders(userId: Long): Flow<Order> {
        return orderRepository.findByUserId(userId)
    }
}

db-transaction - Handle Transactions Correctly

Impact: Data consistency, ACID compliance

// ❌ INCORRECT - no transaction for multiple operations
suspend fun transferMoney(from: Long, to: Long, amount: BigDecimal) {
    val fromAccount = accountRepository.findById(from)!!
    fromAccount.balance -= amount
    accountRepository.save(fromAccount)  // committed

    val toAccount = accountRepository.findById(to)!!  // if this fails, money lost!
    toAccount.balance += amount
    accountRepository.save(toAccount)
}

// ✅ CORRECT - programmatic transaction with coroutines
@Service
class TransferService(
    private val transactionalOperator: TransactionalOperator,
    private val accountRepository: AccountRepository
) {
    suspend fun transferMoney(from: Long, to: Long, amount: BigDecimal) {
        transactionalOperator.executeAndAwait {
            val fromAccount = accountRepository.findById(from)
                ?: throw AccountNotFoundException(from)
            val toAccount = accountRepository.findById(to)
                ?: throw AccountNotFoundException(to)

            if (fromAccount.balance < amount) {
                throw InsufficientFundsException()
            }

            accountRepository.save(fromAccount.copy(balance = fromAccount.balance - amount))
            accountRepository.save(toAccount.copy(balance = toAccount.balance + amount))
        }
    }
}

// ✅ CORRECT - @Transactional with suspend
@Service
class OrderService(
    private val orderRepository: OrderRepository,
    private val inventoryRepository: InventoryRepository
) {
    @Transactional
    suspend fun createOrder(order: Order): Order {
        val savedOrder = orderRepository.save(order)
        inventoryRepository.decrementStock(order.productId, order.quantity)
        return savedOrder
    }
}

db-connection-pool - Configure Connection Pool

Impact: Resource efficiency, connection reuse

// ✅ CORRECT - R2DBC pool configuration
@Configuration
class R2dbcConfig {

    @Bean
    fun connectionFactory(): ConnectionFactory {
        val connectionFactory = ConnectionFactories.get(
            ConnectionFactoryOptions.builder()
                .option(DRIVER, "pool")
                .option(PROTOCOL, "postgresql")
                .option(HOST, "localhost")
                .option(DATABASE, "mydb")
                .option(USER, System.getenv("DB_USER"))
                .option(PASSWORD, System.getenv("DB_PASSWORD"))
                .build()
        )

        val poolConfig = ConnectionPoolConfiguration.builder(connectionFactory)
            .maxIdleTime(Duration.ofMinutes(10))
            .maxSize(20)
            .initialSize(5)
            .maxCreateConnectionTime(Duration.ofSeconds(5))
            .validationQuery("SELECT 1")
            .build()

        return ConnectionPool(poolConfig)
    }
}

// application.yml alternative
# spring:
#   r2dbc:
#     url: r2dbc:pool:postgresql://localhost/mydb
#     pool:
#       initial-size: 5
#       max-size: 20
#       max-idle-time: 10m

db-n-plus-one - Avoid N+1 Queries

Impact: Query optimization, reduced database load

// ❌ INCORRECT - N+1 queries
suspend fun getUsersWithOrders(): List<UserWithOrders> {
    val users = userRepository.findAll().toList()
    return users.map { user ->
        val orders = orderRepository.findByUserId(user.id).toList()  // N queries!
        UserWithOrders(user, orders)
    }
}

// ✅ CORRECT - batch fetch with join or single query
@Repository
interface UserRepository : CoroutineCrudRepository<User, Long> {

    @Query("""
        SELECT u.*, o.* FROM users u
        LEFT JOIN orders o ON u.id = o.user_id
        WHERE u.status = 'ACTIVE'
    """)
    fun findActiveUsersWithOrders(): Flow<UserWithOrders>
}

// ✅ CORRECT - manual batching
suspend fun getUsersWithOrders(): List<UserWithOrders> {
    val users = userRepository.findAll().toList()
    val userIds = users.map { it.id }

    // Single batch query for all orders
    val ordersByUser = orderRepository.findByUserIdIn(userIds)
        .toList()
        .groupBy { it.userId }

    return users.map { user ->
        UserWithOrders(user, ordersByUser[user.id] ?: emptyList())
    }
}

db-migration - Use Flyway/Liquibase

Impact: Schema version control, safe migrations

// ✅ CORRECT - Flyway configuration for R2DBC
// build.gradle.kts
dependencies {
    implementation("org.flywaydb:flyway-core")
    runtimeOnly("org.postgresql:postgresql")  // for migrations
}

// application.yml
# spring:
#   flyway:
#     enabled: true
#     locations: classpath:db/migration
#     url: jdbc:postgresql://localhost/mydb  # JDBC for Flyway
#     user: ${DB_USER}
#     password: ${DB_PASSWORD}
#   r2dbc:
#     url: r2dbc:postgresql://localhost/mydb  # R2DBC for app

// ✅ CORRECT - migration script V1__create_users.sql
/*
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    name VARCHAR(255) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
*/

5. Error Handling (HIGH)

err-supervisor - Use SupervisorJob Correctly

Impact: Fault isolation, independent failure handling

// ❌ INCORRECT - SupervisorJob without exception handler
val scope = CoroutineScope(SupervisorJob())

scope.launch {
    throw Exception("Unhandled!")  // crashes the app on Android, logged on server
}

// ✅ CORRECT - SupervisorJob with CoroutineExceptionHandler
val exceptionHandler = CoroutineExceptionHandler { _, exception ->
    logger.error("Coroutine failed", exception)
    errorReporter.report(exception)
}

val scope = CoroutineScope(
    SupervisorJob() +
    Dispatchers.Default +
    exceptionHandler
)

// ✅ CORRECT - handle exceptions in each child
scope.launch {
    try {
        riskyOperation()
    } catch (e: Exception) {
        logger.error("Operation failed", e)
        // handle gracefully
    }
}

err-handler - Use CoroutineExceptionHandler

Impact: Centralized error handling for uncaught exceptions

// ✅ CORRECT - global exception handler
@Configuration
class CoroutineExceptionConfig {

    @Bean
    fun coroutineExceptionHandler(): CoroutineExceptionHandler {
        return CoroutineExceptionHandler { context, exception ->
            val name = context[CoroutineName]?.name ?: "unknown"
            logger.error("Coroutine '$name' failed", exception)

            when (exception) {
                is CancellationException -> {
                    // Normal cancellation, don't report
                }
                is NetworkException -> {
                    // Retry logic or user notification
                    retryQueue.add(context)
                }
                else -> {
                    errorReporter.report(exception)
                }
            }
        }
    }

    @Bean
    fun applicationScope(handler: CoroutineExceptionHandler): CoroutineScope {
        return CoroutineScope(SupervisorJob() + Dispatchers.Default + handler)
    }
}

err-try-catch - Catch Exceptions in Coroutines

Impact: Proper error recovery, graceful degradation

// ❌ INCORRECT - unhandled exception in async
suspend fun fetchData(): Data = coroutineScope {
    val result = async {
        riskyNetworkCall()  // exception not caught by try-catch below
    }

    try {
        result.await()
    } catch (e: Exception) {
        // This catches, but coroutineScope already cancelled!
        defaultData()
    }
}

// ✅ CORRECT - catch at the source
suspend fun fetchData(): Data = coroutineScope {
    val result = async {
        try {
            riskyNetworkCall()
        } catch (e: Exception) {
            logger.warn("Network call failed, using default", e)
            defaultData()
        }
    }
    result.await()
}

// ✅ CORRECT - use supervisorScope for independent failures
suspend fun fetchData(): Data = supervisorScope {
    val result = async {
        riskyNetworkCall()
    }

    try {
        result.await()
    } catch (e: Exception) {
        defaultData()
    }
}

// ✅ CORRECT - use runCatching
suspend fun fetchDataSafe(): Result<Data> {
    return runCatching {
        riskyNetworkCall()
    }
}

err-cancellation - Handle CancellationException Properly

Impact: Correct cancellation propagation, resource cleanup

// ❌ INCORRECT - swallowing CancellationException
suspend fun processItems(items: List<Item>) {
    items.forEach { item ->
        try {
            processItem(item)
        } catch (e: Exception) {  // catches CancellationException!
            logger.error("Failed", e)
            // Cancellation is swallowed, coroutine continues!
        }
    }
}

// ✅ CORRECT - rethrow CancellationException
suspend fun processItems(items: List<Item>) {
    items.forEach { item ->
        try {
            processItem(item)
        } catch (e: CancellationException) {
            throw e  // always rethrow!
        } catch (e: Exception) {
            logger.error("Failed to process ${item.id}", e)
        }
    }
}

// ✅ CORRECT - use runCatching which handles this
suspend fun processItems(items: List<Item>) {
    items.forEach { item ->
        runCatching {
            processItem(item)
        }.onFailure { e ->
            if (e is CancellationException) throw e
            logger.error("Failed to process ${item.id}", e)
        }
    }
}

// ✅ CORRECT - cleanup with try-finally
suspend fun processWithResource() {
    val resource = acquireResource()
    try {
        process(resource)
    } finally {
        withContext(NonCancellable) {
            resource.close()  // cleanup even on cancellation
        }
    }
}

err-flow-catch - Use catch Operator in Flow

Impact: Flow error handling without breaking collection

// ❌ INCORRECT - exception breaks entire flow
fun getUpdates(): Flow<Update> = flow {
    while (true) {
        val update = fetchUpdate()  // throws on network error
        emit(update)
        delay(1000)
    }
}

// ✅ CORRECT - catch and recover
fun getUpdates(): Flow<Update> = flow {
    while (true) {
        val update = fetchUpdate()
        emit(update)
        delay(1000)
    }
}.catch { e ->
    logger.error("Update fetch failed", e)
    emit(Update.error(e.message))  // emit error state
}

// ✅ CORRECT - retry on error
fun getUpdates(): Flow<Update> = flow {
    val update = fetchUpdate()
    emit(update)
}.retry(3) { e ->
    e is NetworkException  // retry only network errors
}.catch { e ->
    emit(Update.error("Failed after retries"))
}

// ✅ CORRECT - onEach for side effects, catch for errors
fun processNotifications(): Flow<Notification> {
    return notificationSource
        .onEach { notification ->
            analyticsService.track(notification)
        }
        .catch { e ->
            logger.error("Notification processing failed", e)
            // don't emit, just log
        }
}

err-retry - Implement Retry with Backoff

Impact: Resilience for transient failures

// ✅ CORRECT - retry with exponential backoff
suspend fun <T> retryWithBackoff(
    maxRetries: Int = 3,
    initialDelay: Long = 100,
    maxDelay: Long = 1000,
    factor: Double = 2.0,
    block: suspend () -> T
): T {
    var currentDelay = initialDelay
    repeat(maxRetries - 1) { attempt ->
        try {
            return block()
        } catch (e: Exception) {
            if (e is CancellationException) throw e
            logger.warn("Attempt ${attempt + 1} failed, retrying in ${currentDelay}ms", e)
        }
        delay(currentDelay)
        currentDelay = (currentDelay * factor).toLong().coerceAtMost(maxDelay)
    }
    return block()  // last attempt, let it throw
}

// Usage
suspend fun fetchDataWithRetry(): Data {
    return retryWithBackoff(maxRetries = 3) {
        apiClient.fetchData()
    }
}

// ✅ CORRECT - retry in Flow
fun getDataStream(): Flow<Data> = flow {
    while (currentCoroutineContext().isActive) {
        emit(fetchData())
        delay(5000)
    }
}.retryWhen { cause, attempt ->
    if (cause is NetworkException && attempt < 3) {
        delay(1000L * (attempt + 1))
        true  // retry
    } else {
        false  // give up
    }
}

6. Spring WebFlux (MEDIUM)

webflux-controller - Use Suspend in Controllers

Impact: Non-blocking endpoints, efficient resource use

// ✅ CORRECT - suspend function in controller
@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {
    @GetMapping("/{id}")
    suspend fun getUser(@PathVariable id: Long): User {
        return userService.findById(id)
            ?: throw ResponseStatusException(HttpStatus.NOT_FOUND)
    }

    @GetMapping
    fun getAllUsers(): Flow<User> {  // Flow for streaming
        return userService.findAll()
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    suspend fun createUser(@RequestBody user: User): User {
        return userService.save(user)
    }
}

webflux-coRouter - Use coRouter DSL

Impact: Coroutine-friendly functional routing

// ✅ CORRECT - coRouter for functional endpoints
@Configuration
class RouterConfig(
    private val userHandler: UserHandler
) {
    @Bean
    fun userRoutes() = coRouter {
        "/api/users".nest {
            GET("", userHandler::getAllUsers)
            GET("/{id}", userHandler::getUser)
            POST("", userHandler::createUser)
            PUT("/{id}", userHandler::updateUser)
            DELETE("/{id}", userHandler::deleteUser)
        }

        filter { request, next ->
            // logging filter
            val start = System.currentTimeMillis()
            val response = next(request)
            val duration = System.currentTimeMillis() - start
            logger.info("${request.method()} ${request.path()} - ${duration}ms")
            response
        }
    }
}

@Component
class UserHandler(
    private val userService: UserService
) {
    suspend fun getUser(request: ServerRequest): ServerResponse {
        val id = request.pathVariable("id").toLong()
        val user = userService.findById(id)
        return if (user != null) {
            ServerResponse.ok().bodyValueAndAwait(user)
        } else {
            ServerResponse.notFound().buildAndAwait()
        }
    }

…(truncated)