제약(bound) — 아무 타입이나 받지 않기

// 상한 하나
fun <T : Number> sum(list: List<T>): Double =
    list.sumOf { it.toDouble() }

// 여러 제약은 where 로
fun <T> process(items: List<T>): List<T>
        where T : Comparable<T>,
              T : CharSequence =
    items.filter { it.isNotEmpty() }.sorted()

// 기본 상한은 Any? — null 을 막으려면 Any 를 적는다
fun <T : Any> requireAll(list: List<T?>): List<T> =
    list.map { it ?: error("null 원소 발견") }

실무 형태 — 공통 리포지터리

interface Entity { val id: Long }

interface CrudRepository<T : Entity> {
    fun findById(id: Long): T?
    fun save(entity: T): T
    fun findAll(): List<T>
}

// 공통 동작을 기본 구현으로
fun <T : Entity> CrudRepository<T>.findOrThrow(id: Long): T =
    findById(id) ?: throw NoSuchElementException("없음: $id")

// 사용
class UserRepo : CrudRepository<User> { /* ... */ }
val user: User = userRepo.findOrThrow(1)   // 타입이 User 로 그대로

out — 꺼내기만 하는 타입

open class Animal(val name: String)
class Dog(name: String) : Animal(name)

// 코틀린 표준 List 선언: public interface List<out E>
val dogs: List<Dog> = listOf(Dog("바둑이"))
val animals: List<Animal> = dogs      // ✅ out 이라 대입된다

// 내가 만드는 생산자 타입에도 붙인다
interface Producer<out T> {
    fun produce(): T
    // fun consume(item: T)   // ❌ 컴파일 에러 — out 은 '인자'로 못 쓴다
}

// 반환 위치에만 T 가 나타나면 out 을 붙일 수 있다
class Repo<out T>(private val items: List<T>) {
    fun all(): List<T> = items
}

in — 넣기만 하는 타입

// Comparator 선언: public interface Comparator<in T>
val animalCmp = Comparator<Animal> { a, b -> a.name.compareTo(b.name) }
val dogCmp: Comparator<Dog> = animalCmp   // ✅ in 이라 대입된다
// 동물을 비교할 줄 알면 개도 비교할 수 있다 — 당연한 이야기다

interface Consumer<in T> {
    fun consume(item: T)
    // fun produce(): T      // ❌ in 은 '반환'에 못 쓴다
}

// 함수 타입이 대표적 — (in P) -> (out R)
// public interface Function1<in P1, out R>
val f: (Animal) -> String = { it.name }
val g: (Dog) -> Any = f              // ✅ 인자는 넓게, 반환은 좁게

JSON 역직렬화 · API 클라이언트

// 자바 스타일 — Class 를 인자로 받아야 했다
fun <T> parse(json: String, clazz: Class<T>): T = mapper.readValue(json, clazz)
val u1 = parse(json, User::class.java)

// 코틀린 — 타입만 적으면 된다
inline fun <reified T> parse(json: String): T =
    mapper.readValue(json, object : TypeReference<T>() {})

val u2: User = parse(json)                 // 추론까지 된다
val list = parse<List<User>>(json)         // 제네릭 중첩도 가능

// 실제 라이브러리들이 전부 이 방식이다
// kotlinx.serialization: Json.decodeFromString<User>(text)
// Ktor Client:           client.get(url).body<User>()
// Spring 6:              restClient.get().retrieve().body<User>()

안드로이드 · DI · 로거

// 화면 이동 (안드로이드)
inline fun <reified T : Activity> Context.start() =
    startActivity(Intent(this, T::class.java))
start<DetailActivity>()

// 의존성 조회
inline fun <reified T> Injector.get(): T = get(T::class)
val repo: UserRepo = injector.get()

// 클래스별 로거 — 자바에서 늘 쓰던 상용구가 사라진다
inline fun <reified T> T.logger(): Logger =
    LoggerFactory.getLogger(T::class.java)

class OrderService {
    private val log = logger()
}

언제 붙이나 · 언제 안 붙이나

noinline · crossinline

// noinline — 이 람다만 펼치지 않는다 (객체로 남겨 저장·전달해야 할 때)
inline fun run2(
    before: () -> Unit,
    noinline after: () -> Unit,     // 나중에 쓰려고 보관해야 한다
) {
    before()
    handlers += after               // 펼쳐진 코드는 저장할 수 없다
}

// crossinline — 펼치되 '비지역 반환'만 금지한다
inline fun async2(crossinline block: () -> Unit) {
    Thread {
        block()      // 다른 실행 흐름 안에서 부른다
        // 여기서 return 이 허용되면 어디로 돌아가야 하나? → 그래서 금지
    }.start()
}

측정 없이 믿지 마세요

JIT는 대부분의 작은 람다 호출을 인라이닝해 버립니다. 수억 번 도는 루프가 아니면 체감 차이가 없는 경우가 많습니다. inline의 진짜 가치는 세 가지입니다.

• reified를 쓸 수 있다
• 비지역 반환이 된다 (제어 흐름 표현력)
• 안드로이드처럼 객체 생성이 곧 GC 압력인 환경에서 이득

확인하는 법 — 바이트코드 보기

IntelliJ 메뉴
  Tools → Kotlin → Show Kotlin Bytecode
  → [Decompile] 버튼을 누르면 '자바로 치면 이런 코드'가 나온다

무엇을 보나
  · 람다가 클래스로 만들어졌는지 (Function0 · Function1)
  · inline 함수가 정말 펼쳐졌는지
  · data class 가 어떤 equals 를 만들었는지
  · suspend 함수가 어떤 상태 기계로 바뀌었는지  ← 코루틴 탭에서 다시 봅니다

표준 위임 넷

import kotlin.properties.Delegates

class Config(map: Map<String, Any>) {
    // 1) lazy — 처음 읽을 때 한 번만 계산
    val heavy: String by lazy { loadFromDisk() }

    // 2) observable — 바뀔 때마다 알림
    var status: String by Delegates.observable("NEW") { _, old, new ->
        log.info("상태 변경 {} → {}", old, new)
    }

    // 3) vetoable — 조건을 통과할 때만 반영
    var age: Int by Delegates.vetoable(0) { _, _, new -> new in 0..150 }

    // 4) 맵 위임 — 키 이름으로 값을 꺼낸다
    val name: String by map
    val port: Int by map
}

val c = Config(mapOf("name" to "서버1", "port" to 8080))
println(c.name)         // 서버1  (map["name"] 를 읽는다)
c.age = 200             // 무시된다 (vetoable 이 거부)
println(c.age)          // 0

notNull · 다른 프로퍼티에 위임

class Service {
    // lateinit 을 못 쓰는 기본 타입에 쓴다
    var port: Int by Delegates.notNull()
}

// 이름을 바꿀 때 — 옛 이름을 남기며 새 이름으로 위임 (1.4+)
class User(val fullName: String) {
    @Deprecated("name 대신 fullName")
    val name: String by this::fullName
}

// 최상위 프로퍼티에도 쓸 수 있다
val version: String by lazy {
    // 최상위에는 this 가 없어 javaClass 를 바로 못 쓴다 → 익명 객체로 클래스를 얻는다
    object {}.javaClass.getResource("/version.txt")?.readText() ?: "dev"
}

provideDelegate — 만들 때 검증하기

// 프로퍼티가 '만들어지는 시점'에 개입한다
class RequiredEnv(private val key: String) {
    operator fun provideDelegate(thisRef: Any?, prop: KProperty<*>): EnvDelegate {
        // 앱이 뜰 때 바로 검증 — 나중에 처음 읽을 때가 아니라
        require(System.getenv(key) != null) {
            "환경변수 $key 가 없습니다 (프로퍼티 ${prop.name})"
        }
        return EnvDelegate(key)
    }
}

설정 누락을 기동 시점에 잡을 수 있습니다 — 운영에서 특정 API가 호출될 때야 터지는 것보다 훨씬 낫습니다.

실무에서 만나는 위임들

값 객체에 연산 열기

@JvmInline
value class Money(val won: Long) : Comparable<Money> {
    operator fun plus(o: Money) = Money(won + o.won)
    operator fun minus(o: Money) = Money(won - o.won)
    operator fun times(n: Int) = Money(won * n)
    operator fun unaryMinus() = Money(-won)
    override fun compareTo(other: Money) = won.compareTo(other.won)
    override fun toString() = "%,d원".format(won)
}

val total = Money(10_000) + Money(2_500) * 2
println(total)                    // 15,000원
println(Money(100) < Money(200))  // true
println(listOf(Money(300), Money(100)).sorted())   // Comparable 이라 정렬된다

get · invoke · contains

class Matrix(private val rows: Int, private val cols: Int) {
    private val data = DoubleArray(rows * cols)
    operator fun get(r: Int, c: Int) = data[r * cols + c]
    operator fun set(r: Int, c: Int, v: Double) { data[r * cols + c] = v }
}
val m = Matrix(3, 3)
m[0, 0] = 1.5
println(m[0, 0])

// invoke — 객체를 함수처럼 부른다 (전략·유스케이스 패턴에서 흔하다)
class GetUser(private val repo: UserRepo) {
    operator fun invoke(id: Long): User? = repo.find(id)
}
val getUser = GetUser(repo)
val u = getUser(1)          // getUser.invoke(1)

// contains — 도메인 표현을 자연스럽게
class DateRange(val start: LocalDate, val end: LocalDate) {
    operator fun contains(d: LocalDate) = d >= start && d <= end
}
if (today in eventPeriod) { /* ... */ }

@DslMarker — 바깥 스코프가 새는 것을 막는다

// @DslMarker 가 없으면 이런 코드가 컴파일된다
html {
    body {
        body { }      // ❌ 말이 안 되는데 바깥 this 가 보여서 가능했다
    }
}

// @DslMarker 를 붙이면
// "암시적 수신 객체가 두 개면 가장 안쪽만 쓸 수 있다"는 규칙이 켜진다
// → 위 코드는 컴파일 에러가 된다

// 정말 바깥을 써야 하면 이름을 붙여 쓴다
html {
    val outer = this
    body { outer.attr("lang", "ko") }
}

실무에서 쓸 만한 작은 DSL

// 테스트 픽스처 빌더
class UserBuilder {
    var id: Long = 1
    var name: String = "테스트"
    var roles: MutableList<String> = mutableListOf()
    fun role(r: String) { roles += r }
    fun build() = User(id, name, roles.toList())
}
fun user(block: UserBuilder.() -> Unit) = UserBuilder().apply(block).build()

val u = user {
    name = "김현우"
    role("ADMIN")
    role("USER")
}

// 검증 DSL
class Validation(private val errors: MutableList<String> = mutableListOf()) {
    fun check(cond: Boolean, msg: String) { if (!cond) errors += msg }
    fun result() = errors.toList()
}
fun validate(block: Validation.() -> Unit) = Validation().apply(block).result()

val errs = validate {
    check(order.amount > 0, "금액 오류")
    check(order.items.isNotEmpty(), "빈 주문")
}

만들기 · 무한 수열

// 컬렉션에서
val s1 = listOf(1, 2, 3).asSequence()

// 원소 나열
val s2 = sequenceOf(1, 2, 3)

// 규칙으로 무한 생성 — null 을 돌려주면 끝난다
val powers = generateSequence(1) { it * 2 }
println(powers.take(10).toList())   // [1,2,4,...,512]

// 파일 한 줄씩 (메모리에 다 올리지 않는다)
File("big.log").useLines { lines ->
    lines.filter { "ERROR" in it }.take(100).toList()
}

// yield 로 직접 만들기 — 코루틴 문법을 쓴다
val fib = sequence {
    var (a, b) = 0 to 1
    while (true) {
        yield(a)                 // 여기서 멈췄다가 다음에 이어서 실행된다
        a = b.also { b = a + b }
    }
}
println(fib.take(8).toList())     // [0,1,1,2,3,5,8,13]

중간 연산과 종단 연산

// 중간(Intermediate) — 시퀀스를 돌려준다. 아직 아무 일도 안 한다
// map · filter · take · drop · distinct · sortedBy(예외) · flatMap · onEach

// 종단(Terminal) — 여기서 비로소 실행된다
// toList · first · sum · count · any · all · forEach · fold · joinToString

val seq = (1..10).asSequence()
    .onEach { println("보는 중: $it") }    // 아직 출력 안 됨
    .filter { it % 2 == 0 }

println("아직 실행 전")
println(seq.toList())                      // 여기서 한꺼번에 실행

// ⚠️ sorted 계열은 '상태를 모아야' 하므로 전부 읽는다 (지연의 이점이 사라진다)
// ⚠️ 시퀀스는 기본적으로 '한 번만' 소비할 수 있는 것이 많다 (constrainOnce)

정렬 — Comparator 조립

data class Emp(val dept: String, val level: Int, val name: String, val joined: LocalDate?)

// 부서 오름차순 → 직급 내림차순 → 이름 오름차순
val sorted = emps.sortedWith(
    compareBy<Emp> { it.dept }
        .thenByDescending { it.level }
        .thenBy { it.name }
)

// null 을 뒤로 (또는 앞으로)
val byJoined = emps.sortedWith(compareBy(nullsLast()) { it.joined })

// 한글 정렬 — 로케일을 명시해야 자모 순서가 맞는다
val ko = Collator.getInstance(Locale.KOREAN)
val names = emps.map { it.name }.sortedWith(ko)

// 사용자 정의 순서 (등급표 순서대로)
val order = listOf("VIP", "GOLD", "SILVER")
val byGrade = users.sortedBy { order.indexOf(it.grade) }

// 안정 정렬이다 — 같은 키면 원래 순서가 유지된다 (자바 List.sort 와 동일)

한 번 순회로 여러 값 얻기

// ❌ 세 번 순회
val cnt = orders.count { it.paid }
val sum = orders.filter { it.paid }.sumOf { it.amount }
val max = orders.filter { it.paid }.maxOfOrNull { it.amount }

// ✅ 한 번에 — fold 로 누산기를 굴린다
data class Agg(val count: Int = 0, val sum: Long = 0, val max: Long = 0)

val agg = orders.asSequence().filter { it.paid }.fold(Agg()) { a, o ->
    Agg(a.count + 1, a.sum + o.amount, maxOf(a.max, o.amount))
}

// 그룹별 집계는 groupingBy + aggregate 가 가장 빠르다 (중간 리스트를 안 만든다)
val sumByCity: Map<String, Long> = orders
    .groupingBy { it.city }
    .fold(0L) { acc, o -> acc + o.amount }

val countByCity = orders.groupingBy { it.city }.eachCount()

알아 두면 좋은 함수들

listOf(1,2,3,4).zipWithNext()          // [(1,2),(2,3),(3,4)] 연속 비교
listOf(1,2,3).runningFold(0) { a,b -> a+b }  // [0,1,3,6] 누적 합
listOf(3,1,2).sortedDescending()
listOf("a","b").withIndex()
listOf(1,2,3).sumOf { it.toLong() }    // 오버플로 방지 (Long 으로 누적)
listOf(1,2,2,3).groupingBy { it }.eachCount()   // 빈도수
list.chunked(1000) { batch -> repo.saveAll(batch) }  // 배치 저장
list.windowed(3, step = 1, partialWindows = false)   // 이동 평균
list.distinctBy { it.email }           // 특정 키로 중복 제거
list.ifEmpty { listOf(default) }       // 비었으면 대체
list.requireNoNulls()                  // null 있으면 예외

동시성 컬렉션 — 코틀린엔 따로 없다

// 자바 것을 그대로 쓴다
val cache = ConcurrentHashMap<Long, User>()
val queue = ConcurrentLinkedQueue<Task>()
val counter = AtomicLong()

// getOrPut 은 원자적이지 않다! (읽고-없으면-쓰기 사이에 틈이 있다)
// ❌ cache.getOrPut(id) { load(id) }
// ✅ 자바 API 를 쓴다
val u = cache.computeIfAbsent(id) { load(it) }

// 코루틴 환경이라면 Mutex 나 채널이 더 자연스럽다 — 코루틴 탭 참고

value class 의 규칙과 한계

• 프로퍼티는 하나(val)만. @JvmInline이 필요합니다
• 함수·계산 프로퍼티는 가질 수 있습니다 (검증 로직도 init에)
• 박싱되는 경우가 있습니다 — 컬렉션에 담거나(List<Money>), 제네릭·nullable(Money?)로 쓰거나, 인터페이스로 다룰 때
• 자바에서는 이름이 뒤틀립니다(맹글링) — 자바에서 부를 API 라면 주의

@JvmInline
value class Email(val value: String) {
    init { require("@" in value) { "이메일 형식 오류: $value" } }
    val domain: String get() = value.substringAfter("@")
}
println(Email("a@b.com").domain)   // b.com

typealias — 이름만 바꾼다 (타입 안전 아님)

typealias UserId = Long
typealias Handler = (Request) -> Response
typealias UserCache = MutableMap<UserId, User>

fun find(id: UserId) { }
find(123L)          // ✅ 그냥 Long 이라 통과 — 안전장치가 아니다

// 쓰는 자리
// · 긴 제네릭 타입에 이름 붙이기 (가독성)
// · 함수 타입에 이름 붙이기
// · 이름 충돌 회피 (import 별칭)
import java.util.Date as JavaDate
import kotlinx.datetime.Instant as KtInstant

두 종류의 계약

// 1) returns(...) implies (...) — 반환값이 알려 주는 사실
@OptIn(ExperimentalContracts::class)
fun Any?.isUser(): Boolean {
    contract { returns(true) implies (this@isUser is User) }
    return this is User
}

// 2) callsInPlace — 람다가 언제 몇 번 불리는지
@OptIn(ExperimentalContracts::class)
inline fun <T> measure(block: () -> T): T {
    contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) }
    val t = System.nanoTime()
    return block().also { println("${System.nanoTime() - t}ns") }
}

// EXACTLY_ONCE 를 선언했기 때문에 이게 컴파일된다
val name: String
measure { name = loadName() }     // val 을 람다 안에서 초기화
println(name)                     // '반드시 한 번' 실행됨을 컴파일러가 안다

표준 라이브러리가 쓰는 곳

KClass · 자바 Class 오가기

import kotlin.reflect.full.*

data class User(val id: Long, val name: String, val email: String?)

val kc = User::class                 // KClass<User>
val jc = User::class.java            // Class<User>   ← 자바 API 에 넘길 때
val back = jc.kotlin                 // 다시 KClass

println(kc.simpleName)               // User
println(kc.qualifiedName)            // com.example.User
println(kc.isData)                   // true
println(kc.memberProperties.map { it.name })   // [email, id, name]

// 인스턴스에서
val u = User(1, "김", null)
println(u::class.simpleName)         // User

// 프로퍼티 값 읽기
kc.memberProperties.forEach { p ->
    println("${p.name} = ${p.get(u)}")
}

프로퍼티 참조 · 애너테이션

// 프로퍼티 참조 — 리플렉션 없이도 이름을 얻는다
val ref = User::name
println(ref.name)                    // name
println(ref.get(u))                  // 김

// 커스텀 애너테이션 만들고 읽기
@Target(AnnotationTarget.PROPERTY)
@Retention(AnnotationRetention.RUNTIME)     // ← 런타임에 읽으려면 필수
annotation class Masked(val keep: Int = 2)

data class Account(
    @Masked(keep = 4) val cardNo: String,
    val owner: String,
)

fun mask(obj: Any): Map<String, Any?> =
    obj::class.memberProperties.associate { p ->
        val ann = p.annotations.filterIsInstance<Masked>().firstOrNull()
        val v = p.getter.call(obj)
        p.name to if (ann != null && v is String)
            v.takeLast(ann.keep).padStart(v.length, '*') else v
    }

println(mask(Account("1234567812345678", "김현우")))
// {cardNo=************5678, owner=김현우}

① 느리다

직접 호출 대비 수십~수백 배 느립니다. 요청마다 도는 경로에서는 결과를 캐시하세요 (스프링·Jackson도 전부 캐시합니다).

② 컴파일러가 못 지킨다

이름으로 접근하므로 이름을 바꾸면 런타임에 터집니다. 가능하면 User::name 같은 참조를 쓰세요 — 리네임 리팩터링이 따라옵니다.

③ 네이티브에서 막힌다

GraalVM 네이티브 이미지·안드로이드 R8에서는 리플렉션 대상을 미리 등록해야 합니다. 빌드 시점 생성(KSP)이 대안입니다 — 다음 섹션.

애너테이션 정의 — 세 가지를 정한다

@Target(                            // ① 어디에 붙일 수 있나
    AnnotationTarget.CLASS,
    AnnotationTarget.FUNCTION,
    AnnotationTarget.PROPERTY,
)
@Retention(AnnotationRetention.RUNTIME)  // ② 언제까지 남나
// SOURCE: 컴파일하면 사라짐 (린트용)
// BINARY: 클래스 파일에 남지만 리플렉션 불가
// RUNTIME: 리플렉션으로 읽을 수 있음 (기본값)
@MustBeDocumented
annotation class Audited(val action: String = "")

@Audited("주문생성")
fun createOrder() { }

// ③ 사용 지점 지정 — 코틀린은 프로퍼티가 여러 요소로 컴파일된다
class Dto(
    @field:NotNull       // 필드에
    @get:JsonProperty    // getter 에
    @param:JsonProperty  // 생성자 파라미터에
    val name: String,
)

KSP 설정과 실제 프로세서

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.2.0"
    id("com.google.devtools.ksp") version "2.2.0-2.0.2"
}
dependencies {
    implementation("androidx.room:room-runtime:2.7.0")
    ksp("androidx.room:room-compiler:2.7.0")   // ← annotationProcessor 대신 ksp
}

// 프로세서를 직접 만드는 뼈대 (라이브러리 제작자용)
class MyProcessor(private val gen: CodeGenerator) : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSAnnotated> {
        resolver.getSymbolsWithAnnotation("com.example.Audited")
            .filterIsInstance<KSFunctionDeclaration>()
            .forEach { fn ->
                gen.createNewFile(Dependencies(false), "gen", "${fn.simpleName.asString()}Log")
                    .writer().use { it.write("// 생성된 코드") }
            }
        return emptyList()
    }
}

함수 합성 · 부분 적용 · 커링

// 합성 — 표준 라이브러리에는 없으니 직접 만든다 (두 줄이면 된다)
infix fun <A, B, C> ((A) -> B).then(g: (B) -> C): (A) -> C = { a -> g(this(a)) }

val trim: (String) -> String = String::trim
val upper: (String) -> String = String::uppercase
val clean = trim then upper
println(clean("  hi  "))        // HI

// 부분 적용 — 인자를 미리 채운 새 함수
fun log(level: String, tag: String, msg: String) = println("[$level][$tag] $msg")
val debug: (String, String) -> Unit = { tag, msg -> log("DEBUG", tag, msg) }
debug("Order", "생성됨")

// 커링
fun sum3(a: Int) = { b: Int -> { c: Int -> a + b + c } }
println(sum3(1)(2)(3))          // 6

// 메모이제이션
fun <A, R> ((A) -> R).memoize(): (A) -> R {
    val cache = mutableMapOf<A, R>()
    return { a -> cache.getOrPut(a) { this(a) } }
}
val slowSquare = { n: Int -> Thread.sleep(100); n * n }.memoize()

불변 데이터 다루기

data class Address(val city: String, val zip: String)
data class User(val name: String, val address: Address, val tags: List<String>)

val u = User("김", Address("서울", "01234"), listOf("vip"))

// 중첩 객체 수정 — copy 를 겹쳐 쓴다
val moved = u.copy(address = u.address.copy(city = "부산"))

// 리스트 수정도 새 리스트로
val tagged = u.copy(tags = u.tags + "신규")
val untagged = u.copy(tags = u.tags - "vip")

// 깊이가 3단을 넘어가면 확장 함수로 렌즈를 만든다
fun User.withCity(city: String) = copy(address = address.copy(city = city))
val m2 = u.withCity("대구")

① nullable

fun find(id: Long): User? = repo.get(id)

val name = find(1)?.name ?: "없음"

실패 이유가 하나뿐일 때. 가장 가볍고 코틀린답습니다.

② sealed 결과 타입

sealed interface Res<out T> {
    data class Ok<T>(val v: T) : Res<T>
    data class Err(val e: AppError) : Res<Nothing>
}

실패 종류가 여럿이고 호출부가 구분해야 할 때. 실무 기본값입니다.

③ Arrow Either

// arrow-kt 라이브러리
val r: Either<Err, User> = either {
    val u = find(id).bind()
    validate(u).bind()
    u
}

연산을 여러 번 이어 붙일 때 편합니다. 팀 학습 비용을 고려해 도입하세요.

알아 두면 편한 것들

// 시간 재기 (kotlin.time)
val elapsed = measureTime { heavyWork() }
println(elapsed)                       // 1.234s
val (result, t) = measureTimedValue { compute() }

// Duration
val timeout = 3.seconds + 500.milliseconds
delay(timeout)                         // 코루틴에서

// 랜덤
val pick = listOf("a","b","c").random()
val shuffled = (1..10).shuffled()
Random(42).nextInt(1, 100)             // 시드 고정 (테스트에 유용)

// 범위 보정
val page = input.coerceIn(1, 100)
val safe = value.coerceAtLeast(0)

// 반복
repeat(3) { i -> println(i) }

// 아직 안 만든 자리 — 컴파일은 되고 실행하면 예외
fun todo(): String = TODO("나중에 구현")

직접 만들기 전에 찾는 요령

• IntelliJ에서 타입 뒤에 점을 찍고 기다리세요 — 그 타입의 확장 함수가 전부 나옵니다
• xxxOrNull, xxxIndexed, xxxNotNull, xxxTo 접미사 규칙을 알면 이름을 추측할 수 있습니다
• mapTo(destination)처럼 To로 끝나는 것은 결과를 기존 컬렉션에 담는 버전입니다 (할당을 줄일 때)
• 표준 라이브러리 소스는 IntelliJ에서 Ctrl+B로 바로 읽힙니다 — 가장 좋은 코틀린 교재입니다

성능 관련 오해 셋

• “코틀린은 자바보다 느리다” — 같은 바이트코드로 갑니다. 차이가 나는 곳은 람다 객체·박싱·컬렉션 복사이고, 전부 피할 수 있습니다
• “data class 는 무겁다” — 자바에서 손으로 쓰던 equals·hashCode와 같은 코드입니다
• “전부 asSequence 로 바꾸면 빠르다” — 작은 컬렉션에서는 오히려 느립니다. 측정하고 바꾸세요

팀 규칙으로 정해 두면 좋은 것

• !! 금지 (detekt 규칙으로 강제 가능)
• public API 는 반환 타입 명시
• Boolean 인자는 이름 붙여 호출
• 컬렉션 반환은 읽기 전용 타입으로
• 도메인 식별자는 value class
• ktlint + detekt를 CI 에 넣기 — 실전 도구 탭에서 설정 방법을 다룹니다

콜백 지옥에서 나오는 길

// 콜백 — 세 단계만 되어도 읽기 어렵다
fun loadProfile(id: Long, cb: (Profile?) -> Unit) {
    api.getUser(id) { user ->
        if (user == null) { cb(null); return@getUser }
        api.getOrders(user.id) { orders ->
            api.getPoint(user.id) { point ->
                cb(Profile(user, orders, point))   // 에러 처리는 어디에?
            }
        }
    }
}

// 코루틴 — 동기 코드처럼 읽힌다
suspend fun loadProfile(id: Long): Profile {
    val user = api.getUser(id) ?: error("사용자 없음")
    val orders = api.getOrders(user.id)     // 여기서 '기다린다' (스레드는 안 묶임)
    val point = api.getPoint(user.id)
    return Profile(user, orders, point)
}
// try-catch 도 그냥 통한다. 취소도 자동으로 전파된다.

다른 방식과의 비교

delay 와 Thread.sleep 의 차이

runBlocking {
    val t = System.currentTimeMillis()
    // 코루틴 10만 개가 1초씩 기다린다
    val jobs = List(100_000) {
        launch { delay(1000) }        // 스레드를 반납하고 대기
    }
    jobs.joinAll()
    println("${System.currentTimeMillis() - t}ms")   // 약 1초대
}

// Thread.sleep(1000) 이었다면?
// runBlocking 안의 launch 는 runBlocking 스레드 하나를 같이 쓴다 → 한 번에 하나씩 자서 약 10만 초.
// (launch(Dispatchers.Default) 로 띄워도 코어 수만큼만 동시에 자고 나머지는 줄을 선다)

무엇이 “중단점(suspension point)”인가

suspend fun work() {
    println("A")            // 여기까지 스레드 T1
    delay(100)              // ← 중단점. 여기서 반납
    println("B")            // 재개 — T1 이 아닐 수도 있다!
    val x = fetch()         // ← 중단점 (suspend 함수 호출)
    println("C $x")
}

// 중단점이 되는 것
// · delay() · yield()
// · 다른 suspend 함수 호출
// · Channel.send/receive · Flow.collect
// · Job.join() · Deferred.await() · Mutex.lock()

// 중단점이 아닌 것 (그냥 실행된다)
// · 일반 함수 호출 · 반복문 · 계산

재개될 때 다른 스레드일 수 있다는 점이 중요합니다 — ThreadLocal에 담아 둔 값(MDC·시큐리티 컨텍스트)이 사라지는 원인입니다 (11 · 코루틴 컨텍스트).

순차 vs 병렬 — 실행 시간이 갈린다

suspend fun a(): Int { delay(1000); return 1 }
suspend fun b(): Int { delay(1000); return 2 }

// 순차 — 2초
suspend fun sequential(): Int {
    val x = a()      // 1초 기다림
    val y = b()      // 또 1초
    return x + y
}

// 병렬 — 1초
suspend fun parallel(): Int = coroutineScope {
    val x = async { a() }      // 시작만 하고 넘어간다
    val y = async { b() }
    x.await() + y.await()
}

// ⚠️ 흔한 실수 — 이건 여전히 2초다
suspend fun wrong(): Int = coroutineScope {
    val x = async { a() }.await()   // 시작하자마자 기다린다
    val y = async { b() }.await()
    x + y
}

runBlocking — 쓰면 안 되는 자리

// ❌ 컨트롤러·서비스 안에서 runBlocking
@GetMapping("/users/{id}")
fun get(@PathVariable id: Long): User = runBlocking {   // 스레드를 묶어 버린다
    service.find(id)
}

// ✅ 스프링에서는 컨트롤러 함수 자체를 suspend 로
@GetMapping("/users/{id}")
suspend fun get(@PathVariable id: Long): User = service.find(id)

// runBlocking 이 맞는 자리
// · fun main() = runBlocking { }
// · 테스트 (지금은 runTest 가 더 낫다)
// · 코루틴을 모르는 레거시 프레임워크와의 경계 (배치 잡 등)

coroutineScope — 다 끝나야 반환한다

suspend fun loadDashboard(): Dashboard = coroutineScope {
    val users = async { userApi.count() }
    val orders = async { orderApi.today() }
    val alerts = async { alertApi.pending() }

    // 셋이 모두 끝나야 이 줄이 실행된다
    Dashboard(users.await(), orders.await(), alerts.await())
}
// 이 함수가 반환되는 순간 '이 안에서 시작한 코루틴은 하나도 남아 있지 않다'
// 하나가 실패하면 나머지도 취소되고 예외가 위로 던져진다

Job — 코루틴의 손잡이

val job = scope.launch { work() }

job.isActive       // 실행 중인가
job.isCompleted    // 끝났는가 (성공·실패·취소 모두)
job.isCancelled    // 취소됐는가
job.cancel()       // 취소 요청
job.join()         // 끝날 때까지 기다림 (suspend)
job.cancelAndJoin()// 취소하고 정리까지 기다림

job.invokeOnCompletion { cause ->
    if (cause != null) log.warn("실패/취소: $cause")
    else log.info("정상 완료")
}

// 자식 목록도 볼 수 있다
job.children.forEach { println(it) }

플랫폼이 주는 스코프

직접 만들어야 할 때 — 서버 컴포넌트

@Component
class OutboxPublisher(
    private val repo: OutboxRepo,
) : DisposableBean {

    // SupervisorJob: 작업 하나가 실패해도 다른 작업이 죽지 않게
    private val scope = CoroutineScope(
        SupervisorJob() + Dispatchers.IO + CoroutineName("outbox")
    )

    @PostConstruct
    fun start() {
        scope.launch {
            while (isActive) {                  // 취소되면 루프가 끝난다
                runCatching { publishBatch() }
                    .onFailure { log.error("발행 실패", it) }
                delay(1000)
            }
        }
    }

    override fun destroy() {
        scope.cancel()      // 애플리케이션 종료 시 정리
    }
}

IO 와 Default 는 스레드를 공유한다

둘은 같은 스레드 풀을 쓰고 한도만 다릅니다. 그래서 Default → IO 전환은 스레드 교체 없이 일어나는 경우가 많아 비용이 작습니다.

// IO 한도를 늘리려면 (기본 64)
// JVM 옵션: -Dkotlinx.coroutines.io.parallelism=200

// 특정 작업만 동시 실행 수를 제한하고 싶을 때
val limitedIo = Dispatchers.IO.limitedParallelism(10)
withContext(limitedIo) { legacyJdbcCall() }
// ↑ DB 커넥션 풀 크기에 맞추는 용도로 아주 유용하다

잘못 고르면 생기는 일

• Default 에서 블로킹 IO — 코어 수만큼(예: 8개)만 스레드가 있으므로 전체 CPU 작업이 함께 멈춥니다. 가장 흔하고 치명적인 실수
• IO 에서 무거운 CPU 작업 — 64개 스레드가 CPU를 두고 경쟁해 컨텍스트 스위칭만 늘어납니다
• Main 에서 무거운 작업(안드로이드) — 화면이 멈추고 ANR
• 디스패처를 계속 왕복 — 전환마다 스케줄링 비용. 한 번에 묶어서 withContext로 감싸세요

취소를 알아채는 세 가지 방법

자원 정리 — finally 와 NonCancellable

val job = launch {
    val conn = openConnection()
    try {
        while (isActive) { process(conn) }
    } finally {
        // ⚠️ 취소된 코루틴에서는 suspend 함수를 부를 수 없다
        // conn.closeAsync()      // 즉시 CancellationException

        withContext(NonCancellable) {   // 이 블록만 취소를 무시한다
            conn.closeAsync()           // 정리는 반드시 끝내게
        }
    }
}

// use { } 도 그대로 통한다 (finally 기반)
suspend fun read() = File("a.txt").bufferedReader().use { it.readText() }

재시도 — 지수 백오프

suspend fun <T> retry(
    times: Int = 3,
    initialDelay: Duration = 200.milliseconds,
    maxDelay: Duration = 5.seconds,
    factor: Double = 2.0,
    retryOn: (Throwable) -> Boolean = { it is IOException },
    block: suspend () -> T,
): T {
    var delayTime = initialDelay
    repeat(times - 1) {
        try {
            return block()
        } catch (e: CancellationException) {
            throw e                          // 취소는 재시도하지 않는다
        } catch (e: Throwable) {
            if (!retryOn(e)) throw e         // 재시도해도 소용없는 에러는 즉시 던진다
            log.warn("재시도 예정 {}ms: {}", delayTime, e.message)
        }
        delay(delayTime)
        delayTime = (delayTime * factor).coerceAtMost(maxDelay)
    }
    return block()                           // 마지막 시도는 예외를 그대로 전파
}

// 사용
val user = retry(times = 3) { api.getUser(id) }

주의할 점

• 타임아웃은 취소로 동작합니다 — 블록 안에 중단점이 없으면 시간이 지나도 안 멈춥니다(07 참고)
• withTimeout의 예외는 CancellationException의 자식입니다. 바깥에서 catch (e: Exception)으로 잡으면 취소와 구분되지 않습니다
• 재시도에 지터(무작위 흔들림)를 넣으세요 — 모든 클라이언트가 같은 간격으로 재시도하면 동시에 다시 몰립니다
• 결제·주문처럼 부작용이 있는 호출은 재시도 전에 멱등키가 있는지 확인해야 합니다

// 지터 추가
val jitter = Random.nextLong(0, delayTime.inWholeMilliseconds / 2)
delay(delayTime.inWholeMilliseconds + jitter)

launch — 예외가 즉시 위로 간다

// 예외는 launch 블록 '안'에서 잡아야 한다
scope.launch {
    try {
        risky()
    } catch (e: CancellationException) {
        throw e
    } catch (e: Exception) {
        log.error("실패", e)
    }
}

// ❌ 이렇게는 못 잡는다 — launch 는 즉시 반환하기 때문
try {
    scope.launch { risky() }
} catch (e: Exception) { }      // 절대 안 걸린다

// 스코프 전체의 최후 방어선
val handler = CoroutineExceptionHandler { ctx, e ->
    log.error("처리되지 않은 예외 [${ctx[CoroutineName]}]", e)
}
val scope = CoroutineScope(SupervisorJob() + handler)

async — await 할 때 던져진다

val deferred = scope.async { risky() }   // 여기서는 안 터진다

try {
    deferred.await()                      // 여기서 던져진다
} catch (e: Exception) {
    log.error("실패", e)
}

// ⚠️ 함정 — async 의 예외는 '부모에게도' 전파된다
// await 를 감싸도 부모 스코프가 취소될 수 있다
coroutineScope {
    val a = async { error("실패") }
    try { a.await() } catch (e: Exception) { }   // 잡았지만
    delay(100)                                    // 여기서 이미 취소되어 있다
}

// 부분 실패를 허용하려면 supervisorScope 안에서 async 를 쓴다
supervisorScope {
    val a = async { error("실패") }
    val b = async { ok() }
    val ra = runCatching { a.await() }.getOrNull()   // null
    val rb = b.await()                               // 정상
}

부분 실패를 담아 돌려주기

suspend fun fetchAllSafe(ids: List<Long>): Map<Long, Result<User>> =
    supervisorScope {
        ids.associateWith { id ->
            async {
                runCatching { userApi.get(id) }
            }
        }.mapValues { (_, d) -> d.await() }
    }

val results = fetchAllSafe(ids)
val ok = results.values.mapNotNull { it.getOrNull() }
val failed = results.filterValues { it.isFailure }.keys
log.warn("실패한 id: {}", failed)

병렬로 만들면 안 되는 것

• DB 커넥션을 쓰는 작업 — 커넥션 풀 크기를 넘는 동시 실행은 풀 고갈로 이어집니다. limitedParallelism이나 세마포어로 제한하세요
• 순서가 있는 작업 — 재고 차감 후 결제처럼 앞이 성공해야 뒤가 의미 있는 흐름
• 같은 트랜잭션 안 — 스프링 트랜잭션은 스레드에 묶여 있어 다른 코루틴으로 넘어가면 같은 트랜잭션이 아닙니다 (자세한 내용은 Spring Boot 탭)
• 상대 API 의 rate limit 을 넘는 호출 — 병렬로 보내면 429 폭탄

직접 만드는 컨텍스트 요소

// 요청 단위 정보를 코루틴 전체에 흘려보낸다
data class RequestContext(val traceId: String, val userId: Long?) :
    AbstractCoroutineContextElement(Key) {
    companion object Key : CoroutineContext.Key<RequestContext>
}

// 심는 쪽
suspend fun handle(req: Request) = withContext(RequestContext(req.traceId, req.userId)) {
    service.process()
}

// 읽는 쪽 — 어디서든
suspend fun currentTraceId(): String? =
    coroutineContext[RequestContext]?.traceId

suspend fun audit(action: String) {
    log.info("[{}] {} by {}", currentTraceId(), action, coroutineContext[RequestContext]?.userId)
}

ThreadLocal 을 코루틴으로 잇기

// MDC(로그 컨텍스트)를 코루틴에 따라다니게 만든다
// implementation("org.jetbrains.kotlinx:kotlinx-coroutines-slf4j")

withContext(MDCContext()) {          // 현재 MDC 를 코루틴 컨텍스트로 복사
    log.info("여기서도 traceId 가 찍힌다")
    launch { log.info("자식에서도 유지") }
}

// 일반 ThreadLocal 도 이을 수 있다
val userThreadLocal = ThreadLocal<String>()
launch(userThreadLocal.asContextElement("김현우")) {
    println(userThreadLocal.get())   // 김현우
    delay(100)                        // 스레드가 바뀌어도
    println(userThreadLocal.get())   // 김현우 — 재개할 때 다시 심어 준다
}

만들기

// flow 빌더 — 가장 기본
val f1: Flow<Int> = flow {
    for (i in 1..3) {
        delay(100)         // suspend 가 된다 (Sequence 와의 결정적 차이)
        emit(i)            // 값을 흘려보낸다
    }
}

// 이미 있는 값에서
val f2 = flowOf(1, 2, 3)
val f3 = listOf(1, 2, 3).asFlow()

// 콜백 API 를 Flow 로 감싸기 (안드로이드·소켓에서 매우 자주 쓴다)
fun locationFlow(): Flow<Location> = callbackFlow {
    val listener = LocationListener { loc -> trySend(loc) }
    manager.register(listener)
    awaitClose { manager.unregister(listener) }   // 수집이 끝나면 정리
}

수집하기 — collect 하기 전엔 아무 일도 없다

val nums = flow {
    println("시작")            // collect 할 때 실행된다
    emit(1); emit(2)
}

println("아직 아무 일 없음")

runBlocking {
    nums.collect { println("받음: $it") }   // 여기서 비로소 실행
}

// 수집 방법들
nums.toList()                        // 전부 모아서 리스트로
nums.first()                          // 첫 값만 (그 뒤 취소)
nums.single()                         // 딱 하나여야 한다
nums.collect { }                      // 하나씩 처리
nums.onEach { log(it) }.collect()     // 중간 처리 후 수집

// 코루틴 스코프에서 백그라운드 수집
scope.launch { nums.collect { update(it) } }
// 또는 축약형
nums.onEach { update(it) }.launchIn(scope)

flatMap 삼형제 — 이름이 곧 동작

// 검색어가 바뀌면 이전 요청을 버린다
searchQueryFlow
    .debounce(300)                       // 입력이 멎고 300ms 뒤
    .filter { it.length >= 2 }
    .distinctUntilChanged()
    .flatMapLatest { q -> api.search(q) } // 이전 검색은 취소
    .catch { emit(emptyList()) }
    .collect { showResults(it) }

// 이 다섯 줄이 '입력 debounce + 중복 제거 + 이전 요청 취소'를 전부 처리한다.
// 콜백으로 짜면 상태 변수가 세 개는 필요하다.

여러 Flow 합치기

// combine — 어느 쪽이든 바뀌면 최신값끼리 합친다 (UI 상태 조합의 기본)
combine(userFlow, settingsFlow) { user, settings ->
    ScreenState(user, settings)
}.collect { render(it) }

// zip — 양쪽에서 하나씩 짝을 맞춘다 (개수가 맞아야 한다)
flowA.zip(flowB) { a, b -> a to b }

// merge — 두 흐름을 그냥 하나로 섞는다
merge(clickFlow, keyFlow).collect { handle(it) }

// 실전: 목록 + 검색어 + 필터를 합쳐 화면 상태 만들기
combine(items, query, filter) { list, q, f ->
    list.filter { q in it.name && f.matches(it) }
}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())

flowOn — 위쪽만 스레드를 바꾼다

flow { emit(repo.heavyQuery()) }    // ← IO 에서 실행
    .map { transform(it) }          // ← IO 에서 실행
    .flowOn(Dispatchers.IO)         // 여기부터 '위쪽'에 적용
    .collect { updateUi(it) }       // ← 수집자의 컨텍스트 (Main)

// ⚠️ flow { } 안에서 withContext 로 바꿔 emit 하지 마세요 — 컨텍스트 보존 규칙 위반
// flow { withContext(IO) { emit(x) } }  → IllegalStateException
// 반드시 flowOn 을 쓴다

예외 처리 — catch 는 위쪽만 잡는다

flow { emit(risky()) }
    .catch { e -> emit(fallback) }     // 위쪽(flow·map) 예외만 잡는다
    .collect { render(it) }             // ← 여기 예외는 못 잡는다

// collect 의 예외까지 잡으려면 try-catch 로 감싼다
try {
    f.collect { render(it) }
} catch (e: Exception) { }

// 재시도도 연산자로
flow { emit(api.get()) }
    .retry(3) { e -> e is IOException }        // 조건부 재시도
    .retryWhen { cause, attempt ->
        delay(1000L * (attempt + 1)); attempt < 3
    }

StateFlow — 화면 상태

class UserViewModel(private val repo: UserRepo) : ViewModel() {

    // 쓰기는 안에서만, 읽기는 밖에서
    private val _state = MutableStateFlow<UiState>(UiState.Loading)
    val state: StateFlow<UiState> = _state.asStateFlow()

    fun load(id: Long) {
        viewModelScope.launch {
            _state.value = UiState.Loading
            _state.value = runCatching { repo.find(id) }
                .fold(
                    onSuccess = { UiState.Success(it) },
                    onFailure = { UiState.Error(it.message ?: "오류") },
                )
        }
    }

    // 상태 갱신은 update 로 (원자적)
    fun toggleFavorite() = _state.update { s ->
        if (s is UiState.Success) s.copy(user = s.user.copy(fav = !s.user.fav)) else s
    }
}

// 성질
// · 항상 값이 있다 (초기값 필수)
// · 같은 값을 넣으면 방출하지 않는다 (distinctUntilChanged 내장)
// · 늦게 구독해도 '현재 값'을 즉시 받는다

SharedFlow — 일회성 이벤트

class OrderViewModel : ViewModel() {
    // replay = 0 : 늦게 온 구독자는 지난 이벤트를 못 본다 (이벤트에 맞는 성질)
    private val _events = MutableSharedFlow<Event>(
        replay = 0,
        extraBufferCapacity = 8,
        onBufferOverflow = BufferOverflow.DROP_OLDEST,
    )
    val events: SharedFlow<Event> = _events.asSharedFlow()

    fun submit() = viewModelScope.launch {
        runCatching { repo.submit() }
            .onSuccess { _events.emit(Event.NavigateToDone(it.id)) }
            .onFailure { _events.emit(Event.ShowToast("실패: ${it.message}")) }
    }
}

// ⚠️ StateFlow 로 이벤트를 다루면 화면 회전 때 토스트가 다시 뜬다
//    (마지막 값을 다시 받기 때문) — 이벤트는 SharedFlow 나 Channel 로

버퍼 종류

produce · actor · select

// produce — 채널을 만들면서 생산 코루틴을 함께 시작 (자동 close)
fun CoroutineScope.pages(): ReceiveChannel<Page> = produce {
    var cursor: String? = null
    do {
        val page = api.list(cursor)
        send(page)
        cursor = page.next
    } while (cursor != null)
}

// 상태를 한 코루틴에 가두는 액터 패턴 — 락 없이 동시성 해결
sealed interface Msg
data class Add(val n: Int) : Msg
data class Get(val reply: CompletableDeferred<Int>) : Msg

fun CoroutineScope.counter() = actor<Msg> {      // 실험적 API
    var sum = 0
    for (msg in channel) when (msg) {
        is Add -> sum += msg.n
        is Get -> msg.reply.complete(sum)
    }
}

// select — 여러 채널 중 먼저 준비된 것 처리
select<Unit> {
    ch1.onReceive { handle(it) }
    ch2.onReceive { handle(it) }
    onTimeout(1000) { println("둘 다 조용함") }
}

Mutex — synchronized 를 쓰면 안 되는 이유

// ❌ synchronized 블록 안에서는 suspend 함수를 부를 수 없다
// synchronized(lock) { delay(100) }   // 컴파일 에러

// 그리고 synchronized 는 '스레드'를 막는다 —
// 코루틴이 스레드를 반납하지 못해 코루틴의 이점이 사라진다

// ✅ Mutex 는 코루틴을 '중단'시킬 뿐 스레드는 놓아 준다
val mutex = Mutex()
suspend fun transfer(from: Account, to: Account, amount: Long) {
    mutex.withLock {
        from.balance -= amount
        to.balance += amount
        repo.saveAll(from, to)      // suspend 호출도 가능
    }
}

// ⚠️ Mutex 는 재진입(reentrant)이 아니다 — 중첩해서 잠그면 데드락

Semaphore — 동시 실행 수 제한

// 외부 API 를 동시에 10개까지만
val sem = Semaphore(10)

suspend fun callApi(id: Long): Response =
    sem.withPermit { httpClient.get("/items/$id") }

// DB 커넥션 풀 크기에 맞추기
val dbSem = Semaphore(20)      // 풀 크기와 동일하게
suspend fun query(sql: String) = dbSem.withPermit {
    withContext(Dispatchers.IO) { jdbc.query(sql) }
}

① 블로킹 함수 감싸기

// JDBC · 파일 · 동기 HTTP — 전부 IO 디스패처로
suspend fun findUser(id: Long): User? = withContext(Dispatchers.IO) {
    jdbcTemplate.queryForObject(SQL, User::class.java, id)
}

// 커넥션 풀 크기를 넘지 않게 제한하면 더 좋다
private val dbDispatcher = Dispatchers.IO.limitedParallelism(20)
suspend fun findAll(): List<User> = withContext(dbDispatcher) {
    jdbcTemplate.query(SQL, rowMapper)
}

// 취소를 지원하려면 인터럽트를 연결해 준다
suspend fun longQuery(): List<Row> = withContext(Dispatchers.IO) {
    runInterruptible { jdbc.query(HEAVY_SQL) }   // 취소 시 스레드 인터럽트
}

② 콜백 API → suspend

// 레거시 SDK 가 콜백을 준다면
suspend fun getLocation(): Location = suspendCancellableCoroutine { cont ->
    val callback = object : LocationCallback {
        override fun onSuccess(loc: Location) = cont.resume(loc)
        override fun onError(e: Throwable) = cont.resumeWithException(e)
    }
    manager.requestLocation(callback)

    // 코루틴이 취소되면 요청도 취소한다 — 이 줄이 핵심이다
    cont.invokeOnCancellation { manager.cancelRequest(callback) }
}

// OkHttp 예시
suspend fun Call.await(): Response = suspendCancellableCoroutine { cont ->
    enqueue(object : Callback {
        override fun onResponse(call: Call, res: Response) = cont.resume(res)
        override fun onFailure(call: Call, e: IOException) = cont.resumeWithException(e)
    })
    cont.invokeOnCancellation { cancel() }
}

③ Future · Reactor 와 상호 변환

// CompletableFuture → suspend
// (코루틴 1.7+ 은 core 에 포함 — 예전 kotlinx-coroutines-jdk8 의존성은 필요 없다)
val result = someFuture.await()

// suspend → CompletableFuture (자바 호출자에게 줄 때)
fun getUserAsync(id: Long): CompletableFuture<User> =
    scope.future { getUser(id) }

// Reactor(Mono/Flux) ↔ 코루틴
// implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor")
val user: User = userMono.awaitSingle()
val userOrNull: User? = userMono.awaitSingleOrNull()
val users: Flow<User> = userFlux.asFlow()
val mono: Mono<User> = mono { getUser(id) }
val flux: Flux<User> = flow.asFlux()

// RxJava 도 같은 방식 (-rx3 모듈)

경계는 얇게 — 실무 구조

블로킹은 가장 아래층에 가둡니다. 위로 올라올수록 suspend 만 보이게 하면, 나중에 논블로킹 드라이버(R2DBC)로 바꿔도 위층 코드는 그대로입니다.

디스패처 주입 — 테스트 가능한 설계

// ❌ 하드코딩하면 테스트에서 제어할 수 없다
class Repo {
    suspend fun load() = withContext(Dispatchers.IO) { /* ... */ }
}

// ✅ 주입한다
class Repo(private val io: CoroutineDispatcher = Dispatchers.IO) {
    suspend fun load() = withContext(io) { /* ... */ }
}

@Test
fun test() = runTest {
    val repo = Repo(StandardTestDispatcher(testScheduler))   // 가상 시간 공유
    // ...
}

// 안드로이드 ViewModel — Main 디스패처 교체
@Before fun setUp() = Dispatchers.setMain(StandardTestDispatcher())
@After fun tearDown() = Dispatchers.resetMain()

Flow 테스트 — Turbine

@Test
fun `상태가 로딩에서 성공으로 바뀐다`() = runTest {
    val vm = UserViewModel(fakeRepo)

    vm.state.test {                       // Turbine
        assertEquals(UiState.Loading, awaitItem())
        vm.load(1)
        val success = awaitItem()
        assertTrue(success is UiState.Success)
        cancelAndIgnoreRemainingEvents()
    }
}

// Turbine 없이도 가능하지만 장황하다
@Test
fun withoutTurbine() = runTest {
    val vm = UserViewModel(fakeRepo)
    val values = mutableListOf<UiState>()
    val job = launch(UnconfinedTestDispatcher()) { vm.state.toList(values) }
    vm.load(1)
    advanceUntilIdle()
    assertEquals(2, values.size)
    job.cancel()
}

직접 확인해 보기

IntelliJ → Tools → Kotlin → Show Kotlin Bytecode → [Decompile]

suspend 함수를 하나 만들고 디컴파일하면
  · ContinuationImpl 을 상속한 익명 클래스
  · switch (this.label) 로 시작하는 거대한 메서드
  · 지역 변수가 필드(L$0, L$1)로 저장되는 코드
가 그대로 보입니다.

"코루틴이 왜 스레드보다 가벼운가"의 답이 여기 있습니다 —
스택 1MB 대신 필드 몇 개짜리 객체 하나면 되기 때문입니다.

이 변환이 설명해 주는 것들

• 재개 후 스레드가 바뀔 수 있다 — 스택이 아니라 힙에 상태가 있으니 어느 스레드든 이어받을 수 있습니다
• ThreadLocal 이 사라진다 — 위와 같은 이유
• 스택 트레이스가 짧다 — 호출 스택이 아니라 상태 기계 점프이기 때문. -Dkotlinx.coroutines.debug를 켜면 코루틴 경로가 복원됩니다
• suspend 함수는 자바에서 부르기 어렵다 — Continuation 을 직접 만들어야 합니다. 자바용 API 는 CompletableFuture로 감싸 제공하세요
• inline 함수 안의 suspend 는 비용이 없다 — 상태 기계가 호출 자리에 합쳐집니다

함수를 만들 때

• 공개 API 는 suspend fun f(): T 또는 fun f(): Flow<T>
• 메인 세이프하게 — 디스패처 전환은 함수 안에서
• 디스패처는 인자로 주입(기본값 제공) — 테스트를 위해
• 긴 계산 루프에는 ensureActive()
• 자원은 use·finally+NonCancellable로 반드시 정리

운영에서 볼 것

• -Dkotlinx.coroutines.debug + CoroutineName으로 로그 추적
• MDC 전파(MDCContext)로 traceId 유지 (11)
• 디스패처별 스레드 수와 큐 길이를 지표로 노출
• 블로킹 호출이 섞여 있는지 주기적으로 점검 (개발 환경에서 BlockHound로 탐지 가능)
• 취소가 실제로 하위 시스템까지 전달되는지 확인 (DB 쿼리 취소 등)

plugin.spring — 왜 필요한가

코틀린 클래스는 기본이 final인데, 스프링은 @Transactional·@Cacheable 등을 CGLIB 프록시(상속)로 구현합니다. final 클래스는 상속할 수 없으니 프록시를 만들 수 없습니다.

// 이 플러그인이 자동으로 open 을 붙여 준다
// @Component @Service @Repository
// @Controller @Configuration
// @SpringBootTest @Async @Transactional

// 없으면 이런 에러
// Cannot subclass final class

plugin.jpa — 기본 생성자

JPA 명세는 엔티티에 파라미터 없는 생성자를 요구합니다. 코틀린 class User(val name: String)에는 그런 생성자가 없습니다.

// 대상: @Entity @Embeddable
//       @MappedSuperclass
// 바이트코드에만 생성자를 추가한다
// (코드에서는 여전히 못 부른다)

// 없으면
// No default constructor for entity

-Xjsr305=strict

스프링의 자바 API에는 @Nullable·@NonNull이 붙어 있습니다. 이 옵션을 켜면 코틀린이 그 표시를 플랫폼 타입이 아니라 진짜 타입으로 취급합니다.

같은 타입 빈이 여럿일 때

@Service
class NotificationService(
    @Qualifier("slack") private val slack: Notifier,
    @Qualifier("email") private val email: Notifier,
    private val all: List<Notifier>,         // 전부 주입받기
    private val byName: Map<String, Notifier>,// 빈 이름 → 빈
) {
    fun broadcast(msg: String) = all.forEach { it.send(msg) }
}

// 선택적 의존성 — nullable 로 받는다
@Service
class MetricsService(
    private val optional: MeterRegistry? = null,   // 없으면 null
)

@Configuration 과 빈 정의

@Configuration
class AppConfig {

    @Bean
    fun restClient(builder: RestClient.Builder): RestClient =
        builder.baseUrl("https://api.example.com")
            .requestFactory(SimpleClientHttpRequestFactory().apply {
                setConnectTimeout(2_000)
                setReadTimeout(3_000)
            })
            .build()

    @Bean
    @ConditionalOnProperty("feature.newPricing", havingValue = "true")
    fun newPricingPolicy(): PricingPolicy = NewPricingPolicy()

    @Bean
    fun clock(): Clock = Clock.systemDefaultZone()   // 테스트에서 시간 고정용
}

불변 설정 클래스

@ConfigurationProperties(prefix = "app.order")
data class OrderProperties(
    val maxItems: Int = 100,
    val timeout: Duration = 3.seconds.toJavaDuration(),
    val currency: String = "KRW",
    val notify: Notify = Notify(),
) {
    data class Notify(
        val enabled: Boolean = true,
        val channels: List<String> = listOf("email"),
    )
}

// 등록 — 둘 중 하나
@ConfigurationPropertiesScan          // Application 클래스에
@EnableConfigurationProperties(OrderProperties::class)

app:
  order:
    max-items: 200        # 케밥 케이스 → maxItems 로 매핑
    timeout: 5s
    notify:
      channels: [email, slack]

검증과 프로파일

@Validated
@ConfigurationProperties("app.payment")
data class PaymentProperties(
    @field:NotBlank val apiKey: String,        // ★ @field: 가 필요하다
    @field:Min(1) val retryCount: Int = 3,
    @field:Pattern(regexp = "https://.*") val baseUrl: String,
)
// 값이 없거나 형식이 틀리면 '앱이 뜨지 않는다' — 운영 중 발견보다 훨씬 낫다

// 프로파일별 설정
// application.yml · application-local.yml · application-prod.yml
@Profile("!prod")
@Configuration
class DevOnlyConfig { /* ... */ }

// 코드에서 프로파일 확인
@Component
class Startup(private val env: Environment) {
    @PostConstruct fun log() = println(env.activeProfiles.joinToString())
}

suspend 컨트롤러 — 코루틴을 그대로

@RestController
class ProfileController(private val service: ProfileService) {

    // 함수에 suspend 만 붙이면 된다 (spring-web 이 지원)
    @GetMapping("/api/profile/{id}")
    suspend fun profile(@PathVariable id: Long): ProfileResponse =
        service.load(id)         // 안에서 async 로 병렬 호출

    // 스트리밍 응답 — Flow 를 그대로 반환
    @GetMapping("/api/events", produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
    fun events(): Flow<ServerSentEvent<String>> = service.eventFlow()
}

응답을 다루는 방법들

// 1) 그냥 객체 반환 — 200 OK (가장 깔끔)
@GetMapping("/{id}") fun get(@PathVariable id: Long) = service.get(id)

// 2) 상태 코드가 갈리면 ResponseEntity
@GetMapping("/{id}")
fun get2(@PathVariable id: Long): ResponseEntity<OrderResponse> =
    service.find(id)?.let { ResponseEntity.ok(it) }
        ?: ResponseEntity.notFound().build()

// 3) 생성 — Location 헤더까지
@PostMapping
fun create(@RequestBody req: CreateOrderRequest): ResponseEntity<OrderResponse> {
    val created = service.create(req)
    return ResponseEntity
        .created(URI.create("/api/v1/orders/${created.id}"))
        .body(created)
}

// 4) 파일 다운로드
@GetMapping("/{id}/receipt")
fun receipt(@PathVariable id: Long): ResponseEntity<ByteArray> =
    ResponseEntity.ok()
        .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"r-$id.pdf\"")
        .contentType(MediaType.APPLICATION_PDF)
        .body(service.receiptPdf(id))

실무 DTO 설계

// 요청 — 필수는 non-null, 선택은 nullable + 기본값
data class CreateOrderRequest(
    @field:NotNull val productId: Long,
    @field:Min(1) @field:Max(99) val quantity: Int = 1,
    val couponCode: String? = null,
    val memo: String? = null,
)

// 응답 — 도메인과 분리한다 (엔티티를 그대로 노출하지 않는다)
data class OrderResponse(
    val id: Long,
    val status: OrderStatus,
    val totalAmount: Long,
    val items: List<OrderItemResponse>,
    @JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss")
    val createdAt: LocalDateTime,
) {
    companion object {
        fun from(o: Order) = OrderResponse(
            id = o.id, status = o.status, totalAmount = o.total(),
            items = o.items.map(OrderItemResponse::from),
            createdAt = o.createdAt,
        )
    }
}

// 또는 확장 함수로 (프레젠테이션 계층 안에 둔다)
fun Order.toResponse() = OrderResponse(...)

이름·형식 관련 함정

기본 사용

data class SignUpRequest(
    @field:NotBlank(message = "이름은 필수입니다")
    @field:Size(max = 20)
    val name: String,

    @field:Email(message = "이메일 형식이 아닙니다")
    val email: String,

    @field:Pattern(regexp = "^01\\d-\\d{3,4}-\\d{4}$")
    val phone: String,

    @field:Min(0) @field:Max(150)
    val age: Int,

    @field:Valid                       // 중첩 객체까지 검증
    val address: AddressRequest,

    @field:Size(min = 1, message = "최소 1개")
    val items: List<@Valid ItemRequest>,
)

@PostMapping("/signup")
fun signUp(@Valid @RequestBody req: SignUpRequest) = service.signUp(req)
// 실패하면 MethodArgumentNotValidException → 전역 핸들러에서 400 으로

커스텀 검증기

@Target(AnnotationTarget.FIELD)
@Retention(AnnotationRetention.RUNTIME)
@Constraint(validatedBy = [CouponValidator::class])
annotation class ValidCoupon(
    val message: String = "사용할 수 없는 쿠폰입니다",
    val groups: Array<KClass<*>> = [],
    val payload: Array<KClass<out Payload>> = [],
)

@Component
class CouponValidator(
    private val repo: CouponRepository,      // 빈 주입도 된다
) : ConstraintValidator<ValidCoupon, String?> {
    override fun isValid(value: String?, ctx: ConstraintValidatorContext): Boolean =
        value == null || repo.existsByCodeAndActiveTrue(value)
}

data class OrderRequest(
    @field:ValidCoupon val couponCode: String? = null,
)

ProblemDetail — 표준 에러 포맷

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "재고 부족 (남은 수량 2)",
  "instance": "/api/v1/orders",
  "code": "OUT_OF_STOCK",
  "traceId": "a1b2c3"
}

RFC 9457 표준입니다. 팀마다 다른 에러 포맷을 만드는 대신 표준을 쓰고 필드만 몇 개 더하는 편이 클라이언트 입장에서 좋습니다.

놓치기 쉬운 것들

• 코루틴 컨트롤러의 예외도 @RestControllerAdvice가 잡습니다. 단 CancellationException(클라이언트 연결 끊김)은 에러 로그로 남기지 마세요
• 404 를 예외로 만들지 “못 찾음”으로 만들지 정하세요 — 컨트롤러가 ResponseEntity.notFound()를 쓰는 방식도 좋습니다
• 메시지에 내부 정보를 담지 않기 — SQL·스택·경로가 새면 보안 문제
• @ExceptionHandler는 더 구체적인 타입이 우선합니다
• 필터 단계에서 난 예외는 Advice 가 못 잡습니다 — 시큐리티 예외는 AuthenticationEntryPoint로 따로 처리

세 가지 함정

@Service
class OrderService(private val repo: OrderRepository) {

    // ① final — plugin.spring 이 없으면 프록시 자체를 못 만든다
    //    (플러그인이 @Service 클래스를 열어 주므로 보통은 문제없다)
    //    단 '함수'는 열리지 않는 경우가 있어 open 이 필요할 수 있다

    @Transactional
    fun place(cmd: PlaceOrderCommand): Order {
        val order = repo.save(Order(cmd))
        // ② 내부 호출 — 이 호출에는 REQUIRES_NEW 가 걸리지 않는다
        writeAuditLog(order)
        return order
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    fun writeAuditLog(order: Order) { /* ... */ }
}

코루틴에서 트랜잭션 쓰기

// 방법 1 — 트랜잭션 구간을 블로킹으로 가둔다 (JPA·JDBC 를 쓸 때 현실적)
@Service
class OrderService(
    private val tx: TransactionTemplate,
    private val repo: OrderRepository,
) {
    suspend fun place(cmd: PlaceOrderCommand): Order =
        withContext(Dispatchers.IO) {
            tx.execute { repo.save(Order(cmd)) }!!   // 한 스레드 안에서 시작·종료
        }
}

// 방법 2 — R2DBC(리액티브 DB)면 코루틴 트랜잭션이 그대로 된다
@Service
class ReactiveOrderService(private val operator: TransactionalOperator) {
    suspend fun place(cmd: PlaceOrderCommand): Order =
        operator.executeAndAwait { repo.save(Order(cmd)).awaitSingle() }
}

// 방법 3 — 블로킹 서비스(@Transactional)를 얇게 감싼다 (가장 흔한 구조)
@Service
class OrderFacade(private val blockingService: OrderService) {
    suspend fun place(cmd: PlaceOrderCommand) =
        withContext(Dispatchers.IO) { blockingService.place(cmd) }
}

가상 스레드 켜기 — 한 줄

spring:
  threads:
    virtual:
      enabled: true      # Boot 3.2+ · JDK 21+

톰캣이 요청마다 가상 스레드를 만듭니다. 기존 블로킹 코드 그대로 동시성이 크게 오릅니다. 다만 DB 커넥션 풀은 여전히 유한하므로 병목이 그쪽으로 옮겨갈 뿐인 경우도 많습니다 — 측정하고 결정하세요.

suspend 컨트롤러가 실제로 하는 일

@GetMapping("/api/dashboard")
suspend fun dashboard(@AuthenticationPrincipal me: LoginUser): DashboardResponse =
    coroutineScope {
        val orders = async { orderClient.recent(me.id) }    // 외부 API
        val points = async { pointClient.get(me.id) }       // 외부 API
        val coupons = async { couponClient.list(me.id) }    // 외부 API
        DashboardResponse(orders.await(), points.await(), coupons.await())
    }

// 세 API 가 각 150ms 라면
// 기존 방식: 450ms + 요청 스레드 450ms 점유
// 코루틴:    ~150ms + 요청 스레드는 기다리는 동안 반납

JWT 필터 — 코틀린으로

@Component
class JwtAuthenticationFilter(
    private val jwt: JwtProvider,
) : OncePerRequestFilter() {

    override fun doFilterInternal(
        request: HttpServletRequest,
        response: HttpServletResponse,
        chain: FilterChain,
    ) {
        request.getHeader(HttpHeaders.AUTHORIZATION)
            ?.takeIf { it.startsWith("Bearer ") }
            ?.removePrefix("Bearer ")
            ?.let { token -> runCatching { jwt.parse(token) }.getOrNull() }
            ?.let { claims ->
                val auth = UsernamePasswordAuthenticationToken(
                    LoginUser(claims.userId, claims.roles),
                    null,
                    claims.roles.map { SimpleGrantedAuthority("ROLE_$it") },
                )
                SecurityContextHolder.getContext().authentication = auth
            }
        chain.doFilter(request, response)
    }
}

메서드 보안 · 현재 사용자

@Service
class OrderService(private val repo: OrderRepository) {

    @PreAuthorize("hasRole('ADMIN')")
    fun deleteAll() = repo.deleteAll()

    // SpEL 로 소유권 검사
    @PreAuthorize("#userId == authentication.principal.id")
    fun listOf(userId: Long) = repo.findByUserId(userId)

    @PostAuthorize("returnObject.userId == authentication.principal.id")
    fun get(id: Long): Order = repo.findByIdOrNull(id) ?: error("없음")
}

// 컨트롤러에서 현재 사용자 받기
@GetMapping("/me")
fun me(@AuthenticationPrincipal user: LoginUser) = user

// 커스텀 애너테이션으로 짧게
@Target(AnnotationTarget.VALUE_PARAMETER)
@Retention(AnnotationRetention.RUNTIME)
@AuthenticationPrincipal
annotation class CurrentUser

@GetMapping("/orders")
fun orders(@CurrentUser user: LoginUser) = service.listOf(user.id)

단위 테스트 — 스프링 없이

class OrderServiceTest {
    private val repo = mockk<OrderRepository>()
    private val stock = mockk<StockClient>(relaxed = true)   // 반환값 신경 안 씀
    private val service = OrderService(repo, stock)

    @Test
    fun `재고가 부족하면 주문에 실패한다`() {
        every { stock.available(1L) } returns 0

        val ex = assertThrows<DomainException.OutOfStock> {
            service.place(PlaceOrderCommand(productId = 1, quantity = 1))
        }
        assertEquals(0, ex.left)
        verify(exactly = 0) { repo.save(any()) }      // 저장하지 않았다
    }

    @Test
    fun `suspend 함수도 그대로`() = runTest {
        coEvery { stock.reserveAsync(any()) } returns true    // coEvery
        service.placeAsync(cmd)
        coVerify { stock.reserveAsync(1L) }                   // coVerify
    }
}

MockK 문법 요약

// 인자 캡처
val slot = slot<Order>()
every { repo.save(capture(slot)) } answers { slot.captured }
service.place(cmd)
assertEquals(2, slot.captured.items.size)

테스트 픽스처 — 코틀린 기본값 활용

// 기본값을 준 팩토리 함수 하나면 빌더가 필요 없다
fun order(
    id: Long = 1,
    userId: Long = 100,
    status: OrderStatus = OrderStatus.NEW,
    items: List<OrderItem> = listOf(orderItem()),
) = Order(id, userId, status, items)

fun orderItem(productId: Long = 1, quantity: Int = 1, price: Long = 12_000) =
    OrderItem(productId, quantity, price)

// 테스트에서 바꾸고 싶은 것만 적는다
val canceled = order(status = OrderStatus.CANCELED)
val bulk = order(items = List(10) { orderItem(productId = it.toLong()) })

Kotest — 다른 스타일의 선택지

class OrderSpec : BehaviorSpec({
    given("재고가 0인 상품") {
        val stock = mockk<StockClient> { every { available(1) } returns 0 }
        `when`("주문하면") {
            then("OutOfStock 예외가 난다") {
                shouldThrow<DomainException.OutOfStock> {
                    OrderService(repo, stock).place(cmd)
                }
            }
        }
    }
})

// 프로퍼티 기반 테스트도 강력하다
class MoneySpec : StringSpec({
    "덧셈은 교환법칙을 만족한다" {
        checkAll<Long, Long> { a, b ->
            Money(a) + Money(b) shouldBe Money(b) + Money(a)
        }
    }
})

AOP — 실행 시간 측정 애너테이션

@Target(AnnotationTarget.FUNCTION, AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Timed(val name: String = "")

@Aspect
@Component
class TimedAspect(private val registry: MeterRegistry) {

    @Around("@annotation(timed)")
    fun measure(pjp: ProceedingJoinPoint, timed: Timed): Any? {
        val name = timed.name.ifBlank { pjp.signature.toShortString() }
        val sample = Timer.start(registry)
        return try {
            pjp.proceed()
        } finally {
            sample.stop(registry.timer("method.timed", "name", name))
        }
    }
}

@Service
class OrderService {
    @Timed("order.place")
    fun place(cmd: PlaceOrderCommand): Order { /* ... */ }
}

필터 · 인터셉터

// 필터 — 요청/응답 전체를 감싼다
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
class RequestLoggingFilter : OncePerRequestFilter() {
    override fun doFilterInternal(req: HttpServletRequest, res: HttpServletResponse, chain: FilterChain) {
        val start = System.currentTimeMillis()
        val traceId = req.getHeader("X-Trace-Id") ?: UUID.randomUUID().toString().take(8)
        MDC.put("traceId", traceId)
        res.setHeader("X-Trace-Id", traceId)
        try {
            chain.doFilter(req, res)
        } finally {
            log.info("{} {} {} {}ms", req.method, req.requestURI, res.status,
                System.currentTimeMillis() - start)
            MDC.clear()
        }
    }
}

// 인터셉터 — 핸들러(어느 컨트롤러 메서드인지)를 알 수 있다
@Component
class AuditInterceptor : HandlerInterceptor {
    override fun preHandle(req: HttpServletRequest, res: HttpServletResponse, handler: Any): Boolean {
        if (handler is HandlerMethod) {
            handler.getMethodAnnotation(Audited::class.java)?.let { audit(it, req) }
        }
        return true
    }
}

@Configuration
class WebConfig(private val audit: AuditInterceptor) : WebMvcConfigurer {
    override fun addInterceptors(registry: InterceptorRegistry) {
        registry.addInterceptor(audit).addPathPatterns("/api/**")
    }
}

스케줄러

@Configuration
@EnableScheduling
class SchedulerConfig

@Component
class SettlementJob(private val service: SettlementService) {

    // 매일 새벽 3시
    @Scheduled(cron = "0 0 3 * * *", zone = "Asia/Seoul")
    fun daily() {
        runCatching { service.settleYesterday() }
            .onFailure { log.error("정산 실패", it) }    // 여기서 잡아 맥락 있는 로그·알림을 남긴다 (안 잡아도 다음 실행은 된다)
    }

    // 이전 실행이 끝난 뒤 5초
    @Scheduled(fixedDelay = 5_000, initialDelay = 10_000)
    fun poll() = service.pollOutbox()
}

비동기 — @Async vs 코루틴

@Configuration
@EnableAsync
class AsyncConfig {
    @Bean("mailExecutor")
    fun mailExecutor(): Executor = ThreadPoolTaskExecutor().apply {
        corePoolSize = 4; maxPoolSize = 8; queueCapacity = 500
        setThreadNamePrefix("mail-")
        setRejectedExecutionHandler(ThreadPoolExecutor.CallerRunsPolicy())
        initialize()
    }
}

@Service
class MailService {
    @Async("mailExecutor")
    fun sendAsync(to: String) { /* ... */ }     // 반환 즉시 다른 스레드로
}

// 코루틴을 쓴다면 @Async 대신 스코프를 직접 관리하는 편이 명확하다
@Service
class MailService2 : DisposableBean {
    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
    fun sendAsync(to: String) = scope.launch { send(to) }
    override fun destroy() = scope.cancel()
}

코틀린에서 주의할 점

• suspend 함수에는 @Cacheable이 동작하지 않습니다 — 반환 타입이 Object(Continuation 방식)이기 때문. 블로킹 함수로 감싸거나 캐시를 직접 다루세요
• null 캐싱 — unless = "#result == null"을 안 주면 null 도 캐시됩니다(의도적이면 괜찮습니다)
• 내부 호출은 캐시가 안 걸립니다 — 프록시 문제(09)
• 캐시 키에 data class를 쓰면 equals/hashCode 가 자동이라 안전합니다

코루틴 캐시 — 직접 다루기

@Component
class ProductCache(private val repo: ProductRepository) {
    private val cache = Caffeine.newBuilder()
        .maximumSize(10_000)
        .expireAfterWrite(10.minutes.toJavaDuration())
        .build<Long, Product>()

    private val locks = ConcurrentHashMap<Long, Mutex>()

    // 캐시 스탬피드 방지 — 같은 키는 한 번만 조회
    suspend fun get(id: Long): Product? {
        cache.getIfPresent(id)?.let { return it }
        val mutex = locks.computeIfAbsent(id) { Mutex() }
        return mutex.withLock {
            cache.getIfPresent(id) ?: repo.findAsync(id)?.also { cache.put(id, it) }
        }.also { locks.remove(id) }
    }
}

로거 선언 — 세 가지 방식

// ① companion object (가장 흔하다)
class OrderService {
    companion object {
        private val log = LoggerFactory.getLogger(OrderService::class.java)
    }
}

// ② 최상위 프로퍼티 (파일 단위)
private val log = LoggerFactory.getLogger("OrderService")

// ③ 확장 함수로 공통화 — 프로젝트에 하나 만들어 두면 편하다
inline fun <reified T> T.logger(): Logger = LoggerFactory.getLogger(T::class.java)

class OrderService {
    private val log = logger()
}

// kotlin-logging 라이브러리를 쓰면 더 짧다
// implementation("io.github.oshai:kotlin-logging-jvm:7.0.0")
private val logger = KotlinLogging.logger {}
logger.info { "메시지 — 람다라서 레벨이 꺼져 있으면 문자열을 만들지 않는다" }

구조화 로깅 · Actuator

logging:
  structured:
    format:
      console: ecs        # Boot 3.4+ — JSON 로그 (ECS · Logstash · GELF)
  level:
    root: INFO
    com.example: DEBUG

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      probes:
        enabled: true     # /actuator/health/liveness · readiness
  metrics:
    tags:
      application: order-service

// 커스텀 헬스 체크
@Component
class PaymentHealthIndicator(private val client: PaymentClient) : HealthIndicator {
    override fun health(): Health =
        runCatching { client.ping() }
            .fold(
                onSuccess = { Health.up().withDetail("latency", it).build() },
                onFailure = { Health.down(it).build() },
            )
}

메트릭 — Micrometer

@Service
class OrderService(private val registry: MeterRegistry) {

    private val placed = registry.counter("orders.placed")
    private val timer = registry.timer("orders.place.duration")

    fun place(cmd: PlaceOrderCommand): Order =
        timer.recordCallable {
            doPlace(cmd).also { placed.increment() }
        }!!

    // 게이지 — 현재 값을 관찰
    init {
        registry.gauge("orders.pending", this) { it.countPending().toDouble() }
    }
}

// 태그를 붙이면 대시보드에서 쪼개 볼 수 있다
registry.counter("orders.placed", "channel", cmd.channel, "result", "success").increment()

로그를 쓸모 있게 만드는 규칙

• 문자열 템플릿 대신 파라미터를 쓰세요 — log.info("주문 {}", id). 레벨이 꺼져 있으면 문자열을 안 만듭니다 (코틀린 "$id"는 항상 만듭니다)
• traceId 를 MDC 에 넣고 모든 로그에 자동 포함
• 개인정보·토큰·카드번호를 로그에 남기지 않기 (마스킹 유틸을 확장 함수로)
• 예외는 메시지가 아니라 예외 객체로 넘기기 — log.error("실패", e). "$e"는 스택이 안 남습니다
• 정상 흐름에 ERROR 를 쓰지 않기 — 알람이 무뎌집니다

이미지 만들기 — Dockerfile 없이

# Cloud Native Buildpacks — 부트가 최적화된 이미지를 만들어 준다
./gradlew bootBuildImage --imageName=myapp:1.0.0

# 계층이 분리되어 재빌드가 빠르다 (의존성 / 앱 코드)
# JVM 튜닝·CDS·헬스체크가 이미 들어 있다

# 직접 쓰는 경우 — 최소 형태 (JRE 이미지 + jar 하나. 레이어 분리는 하지 않은 버전)
FROM eclipse-temurin:21-jre AS runtime
WORKDIR /app
COPY build/libs/app.jar app.jar
ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=75 -XX:+UseZGC"
EXPOSE 8080
ENTRYPOINT ["java","-jar","app.jar"]

GraalVM 네이티브 이미지

plugins {
    id("org.graalvm.buildtools.native") version "0.10.3"
}

// ./gradlew nativeCompile
// ./gradlew nativeRun

// 리플렉션을 쓰는 코드는 힌트를 등록해야 한다
@Configuration
@ImportRuntimeHints(AppRuntimeHints::class)
class NativeConfig

class AppRuntimeHints : RuntimeHintsRegistrar {
    override fun registerHints(hints: RuntimeHints, cl: ClassLoader?) {
        hints.reflection().registerType(OrderResponse::class.java) {
            it.withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
                           MemberCategory.INVOKE_PUBLIC_METHODS)
        }
        hints.resources().registerPattern("templates/*.html")
    }
}

WebFlux 가 맞는 상황

• 동시 커넥션이 수천~수만 — 채팅·알림·SSE·롱폴링
• 게이트웨이·프록시 — 요청을 받아 다른 서비스로 넘기는 일이 대부분
• 스트리밍 — 대용량 응답을 조금씩 흘려보내야 할 때
• 전 구간 논블로킹이 가능 — R2DBC·논블로킹 HTTP 클라이언트만 사용

MVC 로 충분한 상황 (대부분)

• JPA·JDBC 를 쓴다 — 어차피 블로킹이라 이득이 제한적
• 초당 수백~수천 요청 — 톰캣 + 가상 스레드로 충분
• 팀에 리액티브 경험이 적다 — 디버깅 비용이 큽니다
• 트랜잭션이 복잡한 업무 시스템 — JPA 생태계의 이점이 큽니다

두 타입의 뜻

// Reactor 스타일 (자바에서 오던 코드)
fun findUser(id: Long): Mono<User> =
    repo.findById(id)
        .switchIfEmpty(Mono.error(NotFound(id)))
        .flatMap { u -> enrich(u) }
        .timeout(Duration.ofSeconds(3))
        .onErrorResume(TimeoutException::class.java) { Mono.just(User.GUEST) }   // 타임아웃만 폴백 (NotFound 는 그대로)

// 코틀린 코루틴 스타일 — 같은 일
suspend fun findUser(id: Long): User =
    withTimeoutOrNull(3.seconds) {
        val u = repo.findById(id).awaitSingleOrNull() ?: throw NotFound(id)
        enrich(u)
    } ?: User.GUEST

Cold·구독·백프레셔 — 개념은 Flow와 같다

• 구독하기 전엔 아무 일도 없다 — Flow 의 collect와 같은 규칙
• 백프레셔 — 소비자가 request(n)으로 속도를 조절. 코루틴 Flow 는 중단(suspend)으로 같은 효과를 냅니다
• 연산자 체인 — Flow 의 map·filter·buffer와 대응

애너테이션 방식도 그대로 된다

@RestController
@RequestMapping("/api/v1/orders")
class OrderController(private val service: OrderService) {

    @GetMapping("/{id}")
    suspend fun get(@PathVariable id: Long): OrderResponse = service.get(id)

    @GetMapping
    fun list(): Flow<OrderResponse> = service.listFlow()      // Flow 를 그대로 반환

    @PostMapping
    suspend fun create(@RequestBody @Valid req: CreateOrderRequest) = service.create(req)
}

둘 중 무엇을 고를까 — 팀이 MVC 에 익숙하면 애너테이션이 진입 장벽이 낮습니다. 라우팅이 많고 규칙을 한눈에 보고 싶다면 coRouter 가 낫습니다. 섞어 써도 됩니다.

ServerRequest · ServerResponse 코루틴 API

코루틴으로 부르기

@Service
class OrderClient(private val client: WebClient) {

    // 단건
    suspend fun get(id: Long): Order =
        client.get().uri("/{id}", id)
            .retrieve()
            .awaitBody<Order>()

    // 없을 수 있으면
    // (onStatus 에서 Mono.empty() 를 돌려주면 404 응답 본문을 Order 로 읽으려 들어 실패할 수 있다)
    suspend fun findOrNull(id: Long): Order? =
        try { get(id) }
        catch (e: WebClientResponseException.NotFound) { null }   // 404 만 null 로

    // 목록 스트리밍
    fun stream(userId: Long): Flow<Order> =
        client.get().uri("/stream?userId=$userId")
            .accept(MediaType.TEXT_EVENT_STREAM)
            .retrieve()
            .bodyToFlux<Order>()
            .asFlow()

    // POST
    suspend fun create(req: CreateOrder): Order =
        client.post()
            .bodyValue(req)
            .retrieve()
            .awaitBody<Order>()

    // 응답 전체가 필요할 때 (헤더·상태 코드)
    suspend fun createWithStatus(req: CreateOrder): ResponseEntity<Order> =
        client.post().bodyValue(req).retrieve().awaitEntity<Order>()
}

에러 처리 · 재시도

suspend fun get(id: Long): Order =
    try {
        client.get().uri("/{id}", id)
            .retrieve()
            .onStatus({ it.is4xxClientError }) { res ->
                res.bodyToMono<ProblemDetail>().map { ClientError(it) }
            }
            .awaitBody<Order>()
    } catch (e: WebClientResponseException) {
        log.warn("주문 조회 실패 status={} body={}", e.statusCode, e.responseBodyAsString)
        throw DomainException.Conflict("주문 서비스 오류")
    }

// 재시도는 코루틴 쪽에서 하는 편이 읽기 쉽다
suspend fun getWithRetry(id: Long): Order = retry(times = 3) { get(id) }

// Reactor 연산자로도 가능
client.get().retrieve().bodyToMono<Order>()
    .retryWhen(Retry.backoff(3, Duration.ofMillis(200)).jitter(0.5))
    .awaitSingle()

엔티티와 리포지터리

// R2DBC 는 JPA 가 아니다 — 지연 로딩·영속성 컨텍스트·연관관계가 없다
@Table("orders")
data class Order(
    @Id val id: Long? = null,              // null 이면 INSERT, 값이 있으면 UPDATE
    val userId: Long,
    val status: String,
    val totalAmount: Long,
    @Column("created_at") val createdAt: LocalDateTime = LocalDateTime.now(),
)

// data class 를 그대로 써도 된다 (JPA 와 달리 프록시가 없다)

interface OrderRepository : CoroutineCrudRepository<Order, Long> {
    // 코루틴 리포지터리 — 반환이 suspend / Flow 다
    suspend fun findByIdAndUserId(id: Long, userId: Long): Order?
    fun findByUserIdOrderByIdDesc(userId: Long): Flow<Order>

    @Query("SELECT * FROM orders WHERE status = :status AND created_at >= :from")
    fun findRecent(status: String, from: LocalDateTime): Flow<Order>

    @Modifying
    @Query("UPDATE orders SET status = :status WHERE id = :id")
    suspend fun updateStatus(id: Long, status: String): Int
}

서비스에서 쓰기 · 연관 데이터

@Service
class OrderService(
    private val orders: OrderRepository,
    private val items: OrderItemRepository,
    private val template: R2dbcEntityTemplate,
) {
    suspend fun get(id: Long): OrderDetail = coroutineScope {
        val order = async { orders.findById(id) ?: throw NotFound(id) }
        val itemList = async { items.findByOrderId(id).toList() }
        OrderDetail(order.await(), itemList.await())   // 연관은 '직접 조회해서 조립'
    }

    // 동적 쿼리는 Criteria 로
    suspend fun search(status: String?, minAmount: Long?): List<Order> {
        var criteria = Criteria.empty()
        status?.let { criteria = criteria.and("status").`is`(it) }
        minAmount?.let { criteria = criteria.and("total_amount").greaterThanOrEquals(it) }
        return template.select(Order::class.java)
            .matching(Query.query(criteria).limit(100))
            .flow()
            .toList()
    }
}

주의할 점

• 같은 커넥션을 쓰는 작업만 하나의 트랜잭션입니다. async로 병렬 실행하면 다른 커넥션이 되어 같은 트랜잭션이 아닙니다
• 중첩 트랜잭션·REQUIRES_NEW는 제약이 큽니다 — JPA 만큼 자유롭지 않습니다
• 블로킹 작업이 섞이면 커넥션을 잡은 채 이벤트 루프가 막힙니다
• 여러 서비스에 걸친 일관성이 필요하면 사가·아웃박스 패턴으로 (대규모 트래픽 탭에서 다룹니다)

트랜잭션 안에서 병렬 처리하기

// ❌ 트랜잭션이 갈라진다
tx.executeAndAwait {
    coroutineScope {
        launch { orders.save(a) }      // 다른 커넥션일 수 있다
        launch { items.save(b) }
    }
}

// ✅ 트랜잭션 안에서는 순차로, 병렬은 트랜잭션 밖에서
val (userInfo, coupon) = coroutineScope {
    async { userClient.get(id) } to async { couponClient.get(code) }
}.let { (a, b) -> a.await() to b.await() }

tx.executeAndAwait {
    orders.save(order)                  // 여기는 순차
    items.saveAll(itemList).collect()
}

서버 — Flow 를 그대로 반환

@RestController
class EventController(private val service: EventService) {

    // Server-Sent Events
    @GetMapping("/api/events", produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
    fun events(@RequestParam userId: Long): Flow<ServerSentEvent<EventDto>> =
        service.stream(userId)
            .map { e ->
                ServerSentEvent.builder(e)
                    .id(e.id.toString())
                    .event("order-update")
                    .build()
            }
            .onStart { log.info("스트림 시작 user={}", userId) }
            .onCompletion { log.info("스트림 종료 user={}", userId) }

    // NDJSON — 줄 단위 JSON (대용량 내보내기에 좋다)
    @GetMapping("/api/export", produces = [MediaType.APPLICATION_NDJSON_VALUE])
    fun export(): Flow<OrderRow> = service.exportAll()      // 100만 건도 메모리 안전

    // 하트비트 — 프록시가 유휴 커넥션을 끊지 못하게
    @GetMapping("/api/live", produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
    fun live(): Flow<ServerSentEvent<String>> = merge(
        service.stream(0).map { ServerSentEvent.builder(it.toString()).build() },
        flow { while (true) { delay(15.seconds); emit(ServerSentEvent.builder("ping").comment("hb").build()) } },
    )
}

브로드캐스트 — SharedFlow 로

@Service
class EventService : DisposableBean {
    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)

    private val _events = MutableSharedFlow<EventDto>(
        replay = 0, extraBufferCapacity = 256,
        onBufferOverflow = BufferOverflow.DROP_OLDEST,   // 느린 구독자 때문에 막히지 않게
    )

    fun publish(e: EventDto) { _events.tryEmit(e) }

    fun stream(userId: Long): Flow<EventDto> =
        _events.filter { it.userId == userId }

    override fun destroy() = scope.cancel()
}

// 여러 서버 인스턴스로 확장하려면 Redis Pub/Sub 을 앞에 둔다
// (한 인스턴스에 붙은 구독자에게만 전달되면 안 되므로)

방(Room) 구현 — SharedFlow

@Component
class ChatRoom {
    private val _messages = MutableSharedFlow<ChatMessage>(
        replay = 20,                       // 새로 들어온 사람에게 최근 20개
        extraBufferCapacity = 256,
        onBufferOverflow = BufferOverflow.DROP_OLDEST,
    )
    fun messages(): Flow<ChatMessage> = _messages.asSharedFlow()
    suspend fun publish(m: ChatMessage) = _messages.emit(m)
}

운영에서 챙길 것

• 인증 — 핸드셰이크 시점에 토큰 검증 (쿼리 파라미터·서브프로토콜 헤더)
• 하트비트 — 유휴 커넥션을 프록시가 끊습니다. 핑/퐁 주기 설정
• 재연결 — 클라이언트가 지수 백오프로 다시 붙게, 서버는 중복 세션 처리
• 메시지 크기 제한 — maxFramePayloadLength를 넘기면 연결이 끊깁니다
• 세션 수 지표 — 현재 연결 수를 메트릭으로 노출 (용량 산정의 기준)
• 느린 클라이언트 — 송신 버퍼가 차면 끊거나 버려야 합니다

설정 예시

resilience4j:
  circuitbreaker:
    instances:
      pricing:
        slidingWindowSize: 50
        failureRateThreshold: 50          # 50% 실패면 열린다
        waitDurationInOpenState: 10s
        permittedNumberOfCallsInHalfOpenState: 5
        slowCallDurationThreshold: 1s
        slowCallRateThreshold: 80
  timelimiter:
    instances:
      pricing:
        timeoutDuration: 2s

폴백을 설계하는 법

• 축소된 응답 — 추천 목록이 없으면 인기 상품으로 대체
• 캐시된 마지막 값 — 가격·환율처럼 조금 오래돼도 되는 값
• 기능 끄기 — 부가 기능이면 아예 빼고 200 을 돌려준다
• 실패를 그대로 전달 — 결제처럼 거짓 성공이 더 위험한 경우

traceId — 요청 전 구간에 유지

// WebFlux 필터에서 심는다 (서블릿 필터가 아니다)
@Component
class TraceIdFilter : WebFilter {
    override fun filter(exchange: ServerWebExchange, chain: WebFilterChain): Mono<Void> {
        val traceId = exchange.request.headers.getFirst("X-Trace-Id")
            ?: UUID.randomUUID().toString().take(8)
        exchange.response.headers.set("X-Trace-Id", traceId)
        return chain.filter(exchange)
            .contextWrite { it.put("traceId", traceId) }     // Reactor 컨텍스트
    }
}

// 코루틴에서 읽기 — Reactor 컨텍스트가 코루틴 컨텍스트로 이어진다
suspend fun currentTraceId(): String? =
    currentCoroutineContext()[ReactorContext]?.context?.getOrDefault("traceId", null)

// Micrometer Tracing 을 쓰면 대부분 자동으로 처리된다
// implementation("io.micrometer:micrometer-tracing-bridge-otel")

디버깅 도구

// BlockHound — 블로킹 호출을 실행 중에 잡는다
// testImplementation("io.projectreactor.tools:blockhound:1.0.10")
class BlockingCheckTest {
    companion object {
        // @BeforeAll 은 static 이어야 한다 — 코틀린에선 companion + @JvmStatic
        // (또는 클래스에 @TestInstance(TestInstance.Lifecycle.PER_CLASS) 를 붙이고 일반 함수로)
        @BeforeAll @JvmStatic
        fun setup() = BlockHound.install(
            BlockHoundIntegration { builder ->
                builder.allowBlockingCallsInside("java.util.UUID", "randomUUID")
            }
        )
    }
}

외부 API 목킹 — MockWebServer

// testImplementation("com.squareup.okhttp3:mockwebserver")
class PricingClientTest {
    private val server = MockWebServer()
    private lateinit var client: PricingClient

    @BeforeEach fun setUp() {
        server.start()
        client = PricingClient(WebClient.create(server.url("/").toString()), CircuitBreakerRegistry.ofDefaults())
    }
    @AfterEach fun tearDown() = server.shutdown()

    @Test
    fun `타임아웃이면 폴백을 쓴다`() = runTest {
        server.enqueue(MockResponse().setBodyDelay(5, TimeUnit.SECONDS))
        val price = client.price(1)
        assertEquals(CACHED_PRICE, price)
    }
}

R2DBC 통합 테스트

@SpringBootTest
@Testcontainers
class OrderRepositoryTest(@Autowired val repo: OrderRepository) {

    companion object {
        @Container @ServiceConnection
        val postgres = PostgreSQLContainer("postgres:16-alpine")
    }

    @Test
    fun `저장하고 조회한다`() = runTest {
        val saved = repo.save(Order(userId = 1, status = "NEW", totalAmount = 1000))
        val found = repo.findById(saved.id!!)
        assertEquals("NEW", found?.status)
    }

    @Test
    fun `Flow 로 여러 건`() = runTest {
        repo.saveAll(List(5) { Order(userId = 1, status = "NEW", totalAmount = 100) }).collect()
        val all = repo.findByUserIdOrderByIdDesc(1).toList()
        assertEquals(5, all.size)
    }
}

지표로 볼 것

• 이벤트 루프 지연 — 루프가 막히고 있는지의 직접 증거
• 커넥션 풀 사용률·대기 시간 — reactor.netty.connection.provider.*
• 다이렉트 메모리 사용량 — 힙과 별도로 봐야 한다
• p99 지연 · 활성 커넥션 수 — 용량 산정의 기준
• 취소율 — 클라이언트가 끊는 비율이 높으면 타임아웃 설계를 재검토

흔한 장애 유형

문제가 되는 순간

DB 에서 초당 5만 건이 나오는데 클라이언트가 초당 5천 건밖에 못 받는다고 합시다. 차이인 초당 4만 5천 건이 어딘가에 쌓입니다. 그 "어딘가"를 정하지 않으면 기본값은 메모리이고, 결과는 OOM 입니다.

콜백 기반 코드에는 이 개념 자체가 없습니다. 리액티브 스트림에서는 구독자가 request(n)으로 "n개만 주세요"라고 말하고, 발행자는 그만큼만 보냅니다 — 이게 배압입니다.

배압이 통하는 소스 · 안 통하는 소스

기본 — 아무것도 안 붙이면 동기

// 아무 연산자도 없으면 '한 건 만들고 한 건 처리'가 번갈아 돕니다
flow {
    repeat(1_000) { emit(load(it)) }   // 10ms 걸린다고 치면
}.collect { save(it) }                 // 여기도 10ms

// 총 1,000 × (10 + 10) = 20초
// 만드는 쪽과 처리하는 쪽이 서로를 기다립니다

기본 Flow 는 배압이 완벽하게 통하는 상태입니다. 메모리는 안전하지만 병렬성이 0이라 느립니다.

buffer — 만드는 쪽과 처리하는 쪽을 떼어놓기

flow { repeat(1_000) { emit(load(it)) } }
    .buffer(capacity = 64)             // 코루틴을 분리
    .collect { save(it) }

// 총 약 10초 — 만드는 동안 처리도 같이 돕니다
// 64칸이 차면 emit 이 자연스럽게 멈춥니다(= 배압 유지)

// 넘칠 때 버리고 싶다면
.buffer(64, onBufferOverflow = BufferOverflow.DROP_OLDEST)

capacity 를 반드시 지정하세요. UNLIMITED 는 "메모리가 무한하다"는 가정이고, 그 가정은 언젠가 깨집니다.

conflate — 최신 것만 보면 되는 경우

// 진행률 · 시세 · 마우스 위치처럼
// "중간 값을 놓쳐도 되는" 흐름에 씁니다
priceFlow
    .conflate()                    // 처리 중에 들어온 것은 최신만 남김
    .collect { renderChart(it) }

// StateFlow 는 사실상 conflate 가 내장된 Flow 입니다

collectLatest — 처리 자체를 취소하고 다시 시작

// 검색어가 바뀌면 이전 검색은 의미가 없습니다
queryFlow
    .debounce(300)                 // 타이핑이 멈추길 기다리고
    .collectLatest { q ->          // 새 값이 오면 이전 블록을 취소
        val result = search(q)     // 취소 가능한 suspend 함수여야 합니다
        show(result)
    }

conflate 는 값을 버리고, collectLatest 는 처리를 취소합니다 — 검색·자동완성에서는 후자가 정답입니다.

증상 ① 메모리가 계단식으로 는다

어딘가에 크기 없는 버퍼가 있습니다. 힙 덤프에서 Queue 구현체를 찾아보면 대개 바로 나옵니다.

증상 ② 일정 부하부터 지연이 급등

버퍼가 차서 대기가 시작된 지점입니다. 버퍼를 키우면 잠깐 미뤄질 뿐, 처리 속도 자체를 올려야 해결됩니다.

증상 ③ 값이 조용히 사라진다

누군가 conflate 나 drop 전략을 켜 뒀습니다. 버리는 건수를 지표로 남기세요 — 안 남기면 영원히 모릅니다.

이렇게 쓰면 안 됩니다

@PostMapping("/upload")
suspend fun upload(@RequestBody body: ByteArray): String {
    // 이 시점에 파일 전체가 이미 힙에 올라와 있습니다
    File("/data/x.bin").writeBytes(body)   // 게다가 블로킹
    return "ok"
}

조각으로 받아 그대로 흘려보내기

@PostMapping("/upload", consumes = [MULTIPART_FORM_DATA_VALUE])
suspend fun upload(@RequestPart("file") file: FilePart): UploadResult {
    val target = Path("/data/${UUID.randomUUID()}")

    // transferTo 는 조각을 그대로 파일로 넘깁니다 (논블로킹)
    file.transferTo(target).awaitSingleOrNull()

    return UploadResult(target.name, Files.size(target))
}

FilePart.transferTo 가 가장 단순한 정답입니다. S3 처럼 외부로 바로 넘길 때는 file.content() 로 Flux<DataBuffer> 를 받아 업로더에 연결합니다.

파일 내보내기

@GetMapping("/files/{id}")
fun download(@PathVariable id: String): ResponseEntity<Flux<DataBuffer>> {
    val path = storage.resolve(id)
    val body = DataBufferUtils.read(
        path, DefaultDataBufferFactory(), 8 * 1024   // 8KB 조각
    )
    return ResponseEntity.ok()
        .contentType(MediaType.APPLICATION_OCTET_STREAM)
        .header(CONTENT_DISPOSITION, "attachment; filename=\"$id\"")
        .body(body)
}

Content-Length 를 알 수 있으면 꼭 넣으세요. 없으면 청크 전송이 되고, 클라이언트는 진행률을 표시하지 못합니다.

대용량 조회 결과를 CSV 로

@GetMapping("/export", produces = ["text/csv"])
fun export(): Flow<String> = flow {
    emit("id,name,amount\n")
    orderRepository.findAllBy()          // R2DBC — 스트리밍 조회
        .collect { o ->
            emit("${o.id},${o.name},${o.amount}\n")
        }
}   // 100만 행이어도 메모리는 일정합니다

WebFlux 를 쓰기로 했다면

• 코드는 코루틴 스타일로, Reactor 는 경계에서만
• 블로킹 라이브러리를 클래스패스에서 확인 — JDBC·동기 HTTP·파일 IO
• 불가피한 블로킹은 별도 디스패처로 격리 (Dispatchers.IO)
• BlockHound를 개발·CI 에 켜기
• 모든 외부 호출에 타임아웃 + 폴백
• 스트리밍에는 버퍼 정책(느린 소비자 대비)
• 커넥션 풀·다이렉트 메모리 지표를 대시보드에

자주 하는 실수

• Mono 를 구독하지 않고 버리기 — 아무 일도 일어나지 않는다
• block() 호출 — 이벤트 루프에서 부르면 예외 또는 데드락
• subscribeOn으로 블로킹을 감쌌다고 안심 — 스레드만 옮겼을 뿐, 풀이 마르면 같다
• WebFlux + JPA — 가장 흔한 잘못된 조합
• flow 안에서 withContext — 컨텍스트 보존 위반, flowOn을 쓸 것
• 취소 예외를 에러 로그로 — 클라이언트 이탈이 에러로 집계된다

기본 규칙

• 모든 연관은 LAZY — @ManyToOne·@OneToOne의 기본값이 EAGER 라 반드시 명시해야 합니다 (N+1 의 최대 원인)
• 양방향은 꼭 필요할 때만 — 단방향으로 충분한 경우가 많습니다
• 편의 메서드로 양쪽을 동기화 — 한쪽만 바꾸면 DB 와 메모리가 어긋납니다
• cascade = ALL은 애그리거트 안에서만 — 주문→주문항목은 OK, 주문→사용자는 절대 안 됩니다
• 컬렉션은 Set 보다 List가 실무에서 편하지만, 중복 방지가 필요하면 Set + 올바른 equals

코틀린 특유의 주의점

// ① nullable 연관은 타입에 ? 를 붙인다
@ManyToOne(fetch = FetchType.LAZY)
var coupon: Coupon? = null          // optional = true 와 짝을 맞춘다

// ② non-null 연관은 optional = false 로 DB 제약까지
@ManyToOne(fetch = FetchType.LAZY, optional = false)
var user: User                       // ? 없음

// ③ 지연 로딩 프록시를 == 로 비교하지 말 것
if (order.user == currentUser) { }   // ❌ equals 호출 → 프록시가 초기화된다
if (order.user.id == userId) { }     // ✅ id 만 쓰면 초기화 없이도 가능(설정에 따라)

// ④ 컬렉션 초기화는 프로퍼티 선언에서
private val _items = mutableListOf<OrderItem>()   // lateinit 쓰지 말 것

1차 캐시 · 쓰기 지연

@Transactional                // 쓰기가 있으니 readOnly 가 아니다
fun demo(id: Long) {
    val a = repo.findByIdOrNull(id)
    val b = repo.findByIdOrNull(id)
    println(a === b)          // true — 같은 트랜잭션이면 SELECT 한 번만

    // 쓰기 지연: INSERT 도 모았다가 flush 시점에 나간다
    repeat(3) { repo.save(Order(...)) }
    // 여기까지 SQL 없음 → 커밋(또는 flush) 때 한꺼번에
    // ⚠️ 단, id 가 IDENTITY 전략이면 키를 받아야 해서 persist 즉시 INSERT 된다 (da13)
}

// 강제로 반영해야 할 때
entityManager.flush()          // SQL 을 지금 보낸다 (트랜잭션은 유지)
entityManager.clear()          // 1차 캐시를 비운다 (대량 처리에 필수)

LazyInitializationException

// ❌ 트랜잭션이 끝난 뒤 지연 로딩에 접근
@Transactional(readOnly = true)
fun getOrder(id: Long): Order = repo.findByIdOrNull(id)!!

val order = service.getOrder(1)
println(order.items.size)      // 💥 LazyInitializationException

// ✅ 해결 1 — 트랜잭션 안에서 DTO 로 변환해 반환
@Transactional(readOnly = true)
fun getOrder(id: Long): OrderResponse =
    repo.findByIdOrNull(id)!!.toResponse()      // 필요한 것을 여기서 다 읽는다

// ✅ 해결 2 — fetch join 으로 함께 조회 (da07)
// ✅ 해결 3 — @EntityGraph

// ⚠️ open-in-view 로 덮지 마세요 (기본값 true)
// spring.jpa.open-in-view=false 로 끄고, 위 방식으로 해결하는 것이 정석입니다

기본 형태

interface OrderRepository : JpaRepository<Order, Long> {

    // 없을 수 있으면 ? 를 붙인다 — Optional 은 쓰지 않는다
    fun findByOrderNo(orderNo: String): Order?

    // 목록은 non-null (빈 리스트가 온다)
    fun findByUserIdOrderByCreatedAtDesc(userId: Long): List<Order>

    // 페이징
    fun findByStatus(status: OrderStatus, pageable: Pageable): Page<Order>

    // 존재 여부 · 개수
    fun existsByOrderNo(orderNo: String): Boolean
    fun countByUserIdAndStatus(userId: Long, status: OrderStatus): Long

    // 삭제 (반환은 삭제된 건수)
    fun deleteByCreatedAtBefore(t: LocalDateTime): Long

    // 스트리밍 — 대용량 처리 (트랜잭션 안에서 써야 한다)
    @QueryHints(QueryHint(name = HINT_FETCH_SIZE, value = "1000"))
    fun findAllByStatus(status: OrderStatus): Stream<Order>
}

// findById 는 Optional 을 돌려준다 → 코틀린 확장 함수를 쓴다
import org.springframework.data.repository.findByIdOrNull

val order: Order? = repo.findByIdOrNull(id)
val order2: Order = repo.findByIdOrNull(id) ?: throw NotFound(id)

쿼리 메서드 이름 규칙

프로젝션 세 가지 비교

벌크 연산의 함정

@Transactional
fun expireAll() {
    val order = repo.findByIdOrNull(1)!!      // 1차 캐시에 올라간다
    repo.bulkUpdateStatus(NEW, EXPIRED)        // DB 는 바뀌었지만
    println(order.status)                      // 여전히 NEW (캐시가 모른다)
}

// 해결 — @Modifying(clearAutomatically = true) 로 캐시를 비운 뒤 '다시 조회'하거나
//        (이미 꺼내 둔 order 변수는 비워도 옛 값 그대로다)
//        벌크 연산을 별도 트랜잭션·별도 메서드로 분리한다

// 벌크 연산은
// · 더티 체킹을 거치지 않는다 (엔티티 변경 감지 없음)
// · @LastModifiedDate 같은 감사 필드가 갱신되지 않는다
// · 그만큼 빠르다 (수십만 건 처리에 적합)

실무 조합 — 이렇게 씁니다

1. 기본값으로 default_batch_fetch_size: 100을 켜 둔다 — 대부분의 N+1 이 2번 쿼리로 줄어듭니다
2. ~ToOne 연관은 fetch join 으로 함께 조회
3. 컬렉션은 batch size 에 맡기거나, 페이징이 필요하면 id 만 페이징 → 그 id 로 상세 조회 2단계로
4. 조회 전용은 DTO 프로젝션으로 아예 연관을 안 탄다

발견하는 법

spring:
  jpa:
    properties:
      hibernate:
        format_sql: true
        generate_statistics: true      # 쿼리 수를 로그로
logging:
  level:
    org.hibernate.SQL: debug
    org.hibernate.orm.jdbc.bind: trace   # 바인딩 값까지

설정 — Q타입 생성

plugins {
    kotlin("kapt") version "2.2.0"      // ★ KSP 가 아니라 kapt 가 필요하다
}

dependencies {
    implementation("com.querydsl:querydsl-jpa:5.1.0:jakarta")
    kapt("com.querydsl:querydsl-apt:5.1.0:jakarta")
    kapt("jakarta.annotation:jakarta.annotation-api")
    kapt("jakarta.persistence:jakarta.persistence-api")
}

// 생성 위치: build/generated/source/kapt/main
// IDE 가 못 찾으면 sourceSets 에 추가

동적 쿼리 작성

@Repository
class OrderQueryRepository(private val query: JPAQueryFactory) {

    fun search(cond: OrderSearchCondition, pageable: Pageable): Page<OrderSummary> {
        val o = QOrder.order
        val u = QUser.user

        val where = BooleanBuilder().apply {
            cond.status?.let { and(o.status.eq(it)) }
            cond.userId?.let { and(o.user.id.eq(it)) }
            cond.minAmount?.let { and(o.totalAmount.goe(it)) }
            cond.keyword?.takeIf { it.isNotBlank() }?.let { and(u.name.contains(it)) }
        }

        val content = query
            .select(QOrderSummary(o.id, o.orderNo, u.name, o.totalAmount))
            .from(o).join(o.user, u)
            .where(where)
            .orderBy(o.createdAt.desc())
            .offset(pageable.offset)
            .limit(pageable.pageSize.toLong())
            .fetch()

        val total = query.select(o.count()).from(o).join(o.user, u)   // where 가 u 를 쓰므로 조인도 같이
            .where(where).fetchOne() ?: 0L
        return PageImpl(content, pageable, total)
    }
}

QueryDSL 과 비교

Spring Data 와 함께 쓰기

// spring-data-jpa-support 를 넣으면 리포지터리에서 바로 쓸 수 있다
interface OrderRepository : JpaRepository<Order, Long>, KotlinJdslJpqlExecutor

@Service
class OrderService(private val repo: OrderRepository) {

    fun findPaid(minAmount: Long, pageable: Pageable): Page<Order?> =   // JDSL 실행기는 T? 로 돌려준다
        repo.findPage(pageable) {
            select(entity(Order::class))
                .from(entity(Order::class))
                .whereAnd(
                    path(Order::status).eq(OrderStatus.PAID),
                    path(Order::totalAmount).ge(minAmount),
                )
        }
}

DSL 방식 — 테이블을 object 로

object Orders : LongIdTable("orders") {
    val orderNo = varchar("order_no", 40).uniqueIndex()
    val userId = long("user_id").index()
    val status = enumerationByName("status", 20, OrderStatus::class)
    val totalAmount = long("total_amount")
    val createdAt = datetime("created_at").defaultExpression(CurrentDateTime)
}

object Users : LongIdTable("users") {
    val name = varchar("name", 50)
    val email = varchar("email", 100).uniqueIndex()
}

// 조회 — SQL 그대로가 보인다
transaction {
    val rows = (Orders innerJoin Users)
        .select(Orders.id, Orders.orderNo, Users.name, Orders.totalAmount)
        .where { (Orders.status eq OrderStatus.PAID) and (Orders.totalAmount greaterEq 10_000) }
        .orderBy(Orders.createdAt to SortOrder.DESC)
        .limit(20)
        .map { OrderSummary(it[Orders.id].value, it[Orders.orderNo], it[Users.name], it[Orders.totalAmount]) }
}

// 삽입 · 수정 · 삭제
transaction {
    val id = Orders.insertAndGetId {
        it[orderNo] = "ORD-1"
        it[userId] = 100
        it[status] = OrderStatus.NEW
        it[totalAmount] = 24_000
    }
    Orders.update({ Orders.id eq id }) { it[status] = OrderStatus.PAID }
    Orders.deleteWhere { Orders.createdAt less LocalDateTime.now().minusYears(1) }
}

DAO 방식 — 엔티티처럼

class OrderEntity(id: EntityID<Long>) : LongEntity(id) {
    companion object : LongEntityClass<OrderEntity>(Orders)

    var orderNo by Orders.orderNo
    var status by Orders.status
    var totalAmount by Orders.totalAmount
    val items by OrderItemEntity referrersOn OrderItems.orderId   // 일대다
}

transaction {
    val order = OrderEntity.new {
        orderNo = "ORD-2"
        status = OrderStatus.NEW
        totalAmount = 10_000
    }
    order.status = OrderStatus.PAID       // 커밋 때 UPDATE (JPA 와 비슷)

    OrderEntity.find { Orders.status eq OrderStatus.PAID }
        .limit(10)
        .forEach { println(it.orderNo) }
}

// 코루틴에서
suspend fun findAll(): List<OrderSummary> = newSuspendedTransaction(Dispatchers.IO) {
    Orders.selectAll().map { it.toSummary() }
}

코드 생성 설정

// build.gradle.kts (nu.studer.jooq 플러그인)
jooq {
    version.set("3.19.15")
    configurations {
        create("main") {
            jooqConfiguration.apply {
                jdbc.apply {
                    driver = "org.postgresql.Driver"
                    url = "jdbc:postgresql://localhost:5432/app"
                    user = "app"; password = "secret"
                }
                generator.apply {
                    database.apply { inputSchema = "public" }
                    target.apply { packageName = "com.example.jooq" }
                    generate.apply { isPojosAsKotlinDataClasses = true }   // ★ 코틀린 data class 로
                }
            }
        }
    }
}
// Testcontainers 로 띄운 DB 에서 생성하도록 묶으면 로컬 DB 없이도 빌드된다

JPA 와 함께 쓰기 — 실무 패턴

@Service
@Transactional
class OrderService(
    private val repo: OrderRepository,      // 쓰기 — JPA
    private val query: SalesQueryRepository, // 복잡한 조회 — jOOQ
) {
    fun place(cmd: PlaceOrderCommand): Order = repo.save(Order(cmd))

    @Transactional(readOnly = true)
    fun report(from: LocalDate, to: LocalDate) = query.dailySales(from, to)
}

// 같은 트랜잭션·같은 커넥션을 쓰려면
// spring-boot-starter-jooq 를 쓰면 DataSource·트랜잭션이 자동으로 연결된다

락 — 동시 수정 제어

// 낙관적 락 — 버전 컬럼으로 충돌 감지 (대부분의 경우 이걸로 충분)
@Entity
class Product(
    @Id @GeneratedValue val id: Long = 0,
    var stock: Int,
) {
    @Version
    var version: Long = 0      // 충돌 시 OptimisticLockingFailureException
}

// 비관적 락 — 정말 경합이 심한 자리에만 (SELECT ... FOR UPDATE)
interface ProductRepository : JpaRepository<Product, Long> {
    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("select p from Product p where p.id = :id")
    fun findByIdForUpdate(id: Long): Product?
}

@Transactional
fun decreaseStock(id: Long, qty: Int) {
    val p = repo.findByIdForUpdate(id) ?: throw NotFound(id)
    check(p.stock >= qty) { "재고 부족" }
    p.stock -= qty
}

재시도와 분산 환경

// 낙관적 락 충돌은 '재시도'가 정석
@Retryable(
    retryFor = [ObjectOptimisticLockingFailureException::class],
    maxAttempts = 3,
    backoff = Backoff(delay = 50, multiplier = 2.0),
)
@Transactional
fun decreaseStock(id: Long, qty: Int) { /* ... */ }

// 서버가 여러 대라면 DB 락만으로는 부족한 경우가 있다
// → Redis 분산 락(Redisson) · 대기열 — 대규모 트래픽 탭에서 다룬다

// 코루틴에서 재시도할 때는 트랜잭션 경계를 매번 새로 잡아야 한다
suspend fun decreaseWithRetry(id: Long, qty: Int) = retry(times = 3) {
    withContext(Dispatchers.IO) { tx.execute { doDecrease(id, qty) } }
}

배치 INSERT — 한 건씩 넣지 않기

spring:
  jpa:
    properties:
      hibernate:
        jdbc.batch_size: 500          # 묶어서 보낸다
        order_inserts: true
        order_updates: true
  datasource:
    url: jdbc:postgresql://.../app?reWriteBatchedInserts=true   # PG 는 이 옵션까지

@Transactional
fun bulkInsert(rows: List<OrderRow>) {
    rows.chunked(500).forEach { chunk ->
        chunk.forEach { em.persist(it.toEntity()) }
        em.flush()
        em.clear()          // ★ 1차 캐시를 비우지 않으면 메모리가 계속 찬다
    }
}

// ⚠️ @GeneratedValue(strategy = IDENTITY) 면 배치가 동작하지 않는다
//    (INSERT 마다 키를 받아야 하므로) → SEQUENCE + allocationSize 사용

대량 조회 — 페이징의 함정

// ❌ OFFSET 페이징 — 뒤로 갈수록 느려진다 (100만 번째 페이지는 재앙)
repo.findAll(PageRequest.of(10_000, 20))

// ✅ 커서(키셋) 페이징 — 항상 같은 속도
@Query("""
    select o from Order o
    where (:lastId is null or o.id < :lastId)
    order by o.id desc
""")
fun findPage(lastId: Long?, pageable: Pageable): List<Order>

// ✅ 전체 스캔이 필요하면 스트리밍 + clear
@Transactional(readOnly = true)
fun exportAll(sink: (OrderRow) -> Unit) {
    repo.streamAll().use { stream ->
        stream.forEachIndexed { i, o ->
            sink(o.toRow())
            if (i % 1000 == 0) em.clear()
        }
    }
}

기본 설정

spring:
  jpa:
    hibernate:
      ddl-auto: validate       # 운영: validate 또는 none
    open-in-view: false
  flyway:
    enabled: true
    baseline-on-migrate: true  # 기존 DB 에 처음 도입할 때
    locations: classpath:db/migration

src/main/resources/db/migration/
  V1__init.sql
  V2__add_order_status_index.sql
  V3__create_settlement_table.sql
  R__view_daily_sales.sql        # R = 반복 실행 (뷰·함수)

규칙
· 이미 적용된 파일은 절대 수정하지 않는다 (체크섬이 어긋난다)
· 되돌릴 SQL 도 함께 준비 (Flyway 커뮤니티 판에는 undo 가 없다)
· 파괴적 변경은 2단계로: 새 컬럼 추가 → 코드 배포 → 옛 컬럼 제거

무중단 배포와 스키마

테스트 데이터 만들기

// 코틀린 기본 인자로 픽스처를 짧게
fun order(
    orderNo: String = "ORD-${UUID.randomUUID().toString().take(6)}",
    user: User = user(),
    status: OrderStatus = OrderStatus.NEW,
    items: List<OrderItem> = listOf(orderItem()),
) = Order(orderNo = orderNo, user = user, status = status)
    .apply { items.forEach(::addItem) }

// 컨테이너 재사용으로 테스트를 빠르게
// ~/.testcontainers.properties
// testcontainers.reuse.enable=true
@Container @ServiceConnection
val postgres = PostgreSQLContainer("postgres:16-alpine").withReuse(true)

무엇을 테스트할까

• 쿼리 메서드가 의도한 SQL 을 만드는지 — 특히 이름 규칙으로 만든 것
• N+1 이 없는지 — 쿼리 수 검증 (위 예시)
• 제약 조건 — 유니크·NOT NULL 위반 시 예외
• 낙관적 락 충돌 — 동시 수정 시나리오
• 마이그레이션 — Flyway 가 처음부터 끝까지 적용되는지
• DB 방언 차이 — 네이티브 쿼리를 썼다면 반드시 실제 DB 로

코틀린 JPA 규칙 (팀 컨벤션 후보)

• 엔티티는 일반 class — data class 금지
• 식별자만 val, 나머지 var
• equals는 id 기반, hashCode는 클래스 상수
• toString에 연관 필드 제외
• 모든 연관은 LAZY 명시
• @Enumerated(STRING) 고정
• 컬렉션은 private + 읽기 전용 getter
• open-in-view: false · ddl-auto: validate
• default_batch_fetch_size: 100 기본 적용
• 조회 전용 API 는 DTO 프로젝션

갈아탈 신호

minSdk 를 정하는 법

낮출수록 더 많은 기기를 지원하지만 옛 API 대응 코드가 늘어납니다. Android Studio 의 마법사가 버전별 점유율을 보여 주므로 그걸 기준으로 정합니다. 26(Oreo) 이상이면 자바 8 API·알림 채널 등 대부분의 현대적 기능을 쓸 수 있습니다.

서버 개발자가 낯설어하는 것

• 매니페스트 — 화면·서비스·권한을 XML 로 선언해야 시스템이 안다
• 리소스 — 문자열·색·크기를 코드가 아니라 res/에 두고 참조
• R8/ProGuard — 릴리스 빌드에서 코드가 난독화·축소된다 (리플렉션 주의)
• 기기 파편화 — 화면 크기·OS 버전·제조사 변형까지 고려

Activity 생명주기 콜백

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent { AppTheme { AppNavHost() } }     // Compose 진입점
    }
    // onStart  — 화면에 보이기 시작
    // onResume — 사용자와 상호작용 가능 (포커스)
    // onPause  — 다른 화면이 위로 (일부 가림)
    // onStop   — 완전히 안 보임 → 여기서 무거운 작업 중단
    // onDestroy— 끝 (회전 시에도 불린다!)
}

// Compose 에서 생명주기 이벤트를 관찰
@Composable
fun ObserveLifecycle(onResume: () -> Unit) {
    val owner = LocalLifecycleOwner.current
    DisposableEffect(owner) {
        val observer = LifecycleEventObserver { _, event ->
            if (event == Lifecycle.Event.ON_RESUME) onResume()
        }
        owner.lifecycle.addObserver(observer)
        onDispose { owner.lifecycle.removeObserver(observer) }
    }
}

상태 복구 — SavedStateHandle

@HiltViewModel
class SearchViewModel @Inject constructor(
    private val savedState: SavedStateHandle,   // 프로세스 종료도 견딘다
    private val repo: SearchRepository,
) : ViewModel() {

    // 화면 인자 (Navigation 에서 전달된 값)
    private val categoryId: Long = checkNotNull(savedState["categoryId"])

    // 사용자 입력 — 프로세스가 죽어도 복구된다
    val query: StateFlow<String> = savedState.getStateFlow("query", "")

    fun onQueryChange(q: String) { savedState["query"] = q }

    val results: StateFlow<List<Item>> = query
        .debounce(300)
        .flatMapLatest { repo.search(it, categoryId) }
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())
}

핵심 개념 넷