RSS Feed of yunhobb 블로그

Transactional Outbox 오픈소스 기여 기록 — CGLIB 프록시가 만든 핸들러 ID 불안정성

Wed, 20 May 2026 00:00:00 GMT

숙박과 장기 임대 도메인에서 개발을 하다 보면 거주자와 숙박 이용자에게 알림을 보낼 일이 자주 있습니다. 그중에서도 계약 관련 알림은 일부 누락되어도 되는 정도가 아니라 반드시 고객에게 도달해야 하는 알림입니다. 계약 갱신·만료 같은 통지가 누락되면 분쟁의 소지가 됩니다.

그런데 "DB에 계약 상태를 저장하는 것"과 "고객에게 알림을 발행하는 것"은 서로 다른 시스템입니다. 이 둘을 어떻게 원자적으로 묶어 알림을 '반드시' 내보낼 것인가 — 이 문제의 해법으로 자주 언급되는 것이 Transactional Outbox 패턴입니다.

저는 학습 대상으로 namastack-outbox를 골랐습니다. Spring Modulith가 2.1부터 outbox 기반 이벤트 외부화(externalization) 백엔드로 공식 채택한 라이브러리입니다. (Spring Modulith 2.1 M2 릴리스 노트에 spring-modulith-starter-namastack로 소개됩니다.) 모듈러 모놀리스에서 outbox 전용 코드 없이 트랜잭션 이벤트 보장을 얻을 수 있다는 점 때문에 내부 구현을 직접 확인하고 싶었습니다. (컬리 기술블로그에서도 언급이 있었습니다.)

코드를 읽다가 버그 하나를 발견하고 두 개의 PR을 머지하게 된 기록입니다.

1. 배경: Transactional Outbox는 왜 필요할까

먼저 패턴을 정리합니다. 흔한 시나리오는 다음과 같습니다.

1. 계약 상태를 DB에 저장한다 (트랜잭션 커밋)
2. "계약 갱신 안내" 알림을 고객에게 발행한다 (메시지 브로커 등)

문제는 이 둘이 서로 다른 시스템이라는 점입니다. 하나의 비즈니스 동작 안에서 DB와 메시지 브로커, 두 곳에 각각 써야 하는데 microservices.io는 이를 이중 쓰기 문제(dual write problem) 라고 부릅니다. 1번 커밋 직후 애플리케이션이 죽으면 2번이 실행되지 않아 DB엔 계약 변경이 남았는데 고객은 안내를 못 받고, 반대로 2번을 먼저 보내고 1번이 롤백되면 실제로는 바뀌지도 않은 계약에 대한 유령 알림이 나갑니다.

둘을 하나의 분산 트랜잭션으로 묶는 방법은 현실적이지 않습니다. DB와 메시지 브로커를 아우르는 2PC(2단계 커밋)는 적절한 선택지가 아닙니다. Kafka 같은 브로커가 XA 트랜잭션을 제대로 지원하지 않을뿐더러, 2PC 자체가 가용성을 떨어뜨립니다. 필요한 보장은 다음과 같습니다.

DB 트랜잭션이 커밋되면 메시지는 반드시 발행되고, 롤백되면 절대 발행되지 않는다. (microservices.io의 표현으로는 "메시지는 DB 트랜잭션이 커밋된 경우에 한해(if and only if) 발행된다.")

Transactional Outbox는 이 요구를, 메시지 브로커를 트랜잭션 바깥으로 빼내 충족합니다.

비즈니스 데이터와 발행할 메시지(outbox 레코드)를 같은 로컬 트랜잭션 안에서 OUTBOX 테이블에 함께 저장한다. 둘 다 같은 DB이므로, 하나의 ACID 트랜잭션으로 원자적으로 커밋된다.
메시지 릴레이(Message Relay) 라 불리는 별도 프로세스가 OUTBOX 테이블을 읽어, 저장된 레코드를 실제 브로커로 발행(혹은 핸들러 실행)한다.
성공하면 레코드를 완료 처리하고, 실패하면 재시도 정책에 따라 다시 시도한다.

핵심은 "무엇을 할지"를 일단 DB에 안전하게 적어두고, "실행"은 메시지 릴레이가 나중에 별도로 보장한다는 것입니다. 메시지 릴레이를 구현하는 방식은 크게 두 가지입니다.

방식	동작	특징
Polling Publisher	릴레이가 `OUTBOX` 테이블을 주기적으로 폴링해 미처리 레코드를 발행	구현이 단순. 폴링 주기만큼의 지연과 DB 부하
Transaction Log Tailing (CDC)	DB 트랜잭션 로그(binlog 등)를 추적해 outbox 삽입을 감지·발행	지연이 적음. Debezium 같은 CDC 인프라 필요

이번에 뜯어본 namastack-outbox는 이 중 Polling Publisher 방식입니다.

한 가지 주의할 점이 있습니다. 이 패턴이 보장하는 것은 at-least-once(최소 한 번) 입니다. 릴레이가 메시지를 발행한 뒤 "완료" 처리 직전에 죽으면, 재시작 후 같은 레코드를 한 번 더 발행할 수 있습니다. 그래서 microservices.io도 "메시지 릴레이가 메시지를 두 번 이상 발행할 수 있다"고 명시하며, 컨슈머를 멱등(idempotent)하게 설계할 것을 전제로 둡니다.

이번 글의 버그는 이 ID와 관련됩니다. outbox 레코드는 "이 레코드를 처리할 핸들러가 누구인지"를 문자열 ID로 들고 있습니다. 폴링으로 꺼낸 레코드를 올바른 핸들러로 연결하려면 이 ID가 언제나 같은 값으로 안정적이어야 합니다. 버그는 이 지점에 있었습니다.

2. 문제: 핸들러 ID가 프록시 이름을 쓰고 있다

namastack-outbox에서 핸들러 ID를 만드는 코드는 BaseHandlerMethod에 있었습니다.

// io.namastack.outbox.handler.method.BaseHandlerMethod
protected fun buildId(): String {
    val className = bean::class.java.name   // ← 클래스명을 런타임 클래스에서 가져온다
    val methodName = method.name
    val paramTypes = method.parameterTypes.joinToString(",") { it.name }

    return "$className#$methodName($paramTypes)"
}

ID는 클래스명#메서드명(파라미터타입) 형태입니다. 클래스명을 bean::class.java.name으로 가져오고 있었는데, 핸들러 빈에 @Transactional이 붙어 있으면 이 bean은 원본 객체가 아니라 CGLIB 프록시일 수 있다는 점이 문제였습니다.

Spring은 @Transactional 같은 AOP가 적용된 빈을 프록시(Proxy) 로 감쌉니다. 이 프록시를 만드는 방식은 두 가지입니다.

방식	언제 쓰이나	`bean::class.java.name`이 돌려주는 값
JDK 동적 프록시(JDK Dynamic Proxy)	빈이 인터페이스를 구현하고 `proxyTargetClass=false`일 때	`jdk.proxy2.$Proxy123` — 원본과 전혀 무관한 이름
CGLIB 프록시	인터페이스가 없거나 `proxyTargetClass=true`일 때	`com.example.MyHandler$$SpringCGLIB$$0` — 원본을 상속한 서브클래스

JDK 동적 프록시는 같은 인터페이스를 구현한 별도 객체를, CGLIB는 원본 클래스를 상속한 서브클래스를 런타임에 만들어 냅니다. Spring Boot는 2.0부터 proxyTargetClass=true가 기본값이라 대개 CGLIB이 쓰이지만, 중요한 건 어느 쪽이든 bean::class.java.name이 원본 클래스명을 돌려주지 않는다는 점입니다. CGLIB이면 원본 이름 뒤에 접미사가 붙고, JDK 프록시면 아예 com.sun.proxy.$Proxy123처럼 핸들러와 무관한 이름이 나옵니다.

이 글의 핸들러 빈은 CGLIB로 감싸진 경우라, bean::class.java.name은 이런 값을 돌려주고 있었습니다.

com.example.MyHandler$$SpringCGLIB$$0

이게 왜 문제냐면, 이 ID는 DB에 그대로 저장되어 outbox 레코드가 핸들러를 찾는 키로 쓰이기 때문입니다. 핸들러 ID가 안정적이지 않으면 다음과 같은 일이 벌어집니다.

@Transactional을 새로 붙이거나 떼면 → 프록시 적용 여부가 바뀌고 → 클래스명이 바뀌고 → ID가 바뀝니다.
그러면 이미 DB에 쌓여 있던 outbox 레코드의 ID(...$$SpringCGLIB$$0#...)와 새로 등록된 핸들러의 ID가 어긋나, 재시도 정책 조회(retryPolicyRegistry.getByHandlerId())가 깨집니다.

$$SpringCGLIB$$0의 숫자 접미사는 프록시 생성 순서 등에 따라 달라질 수 있는 불안정한 식별자입니다. 영속화되는 ID의 재료로 쓰기에는 적합하지 않습니다. 환경에 따라 가끔 발생하는 버그가 아니라, AOP 설정을 변경하는 순간 조용히 깨지는 문제였습니다.

3. 첫 번째 PR (#237): 진짜 클래스 이름을 사용하자

이 라이브러리 안에는 이미 프록시를 벗겨내는 유틸이 있었습니다. Spring이 제공하는 AopProxyUtils.ultimateTargetClass()를 감싼 ReflectionUtils.getTargetClass()입니다. ID를 만들 때 이것을 쓰도록 한 줄만 바꾸면 됩니다.

// AS-IS
val className = bean::class.java.name

// TO-BE
val className = ReflectionUtils.getTargetClass(bean).name  // ← 프록시 뒤의 실제 타겟 클래스

이렇게 하면 @Transactional이 붙든 안 붙든 핸들러 ID는 언제나 원본 클래스명(com.example.MyHandler#handle(java.lang.String))으로 안정적으로 고정됩니다.

테스트는 "CGLIB 프록시로 감싼 빈과 원본 빈이 같은 ID를 만드는가"를 검증하도록 작성했습니다.

@Test
fun `handler ID uses target class name not CGLIB proxy class name`() {
    val proxiedBean = createCglibProxy(targetBean)
    val handlerFromTarget = TypedHandlerMethod(targetBean, method)
    val handlerFromProxy = TypedHandlerMethod(proxiedBean, method)

    assertThat(handlerFromProxy.id).isEqualTo(handlerFromTarget.id)
}

@Test
fun `handler ID contains original class name not proxy class name`() {
    val proxiedBean = createCglibProxy(targetBean)
    val handlerFromProxy = TypedHandlerMethod(proxiedBean, method)

    assertThat(handlerFromProxy.id).contains("TestHandler")
    assertThat(handlerFromProxy.id).doesNotContain("CGLIB")
    assertThat(handlerFromProxy.id).doesNotContain("$$")
}

이슈(GH-238)를 먼저 등록하고, 본문 한 줄 + 테스트로 PR을 올렸습니다. 변경량은 적었지만 리뷰 과정에서 추가로 확인할 점이 있었습니다.

4. 리뷰에서 날아온 지적: 작업이 하위 호환을 깨는 변경이다

첫 PR(#237)이 머지된 직후, 메인테이너(@rolandbeisel)가 제가 놓치고 있던 문제를 짚었습니다.

"이건 사실 breaking change입니다. 이미 옛 ID(CGLIB 프록시 이름)를 참조하는 outbox 레코드가 DB에 남아 있는 상태에서 업데이트 후 애플리케이션을 재시작하면, 그 옛 ID로는 핸들러를 못 찾습니다."

저는 "앞으로 만들어질 ID"만 고려했고, 이미 DB에 쌓여 있는, 아직 처리되지 않은 레코드를 놓치고 있었습니다.

업그레이드 전 저장된 레코드의 ID: com.example.MyHandler$$SpringCGLIB$$0#handle(...) (옛 프록시 이름)
업그레이드 후 등록되는 핸들러의 ID: com.example.MyHandler#handle(...) (안정적인 새 이름)

둘이 매칭되지 않으니, 업그레이드 시점에 미처리 상태로 남아 있던 레코드들은 핸들러를 찾지 못합니다. ID 생성 규칙을 바꾼 것이 기존 데이터와의 단절을 만든 것입니다.

저는 두 가지 해법을 제안하고 후속 PR을 열겠다고 했습니다.

등록 시 두 ID(프록시 이름 + 실제 이름)를 모두 저장해 옛 레코드도 매칭되게 한다.
1차 조회 실패 시 CGLIB 접미사를 떼고 재조회하는 fallback을 둔다.

메인테이너는 1번 방향을 권했습니다. "안정적인 ID와 레거시 ID 둘 다로 핸들러를 등록하고, 조회는 안정 ID를 먼저 본 뒤 없으면 레거시 ID로 떨어지게 하자." 협력자(@Alek96)는 한 가지를 더 짚어줬습니다. *"핸들러 레지스트리뿐 아니라 fallback 레지스트리도 같은 ID를 쓰니 둘 다 처리해야 한다."*

5. 두 번째 PR (#240): 레거시 ID를 별칭으로 함께 등록

방향이 정해진 뒤 구현은 명확했습니다. 먼저 BaseHandlerMethod에 레거시 ID(런타임 클래스명 = 프록시 이름 기반)를 별도로 계산해 들고 있게 했습니다. 안정 ID는 그대로 두었습니다.

/** 런타임 클래스명 기반 ID. CGLIB 접미사($$SpringCGLIB$$0 등)가 포함될 수 있다. */
val legacyId: String = buildLegacyId()

protected fun buildLegacyId(): String {
    val className = bean::class.java.name   // 프록시면 프록시 이름 그대로
    val methodName = method.name
    val paramTypes = method.parameterTypes.joinToString(",") { it.name }
    return "$className#$methodName($paramTypes)"
}

그리고 각 레지스트리에 registerAlias()를 추가했습니다. 일반 register()와 달리, ID 기반 조회 맵에만 별칭을 추가합니다. (타입별 핸들러 목록 등에 중복으로 넣지 않기 위해서입니다.)

// OutboxHandlerRegistry
internal fun registerAlias(aliasId: String, handlerMethod: OutboxHandlerMethod) {
    check(handlersById.putIfAbsent(aliasId, handlerMethod) == null) {
        "Duplicate alias ID detected: $aliasId"
    }
}

마지막으로 빈을 스캔해 등록하는 OutboxHandlerBeanPostProcessor에서, 빈이 프록시일 때만(handler.id != handler.legacyId) 레거시 별칭을 모든 레지스트리에 함께 등록하도록 했습니다.

// d. 빈이 AOP 프록시일 때만 레거시 별칭 등록 (하위 호환)
if (handler.id != handler.legacyId) {
    registerLegacyAliases(handler.legacyId, result)
}

private fun registerLegacyAliases(legacyId: String, result: HandlerScanResult) {
    val handler = result.handler

    handlerRegistry.registerAlias(legacyId, handler)

    result.fallback?.let { fallback ->
        fallbackHandlerRegistry.registerAlias(legacyId, fallback)   // ← Alek96이 짚어준 부분
    }

    retryPolicyScanners
        .mapNotNull { it.scan(handler) }
        .forEach { policy -> retryPolicyRegistry.registerAlias(legacyId, policy) }
}

여기서 한 가지를 추가로 처리했습니다. 메인테이너 토론에서는 핸들러 레지스트리와 fallback 레지스트리만 언급됐지만, 레거시 ID를 가진 레코드는 재시도 정책 조회도 동일하게 작동해야 합니다. 그래서 OutboxRetryPolicyRegistry에도 registerAlias()를 더했습니다. PR 본문에 "불필요하면 빼겠다"고 적어 두었는데, 협력자가 "Good catch" 로 승인해 주었습니다.

이렇게 하면 업그레이드 후에도 흐름이 끊기지 않습니다.

업그레이드 후, 옛 레코드(ID = ...$$SpringCGLIB$$0#handle)가 처리될 때
1. 안정 ID로 핸들러 조회 → 없음
2. 레거시 ID(별칭)로 조회  ← 별칭으로 등록해 둔 덕분
3. 핸들러 + fallback + 재시도 정책 모두 정상 해석

테스트로는 ▲프록시 빈일 때 두 ID가 같은 핸들러로 해석되는지 ▲프록시가 아닌 빈엔 별칭이 안 생기는지 ▲fallback·재시도 정책 별칭이 제대로 도는지를 검증했고, 커버리지 100%로 1.2.0 마일스톤에 머지됐습니다.

6. 마무리

이번 기여에서 정리한 점은 다음과 같습니다.

변경 전에 영향도를 파악한다. 이번 수정은 bean::class.java.name 한 줄을 바꾸는 것이 전부였습니다. 그러나 이 한 줄이 만든 ID는 outbox 레코드로 DB에 저장되고, fallback 레지스트리와 재시도 정책 조회(retryPolicyRegistry.getByHandlerId()) 의 키로도 쓰이고 있었습니다. ID 생성 규칙을 바꾸면 이미 저장된 레코드의 옛 ID와 새로 등록되는 핸들러의 ID가 어긋나, 그 레코드들은 핸들러를 찾지 못합니다. 그래서 고치기 전에 "이 값이 DB에 저장되는가? 어떤 레지스트리가 키로 쓰는가? 이미 저장된 값은 그대로 매칭되는가?" 를 먼저 확인해야 했습니다.
리뷰가 설계를 보강했다. 첫 PR의 breaking change, fallback 레지스트리 별칭, 재시도 정책 별칭 — 이 셋은 제가 아니라 리뷰어(@rolandbeisel, @Alek96)가 짚어준 지점입니다. 리뷰가 코드 검사를 넘어 설계 보강 역할을 했습니다.
PR #237: Fix handler ID instability with CGLIB proxies
PR #240: Add legacy alias support for backward compatibility with CGLIB proxy handler IDs

EcsRunTaskOperator에 skip_on_exit_code 옵션 추가 — Apache Airflow 기여 기록

Fri, 13 Mar 2026 00:00:00 GMT

관리비 및 공과금 데이터를 크롤링하는 파이프라인을 구축했습니다. 로컬 개발 환경에서는 크롤러를 Docker 컨테이너로 구동하여 정상 동작을 확인했고, 스케줄링은 Apache Airflow를 활용했습니다.

그러나 해당 크롤러를 dev 환경(AWS ECS)에 배포하여 실행하자, 로컬에서 정상 처리되던 태스크가 Airflow에서 실패(Failed) 상태로 종료되었습니다.

1. 현상: 로컬 Docker(스킵)와 dev ECS(실패)의 동작 차이

수도, 전기, 가스 관리비 도메인의 특성상, 고지서 발행일 특정일 기준 n영업일 이내라고 명시만 되어있고, 매번 동일한 일자에 고지가 되지 않습니다. 따라서 특정 월의 고지서가 아직 업로드되지 않는 케이스가 존재합니다. 이는 데이터를 수집할 수 없는 상태이므로, 태스크를 실패가 아닌 스킵(Skip)으로 처리해야 합니다.

이를 위해 크롤러가 데이터 미존재 시 0이 아닌 특정 exit code를 반환하며 종료되도록 설계했습니다. 그러나 같은 크롤러가 실행 환경에 따라 다르게 동작했습니다.

로컬 환경 (DockerOperator): 설정한 exit code가 Airflow에서 스킵(Skip) 상태로 정상 인식되었습니다.
dev 환경 (EcsRunTaskOperator): 동일한 크롤러가 동일한 exit code를 반환했음에도 태스크가 실패(Failed)로 처리되었습니다.

EcsRunTaskOperator는 ECS 태스크의 exit code가 0이 아닐 경우, 예외 조건 없이 AirflowException을 발생시키며 태스크를 실패로 기록하고 있었습니다.

2. exit code의 정의와 활용

exit code(종료 코드)는 프로세스가 종료될 때 부모 프로세스에 전달하는 0~255 사이의 정수 값입니다. 셸에서 실행한 직전 명령의 종료 코드는 $?로 확인할 수 있습니다.

$ ls /not-exist
ls: /not-exist: No such file or directory
$ echo $?
1 # ← 명령 수행 실패를 의미하는 코드 1 반환

POSIX 규격에서 통용되는 주요 exit code의 의미는 다음과 같습니다.

exit code	정의된 의미
0	성공 (Success)
1	일반 오류 (General error)
2	셸 오용 (Misuse of shell builtins)
126	명령 실행 불가 (Permission denied 등)
127	명령을 찾을 수 없음 (Command not found)
128 + n	시그널 n에 의한 종료 (예: 130 = SIGINT, Ctrl+C)
255	범위를 벗어난 종료 코드

0은 성공을 의미하지만, 0이 아닌 나머지 코드의 구체적인 의미는 애플리케이션 단위에서 정의하여 사용할 수 있습니다. 즉, "exit code 2는 오류가 아니라 데이터 미존재(스킵)를 의미한다"와 같은 규칙 설정이 가능합니다. 앞서 설계한 크롤러가 사용한 방식이 바로 이것입니다.

3. 오퍼레이터별 기능 비교

두 환경의 결과 차이는 Airflow 오퍼레이터의 기능 공백에서 발생했습니다. Airflow 소스 코드를 확인한 결과, 컨테이너 실행 오퍼레이터 간 옵션 지원 여부가 달랐습니다.

오퍼레이터	`skip_on_exit_code` 지원
`DockerOperator`	지원함
`KubernetesPodOperator`	지원함
`EcsRunTaskOperator`	지원 안 함

skip_on_exit_code는 지정한 exit code가 반환되었을 때 AirflowSkipException을 발생시켜 태스크를 스킵 상태로 처리하는 파라미터입니다. 타 오퍼레이터와의 기능 일관성을 맞추기 위해, EcsRunTaskOperator에도 해당 기능을 직접 추가하기로 결정했습니다.

4. 기존 PR 보완 및 코드 구현

동일한 기능 구현을 시도했던 기존 작업(PR #47256)이 존재했으나, 머지되지 못하고 중단된 상태임을 확인했습니다. 그래서 이 PR의 구현 방향을 참고하여, 누락된 부분까지 보완해 직접 구현한 뒤 새 PR(apache/airflow#63274)로 제출했습니다.

수정 작업은 providers/amazon/.../operators/ecs.py 파일에서 진행되었습니다.

# 1) 파라미터 정의 — 단일 정수(int) 또는 컨테이너 객체 허용
skip_on_exit_code: int | Container[int] | None = None,

# 2) 데이터 정규화 — 단일 값 리스트화 및 None 예외 처리
self.skip_on_exit_code = (
    skip_on_exit_code
    if isinstance(skip_on_exit_code, Container)
    else [skip_on_exit_code]
    if skip_on_exit_code is not None
    else []
)

# 3) 조건 판정 — 지정된 exit code 일치 여부에 따라 발생 예외를 분기
exit_code = container.get("exitCode", 1)
if exit_code in self.skip_on_exit_code:
    exception_cls: type[AirflowException] = AirflowSkipException
else:
    exception_cls = AirflowException

하드코딩되어 있던 AirflowException 발생 로직을, skip_on_exit_code 포함 여부에 따라 AirflowSkipException으로 분기되도록 수정한 것이 핵심입니다.

기능 검증을 위해 아래 항목에 대한 유닛 테스트(Unit Test)도 추가했습니다.

정의된 exit code 반환 시 AirflowSkipException 발생 여부
로그 출력과 스킵 처리의 정상 연동 여부
정의되지 않은 exit code 반환 시 기존대로 AirflowException 발생 여부

5. 마무리

DockerOperator와 KubernetesPodOperator에서 제공하던 skip_on_exit_code 옵션을 EcsRunTaskOperator에도 동일하게 구현했습니다.
이를 통해 AWS ECS 환경에서도 특정 exit code를 기준으로 태스크를 실패가 아닌 스킵(Skip) 상태로 제어할 수 있게 되었습니다.
오픈소스 기여 시, 중단된 기존 PR을 분석하고 보완하는 방식으로 개발 리소스를 단축할 수 있습니다. 새로운 문제일수록 누군가 이미 시도했을 가능성이 높으므로, 구현에 앞서 관련 이슈와 PR을 먼저 검색하는 것이 효율적입니다.

전체 구현과 리뷰 과정은 머지된 PR에서 확인할 수 있습니다 → apache/airflow#63274 — Add skiponexit_code support to EcsRunTaskOperator

ArgoCD는 Healthy인데 왜 503은 반환했을까?

Sun, 23 Nov 2025 00:00:00 GMT

현재 저희 서비스의 DEV 환경은 다음과 같이 구성되어 있습니다.

오케스트레이션: AWS EKS 위에 Spring Boot 애플리케이션을 파드로 배포
배포: ArgoCD(GitOps)로 매니페스트를 동기화, 갱신은 기본 전략인 롤링 업데이트(rolling update)
트래픽 인입: ALB Ingress + AWS Load Balancer Controller, 타겟 모드는 target-type: ip
헬스 체크: 쿠버네티스 readinessProbe와 ALB 자체 health check가 각각 동작

즉 트래픽은 사용자 → ALB → (파드 IP) → Spring Boot 파드 경로로 흐르고, 배포는 ArgoCD가 새 파드를 띄우고 구 파드를 내리는 식으로 진행됩니다.

ArgoCD에서는 모든 파드가 Healthy로 표시되는데, 배포 직후 API를 호출하면 간헐적으로 503 응답을 마주했습니다.

1. ArgoCD 배포 상태와 ALB 헬스 체크의 불일치 현상

저희는 ALB Ingress를 target-type: ip로 쓰고 있었습니다.

alb.ingress.kubernetes.io/target-type: ip

이 설정에서 ALB는 노드(NodePort)를 거치지 않고 파드 IP에 직접 트래픽을 전달합니다. 이때 ALB의 판정 단위는 파드 하나하나가 됩니다. 새로 뜬 파드는 kubelet readinessProbe와 ALB 자체 health check를 각각 통과해야 트래픽을 받는데, 둘은 서로의 판정 결과를 주고받지 않습니다.

항목	쿠버네티스	AWS ALB
healthy 판단 주체	kubelet	ALB (보통 다른 AZ에서)
통과 조건	`readinessProbe` 1회 200	health check `healthy_threshold` 연속 200
ArgoCD 가시성	보임	안 보임

kubelet은 자기 노드의 파드를 보고 readinessProbe가 한 번 200을 주면 곧장 Ready로 표시합니다. 그러면 K8s Endpoints에 파드 IP가 올라가고, ArgoCD는 이를 보고 Healthy를 표시합니다.

실제로 트래픽을 전달하는 주체는 ALB입니다. ALB는 ArgoCD가 보는 K8s 상태를 알지 못합니다. 자기만의 health check를 연속으로 통과시켜 healthy라고 판단하기 전까지는 그 파드에 요청을 보내지 않습니다.

즉 ArgoCD가 보는 healthy와 ALB가 보는 healthy는 같은 단어지만 서로 다른 상태를 가리킵니다. 이 둘이 어긋나는 순간이 배포 시점이었습니다.

참고: target-type: instance였다면 ALB 타겟은 노드(NodePort)이므로, 새 파드가 떠도 ALB에 따로 등록할 필요 없이 라우팅은 kube-proxy가 맡습니다. 아래에서 볼 파드 단위 등록 지연이 애초에 생기지 않습니다. 대신 노드 한 단계를 더 거치는 트레이드오프가 있습니다.

2. 503은 코드 버그가 아니다: ALB가 직접 뱉는 신호

원인을 추적하기 전에 503의 의미부터 짚어야 했습니다. ALB는 백엔드(타겟)까지 도달하지 못하면 자기가 직접 상태 코드를 생성하기 때문입니다.

503(Service Unavailable)은 타겟 그룹에 healthy 타겟이 0일 때, ALB가 어디에도 요청을 보내지 못하고 자기 선에서 생성해 돌려주는 코드입니다. 즉 503은 코드가 실패했다는 뜻이 아니라 요청을 보낼 곳이 없다는 신호입니다.

따라서 ArgoCD가 Healthy인데도 503이 떴다는 것은, ALB 관점에서는 healthy 타겟이 0인 순간이 있었다는 의미입니다.

참고: 같은 5xx라도 502(Bad Gateway, upstream이 RST를 보낸 계열)·504(Gateway Timeout, upstream 응답 지연)는 요청을 보냈으나 실패한 쪽이라 원인이 다릅니다. 이번 건은 타겟이 0이라 아예 보내지 못한 503이었습니다.

3. 진짜 원인: Registration Lag

원인은 새 파드가 ALB에 등록되어 healthy가 되기까지의 지연(registration lag) 이었습니다. 배포 시점을 초 단위로 풀어보면 간극이 그대로 드러납니다.

t=0s    : 새 Pod 생성
t=120s  : kubelet readinessProbe 통과 → K8s Endpoints에 IP 추가
          → ArgoCD는 여기서 'Healthy' 표기 ✓
t=121s  : AWS LB Controller가 ALB.RegisterTargets 호출
          → target state: 'initial'
t=121~270s : ALB 자체 health check 진행
             (30초 간격 × healthy_threshold=5)
             ▶ 이 구간에 요청이 오면 503 (healthy target = 0)
t=270s  : ALB target state: 'healthy'  ← 이제야 트래픽 받을 준비 완료

readinessProbe가 통과한 t=120s와 ALB가 healthy로 인정한 t=270s 사이에 약 150초의 빈 구간이 있습니다. 이 150초 동안 ArgoCD는 Healthy를 표시하지만, 롤링 업데이트가 같은 타이밍에 기존 파드를 종료시키면, ALB 입장에서는 트래픽을 받을 healthy 타겟이 0이 됩니다.

쿠버네티스의 readinessProbe는 앱 프로세스가 떴다는 것까지만 보장합니다. 그것을 곧바로 트래픽 받을 준비가 끝났다는 의미로 받아들여 구 파드를 내린 것이, ArgoCD는 Healthy인데 사용자는 503을 보는 상황의 원인이었습니다.

4. 해결: 두 Control Plane을 K8s readiness로 묶는다

원인은 한 줄로 정리됩니다. kubelet이 Ready라고 해서 ALB도 healthy로 인식하는 것은 아니다. 따라서 해법도 명확합니다. ALB가 healthy라고 인정하기 전까지는 쿠버네티스도 파드를 Ready로 표시하지 않게 만들어, 두 health 판정을 한 지점에서 일치시키면 됩니다.

이걸 그대로 구현한 게 AWS Load Balancer Controller의 Pod Readiness Gate입니다.

spec:
  readinessGates:
    - conditionType: target-health.elbv2.k8s.aws/<ingress>_<service>_<port>

이 게이트가 붙으면 파드는 readinessProbe를 통과해도 ALB target이 healthy가 될 때까지 Ready로 마킹되지 않습니다. 즉 3번에서 본 150초의 간극 동안 롤아웃이 전진하지 못하므로, 기존 파드도 그대로 유지됩니다. healthy 타겟이 0이 되는 구간 자체가 사라집니다. (네임스페이스에 elbv2.k8s.aws/pod-readiness-gate-inject=enabled 라벨을 붙이면 컨트롤러 웹훅이 이 게이트를 자동 주입합니다.)

처방을 한 장으로 정리하면 이렇습니다.

문제	처방	원리
Registration lag (503)	Pod Readiness Gate	두 health 판정을 K8s readiness에서 일치
단일 replica	`replicas ≥ 2`	가용성 하한 확보
Probe 모호	readiness/liveness 분리	health 정의를 layer별로 분리

실제로 적용한 매니페스트는 다음과 같습니다.

spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: api-admin
          startupProbe:
            httpGet: { path: /actuator/health/liveness, port: 8080 }
            failureThreshold: 30
            periodSeconds: 5
          readinessProbe:
            httpGet: { path: /actuator/health/readiness, port: 8080 }
            periodSeconds: 5
            failureThreshold: 2
          livenessProbe:
            httpGet: { path: /actuator/health/liveness, port: 8080 }
            periodSeconds: 30
---
# Ingress annotations
alb.ingress.kubernetes.io/healthcheck-path: /actuator/health/readiness
alb.ingress.kubernetes.io/healthcheck-interval-seconds: '10'
alb.ingress.kubernetes.io/healthy-threshold-count: '2'

health check 간격을 10초 × threshold 2로 줄여 등록 지연 자체를 짧게 만들었습니다(150초 → 약 20초). probe를 /actuator/health/readiness와 /liveness로 분리한 것도 핵심입니다. 살아 있다(liveness)와 트래픽을 받을 수 있다(readiness)는 서로 다른 판정이기 때문입니다. 거기에 replicas: 2로 두어, 롤링 중 한 파드가 교체되는 순간에도 healthy 타겟이 0으로 떨어지지 않도록 가용성 하한을 확보했습니다.

5. 마무리

쿠버네티스(kubelet)와 ALB라는 두 개의 Control Plane이 서로 다른 시점에 'healthy'를 판단하고, 그 propagation delay가 사용자에게 503으로 드러난 것이었습니다. ArgoCD가 Healthy를 표시하는 시점과 ALB가 트래픽을 전달해도 된다고 판단하는 시점은 처음부터 일치하지 않았습니다.

어떤 컴포넌트가 'healthy'라고 할 때 그것이 누구의 관점인지 확인하지 않으면, production에서 503을 만날 수 있습니다.

플랫폼이 무중단 배포를 보장해 줄 것 같지만, 서로 다른 두 시스템이 맞물리는 경계에는 이런 시차가 존재합니다. 그 시차를 명시적으로 견디도록 Pod Readiness Gate로 두 plane을 한 지점에 묶는 것이 이번 503을 메운 처방이었습니다.

INSERT 한 문장이 일으킨 데드락 — 서브쿼리 S락과 트리거 X락의 락 순서 역전 분석

Wed, 30 Apr 2025 00:00:00 GMT

이 글은 "S락·X락·갭 락·락 승격 — InnoDB 락 노트"에 이어지는 2편입니다. 1편에서 정리한 공유락(S)·배타락(X)·락 승격 개념을 그대로 가져다 씁니다.

운영 DB 모니터링에서 데드락(deadlock) 기록을 발견했습니다. 데드락 로그가 지목한 문장은 contract_slots에 행 하나를 넣는 upsert 쿼리였습니다. 단순해 보이는 INSERT 한 번이 교착에 빠진 원인을 추적했습니다.

원인은 한 INSERT 문이 같은 contracts 행을 두 번(S락 → X락) 잠그고 있었다는 데 있습니다. 그 사이에 다른 행의 X락이 끼어들면서 교착이 발생했습니다. 로그를 한 줄씩 따라가며 살펴봅니다.

1. 현상: upsert 한 번에 데드락 로그가 찍혔다

문제의 쿼리는 이렇게 생겼습니다. gcid로 가장 최신 계약(contracts)을 골라 그 id를 contract_slots에 꽂는, ON DUPLICATE KEY UPDATE 기반 upsert입니다.

public Mono<Long> upsertContractSlot(UpsertContractSlot upsertContractSlot) {
    String query =
        """
        insert into contract_slots (contract_id, slot_id, user_id, ...)
        values (
            (select c.id                              -- ⚠️ 문제 1: contracts에 S락
             from contracts as c
             join (select max(c.ezrems_cid) as max_cid
                   from contracts as c
                   where c.ezrems_gcid = :ezrems_gcid
                   group by c.ezrems_gcid) as subquery
             on subquery.max_cid = c.ezrems_cid),
            :slot_id,
            :user_id,
            ...
        )
        on duplicate key update ...                   -- ⚠️ 문제 2: 트리거 발동 → contracts에 X락
        """;

    return databaseClient.sql(query)
        .bind("ezrems_gcid", upsertContractSlot.getGcid())
        .fetch().rowsUpdated();
}

그리고 SHOW ENGINE INNODB STATUS가 남긴 데드락 기록입니다. (테이블은 MariaDB / InnoDB, 일부 컬럼은 생략했습니다.)

------------------------
LATEST DETECTED DEADLOCK
------------------------
2025-10-28 08:42:27

*** (1) TRANSACTION:
TRANSACTION 1110068327, ACTIVE 0 sec starting index read
UPDATE mims_authorizations AS ma
    JOIN contracts AS c ON NEW.contract_id = c.id
    ...
WHERE ma.source_id = NEW.id

*** (1) WAITING FOR THIS LOCK TO BE GRANTED:
RECORD LOCKS on table `mgrv_dev`.`contracts`
trx id 1110068327 lock_mode X locks rec but not gap waiting
Record: contracts.id = 197084

*** (1) CONFLICTING WITH:
RECORD LOCKS on table `mgrv_dev`.`contracts`
trx id 1110068328 lock mode S locks rec but not gap
Record: contracts.id = 197084

*** (2) TRANSACTION:
TRANSACTION 1110068328, ACTIVE 0 sec inserting
insert into contract_slots (contract_id, ...)
values ((select c.id from contracts where c.ezrems_gcid = 141431 ...), ...)
on duplicate key update ...

*** (2) WAITING FOR THIS LOCK TO BE GRANTED:
RECORD LOCKS on table `mgrv_dev`.`contract_slots`
index contract_slots_ezrems_gcid_ezrems_guest_code_uindex
trx id 1110068328 lock_mode X waiting
Record: ezrems_gcid=141431, ezrems_guest_code=0, id=2088501

*** (2) CONFLICTING WITH:
RECORD LOCKS on table `mgrv_dev`.`contract_slots`
trx id 1110068327 lock_mode X
Record: ezrems_gcid=141431, ezrems_guest_code=0, id=2088501

*** WE ROLL BACK TRANSACTION (1)

로그에는 INSERT 하나에 트랜잭션 둘이 얽혀 있고, 그중 한쪽은 mims_authorizations를 UPDATE 하고 있습니다. 그런데 upsert 쿼리에는 mims_authorizations라는 테이블이 등장하지 않습니다. 단서는 (1) 트랜잭션의 SQL에 박힌 NEW.contract_id, NEW.id였습니다. NEW는 트리거(Trigger) 안에서만 쓸 수 있는 키워드입니다. 즉 이 UPDATE는 직접 호출한 쿼리가 아니라, contract_slots에 행이 들어갈 때 따라 도는 트리거의 본문입니다.

2. 로그 해부: 누가 무엇을 쥐고 무엇을 기다렸나

InnoDB의 데드락 로그는 각 트랜잭션이 무엇을 기다리는지(WAITING FOR), 그리고 그게 누구와 충돌하는지(CONFLICTING WITH)를 기록합니다. 두 트랜잭션이 같은 gcid=141431을 동시에 처리하면서, 같은 contracts 행(197084)과 같은 contract_slots 행(2088501)을 두고 엇갈렸습니다. 정리하면 이렇습니다.

트랜잭션	이미 쥔 락 (보유)	기다리는 락 (대기)
trx …327 (트리거 UPDATE 실행 중)	`contract_slots`(2088501) X락	`contracts`(197084) X락
trx …328 (INSERT 실행 중)	`contracts`(197084) S락	`contract_slots`(2088501) X락

화살표로 그려 보면 서로의 꼬리를 문 모양이 드러납니다.

trx …327 ── 기다림 ──▶ contracts(197084)   ◀── 쥐고 있음 ── trx …328
trx …328 ── 기다림 ──▶ contract_slots(2088501) ◀── 쥐고 있음 ── trx …327

327은 328이 쥔 contracts를, 328은 327이 쥔 contract_slots를 기다립니다. 전형적인 순환 대기(circular wait), 곧 교착입니다. InnoDB는 둘 중 하나를 롤백시켜 교착을 풀며, 로그 마지막 줄 WE ROLL BACK TRANSACTION (1)이 그 결과입니다. 트리거를 돌리던 327이 롤백됐습니다.

여기서 한 가지 의문이 남습니다. 같은 쿼리를 호출한 두 세션인데, 왜 한쪽은 contracts에 S락(공유락)을, 다른 쪽은 X락(배타락)을 쥐고 있는가 하는 점입니다. 다음 절에서 그 이유를 살펴봅니다.

3. 원인: 한 INSERT 문 안의 두 단계 락

이유는 하나의 upsert가 contracts를 두 번, 서로 다른 모드로 잠근다는 데 있습니다. 쿼리에 달아둔 ⚠️ 문제 1, ⚠️ 문제 2가 바로 그 두 지점입니다.

문제 1 — 서브쿼리가 거는 S락. values (...) 안에는 contract_id를 구하려고 contracts를 읽는 서브쿼리가 들어 있습니다. InnoDB는 기본 격리 수준(REPEATABLE READ)에서, 쓰기 문장이 다른 행을 읽어서 그 값을 쓰면 읽은 행의 일관성을 지키기 위해 공유락(S락)을 건다. 그래서 INSERT가 진행되는 동안 선택된 contracts 행(197084)에는 S락이 잡힙니다. S락은 공유락이므로 두 세션이 동시에 같은 행에 S락을 쥐어도 충돌하지 않는다.

문제 2 — 트리거가 거는 X락. ON DUPLICATE KEY UPDATE는 이름과 달리 실제로 행을 쓰는 동작이라, contract_slots에 걸린 AFTER 트리거를 깨운다. 그 트리거가 UPDATE mims_authorizations ... JOIN contracts를 실행하는데, 로그를 보면 이 문장이 contracts(197084)에 배타락(X락)을 요청합니다(lock_mode X locks rec but not gap). 같은 트랜잭션이 서브쿼리에서 S락으로 잡았던 행을, 트리거 시점에는 X락으로 올려야 한다. 락 승격(lock upgrade)이다.

하나의 upsert가 락을 잡는 순서를 시간순으로 늘어놓으면 이렇습니다.

upsertContractSlot 한 번이 잡는 락 (순서대로)
1. 서브쿼리 SELECT contracts            → S락  contracts(197084)
2. INSERT … ON DUPLICATE KEY UPDATE     → X락  contract_slots(2088501)
3. ODKU가 깨운 트리거의 UPDATE … JOIN    → X락  contracts(197084)   ← 1번의 S락을 X로 승격

핵심은 같은 contracts 행을 1번(S)과 3번(X)에서 두 번 잠그고, 그 사이 2번에서 다른 행(contract_slots)의 X락이 끼어든다는 점입니다. 단독으로 실행될 때는 문제가 없다. 하지만 같은 gcid로 두 세션이 동시에 들어오면, 이 순서가 교착의 조건이 됩니다.

4. 락 순서 역전: 왜 풀리지 않는 교착인가

두 세션 A(327)와 B(328)가 같은 gcid=141431로 동시에 upsert를 호출한 경우를 따라가 봅니다.

세션 A (trx …327)                       세션 B (trx …328)
─────────────────────────────────       ─────────────────────────────────
1. contracts(197084) S락 획득            1. contracts(197084) S락 획득   (S끼리는 공존 OK)
2. contract_slots(2088501) X락 획득      2. contract_slots(2088501) X락 … 대기 (A가 쥠)
3. 트리거: contracts X락 … 대기
   (B가 같은 행에 S락을 쥐고 있어
    S→X 승격 불가)
        └──────────── 서로 물림 → 교착 ────────────┘

핵심은 S락은 공존하지만 X락 승격은 다른 세션의 S락이 남아 있으면 진행되지 못한다는 점입니다.

A와 B 둘 다 서브쿼리로 같은 contracts 행을 읽으므로, S락을 함께 쥔다.
contract_slots 행의 X락은 한 세션만 가질 수 있으므로, 먼저 도착한 A가 가져간다. B는 여기서 대기한다.
A는 트리거를 실행하려고 contracts를 S에서 X로 올려야 한다. X로 올리려면 다른 세션이 그 행에 락을 쥐고 있지 않아야 하는데, B가 아직 S락을 쥔 채 2번에서 멈춰 있다. A는 B가 S를 놓기를 기다린다.
그러나 B는 A가 쥔 contract_slots X락을 기다리는 중이라 전진하지 못하고, S락도 놓지 못한다.

A는 B를 기다리고, B는 A를 기다립니다. 어느 쪽도 진행할 수 없으므로 InnoDB가 데드락으로 판정하고 A(327)를 롤백시킵니다. 환경에 따라 간헐적으로 발생하는 것이 아니라, 같은 gcid로 요청이 겹치는 순간 구조적으로 발생하는 교착입니다.

5. 해결 방향: 락을 한 방향으로 정렬한다

데드락의 일반적인 해법은 모든 트랜잭션이 자원을 같은 순서로 잠그게 하는 것입니다. 이 사례에서는 "한 INSERT 문이 contracts를 S로 잡았다가 X로 다시 잡는" 두 단계 구조를 없애는 것이 핵심입니다. 후보는 세 가지입니다.

방향	무엇을 바꾸나	트레이드오프
① 서브쿼리를 INSERT 밖으로	`contract_id`를 먼저 조회(또는 호출부에서 주입)하고, INSERT엔 확정된 값만 넣는다	쓰기 문장이 `contracts`에 S락을 들고 있지 않게 되어, 락은 트리거의 X락 한 번뿐. 왕복(round-trip) 한 번 추가
② 처음부터 X로 잠그기	서브쿼리 조회를 `SELECT … FOR UPDATE`로 바꿔, 양쪽이 `contracts`를 X락으로 먼저 잡고 줄 서게 한다	S→X 승격이 사라져 교착 해소. 대신 `contracts` 접근이 직렬화되어 동시성 저하
③ 트리거를 걷어내기	`mims_authorizations` 갱신을 DB 트리거가 아니라 애플리케이션 트랜잭션 코드로 옮긴다	숨은 락(트리거의 X락)이 사라져 흐름이 명시적이 됨. 트리거에 기대던 다른 경로까지 함께 점검해야 함

①과 ②는 락을 한 번만, 한 방향으로 잡게 만들어 순환 자체를 끊습니다. ③은 여기에 더해 "쿼리만 봐서는 드러나지 않던 트리거의 락"을 제거합니다. 세 방향 모두 "같은 행을 한 트랜잭션 안에서 S→X로 두 번 잠그지 않는다"는 원칙으로 수렴합니다.

6. 마무리

이번 분석에서 얻은 교훈을 정리합니다.

데드락 로그는 추측이 아니라 증거다. LATEST DETECTED DEADLOCK의 WAITING FOR / CONFLICTING WITH를 읽으면 누가 무엇을 쥐고 무엇을 기다리는지가 드러납니다. 락 모드(S/X)와 레코드 키를 표로 정리하자 순환 대기가 명확해졌습니다.
쿼리에 드러나지 않는 락을 의심하자. 데드락을 만든 mims_authorizations UPDATE는 직접 작성한 문장이 아니었습니다. NEW. 키워드가 트리거를 가리켰고, 그 트리거의 X락이 원인의 절반이었습니다. 트리거·외래키·서브쿼리처럼 자동으로 따라붙는 락은 SQL 텍스트만 봐서는 드러나지 않습니다.
한 문장이 같은 행을 두 번 잠그면 의심하자. S락(읽기)과 X락(쓰기)을 한 트랜잭션 안에서 같은 행에 순차로 거는 구조는, 동시 요청이 겹치는 순간 락 승격이 막히며 교착으로 이어집니다.

참고: 이 데드락은 환경에 따른 간헐적 버그가 아니라 같은 gcid가 겹치면 재현되는 구조적 문제였습니다. 재현 조건이 명확하면 수정 후 검증도 명확하게 할 수 있습니다.

S락·X락·갭 락·락 승격 — InnoDB 락 정리 노트

Mon, 21 Apr 2025 00:00:00 GMT

운영 DB에서 데드락(deadlock) 로그를 읽다가, lock_mode X locks rec but not gap, lock mode S 같은 표현이 어떤 락을 가리키는지는 알아도 어떤 문장이 왜 그 락을 잡았는지는 바로 설명하기 어려웠습니다. 그래서 데드락 추적에 앞서 락부터 정리했습니다.

이 글은 그 정리 노트입니다. InnoDB가 행을 어떻게 잠그는지 따라가며, 다음 편에서 다룰 데드락의 배경을 먼저 정리합니다. (개념 설명은 MySQL 공식 문서의 InnoDB Locking을 기준으로 했고, px201226님의 "MySQL 트랜잭션 락" 글을 참고해 구성을 잡았습니다. 갭 락과 삽입 의도 락 부분은 당근 기술블로그의 "MySQL Gap Lock 다시보기"·"두 번째 이야기"에서 실사례를 빌렸습니다. MariaDB의 InnoDB도 같은 락 모델을 따릅니다.)

1. 두 개의 기본 락: 공유락(S)과 배타락(X)

InnoDB의 행 락은 두 종류에서 출발합니다.

공유락(Shared Lock, S): 읽기를 위한 락. 여러 트랜잭션이 같은 행에 동시에 S락을 쥘 수 있습니다. 단, 그 행을 바꾸려는 배타락은 막습니다. SELECT ... FOR SHARE(과거 LOCK IN SHARE MODE)로 명시적으로 걸 수 있습니다.
배타락(Exclusive Lock, X): 쓰기를 위한 락. 한 트랜잭션만 쥘 수 있고, 다른 어떤 락(S든 X든)과도 공존하지 못합니다. SELECT ... FOR UPDATE나 UPDATE/DELETE가 이 락을 겁니다.

정리하면 S락끼리는 공존하고, X락은 단독으로만 잡힙니다. 이 규칙이 뒤에 나올 데드락의 절반을 설명합니다.

보유 ↓ \ 요청 →	S	X
S	✓ 공존	✗ 대기
X	✗ 대기	✗ 대기

여기서 한 가지를 미리 짚어 둡니다. 이미 S락을 쥔 행을 같은 트랜잭션이 X락으로 올리는 것(락 승격, lock upgrade)은, 그 사이 다른 트랜잭션도 같은 행에 S락을 쥐고 있으면 성공하지 못합니다. S락은 공존하지만, X로의 승격은 다른 락이 모두 풀려 있어야 하기 때문입니다.

2. 행을 잠그기 전에 손드는 락: 의도락(Intention Lock)

InnoDB는 테이블 락과 행 락을 함께 씁니다(다중 세분성 잠금, multiple granularity locking). 그런데 누군가 테이블 전체에 락을 걸려 할 때, "이 테이블 안 어딘가의 행에 락이 걸려 있나?"를 행을 일일이 훑어 확인하면 느립니다. 그래서 행 락을 걸기 전에, 테이블 레벨에 "나 이 테이블의 어떤 행을 잠글 거야"라는 깃발을 먼저 꽂습니다. 이게 의도락(Intention Lock)입니다.

IS(Intention Shared): 행에 S락을 걸 의도. (SELECT ... FOR SHARE)
IX(Intention Exclusive): 행에 X락을 걸 의도. (SELECT ... FOR UPDATE, UPDATE, INSERT 등)

의도락끼리는 대부분 호환됩니다. 둘 다 "행 단위로 락을 걸 예정"이라는 표시일 뿐이고, 실제 충돌은 행 레벨에서 가려지기 때문입니다. 공식 문서의 호환성 매트릭스는 다음과 같습니다.

	X	IX	S	IS
X	✗	✗	✗	✗
IX	✗	✓	✗	✓
S	✗	✗	✓	✓
IS	✗	✓	✓	✓

표에서 보이듯, 테이블 레벨 X락만 모든 것을 막습니다. 평소 우리가 만나는 데드락은 의도락이 아니라 행 레벨의 S/X에서 벌어지니, 의도락은 "이런 계층이 있다" 정도로만 알아두면 충분합니다.

3. InnoDB가 행을 잠그는 세 가지 방식: 레코드 / 갭 / 넥스트키 락

InnoDB의 행 락은 사실 "행"이 아니라 인덱스 레코드를 잠급니다. 잠그는 범위에 따라 셋으로 나뉩니다.

락	잠그는 대상	`performance_schema` 표기
레코드 락(Record Lock)	인덱스 레코드 하나	`X,REC_NOT_GAP` / `S,REC_NOT_GAP`
갭 락(Gap Lock)	레코드와 레코드 사이의 빈 구간	`X,GAP` / `S,GAP`
넥스트키 락(Next-Key Lock)	레코드 + 그 앞 갭	(기본 표기)

갭 락은 값을 잠그는 게 아니라 그 구간에 새 행이 끼어드는 것(INSERT)을 막는 락입니다. 같은 조건으로 두 번 읽었을 때 없던 행이 생기는 팬텀 리드(phantom read)를 막기 위한 장치입니다. 넥스트키 락은 레코드 락과 갭 락을 합친 것으로, REPEATABLE READ에서 범위 조건을 다룰 때 기본으로 쓰입니다.

갭 락이 언제 붙는지는 인덱스 종류를 탑니다.

기본키·유니크 인덱스 + 동등 조건(=)으로 정확히 1건: 레코드 락만. 갭은 안 잠급니다.
존재하지 않는 값 조회, 범위 조건, 또는 보조 인덱스(secondary index): 레코드 락 + 갭 락이 함께 붙습니다. 특히 보조 인덱스 동등 조회는 거의 항상 갭까지 잠그기 때문에, 한 건만 건드린 것처럼 보여도 인접 구간의 INSERT가 막힐 수 있습니다.

여기에 갭과 짝을 이루는 락이 하나 더 있습니다. 삽입 의도 락(INSERT Intention Lock)입니다. INSERT가 어떤 갭에 행을 넣기 직전 그 갭에 거는 특수한 갭 락이며, 다음 성질이 중요합니다.

갭 락끼리는 서로 호환됩니다. 여러 트랜잭션이 같은 갭에 갭 락을 함께 쥘 수 있습니다.
하지만 갭 락과 삽입 의도 락은 충돌합니다. 누군가 갭을 잠가두면, 그 갭에 INSERT 하려는 트랜잭션은 대기합니다.

이 "갭 락은 공존하지만 삽입 의도 락과는 비호환"이라는 비대칭이 6절의 또 다른 데드락 패턴을 만듭니다.

참고: 2편의 데드락 로그에는 locks rec but not gap이 등장합니다. 갭은 잠그지 않고 레코드 하나만 잠근, 위 표의 "레코드 락"입니다. 즉 2편의 교착은 갭 락이 아니라 레코드 락 + S→X 승격이 원인이며, 지금 설명한 갭 락은 그것과 별개의 데드락 갈래입니다.

4. 격리 수준이 락을 바꾼다 — 기본은 REPEATABLE READ

같은 SQL이라도 트랜잭션 격리 수준(isolation level)에 따라 잡는 락이 달라집니다. MySQL·MariaDB의 기본값은 REPEATABLE READ(RR)입니다.

일반 SELECT는 락을 안 건다. RR에서 평범한 조회는 MVCC(다중 버전 동시성 제어)로 스냅샷을 읽기 때문에, 락 없이도 일관된 결과를 봅니다.
하지만 쓰기는 다르다. UPDATE, DELETE, 그리고 다른 테이블을 읽어 값을 넣는 INSERT ... SELECT는 MVCC로 처리되지 않고 실제 락을 잡습니다. RR이라도 MVCC는 읽기 동시성을 위한 것이며, 쓰기에는 적용되지 않습니다.

READ COMMITTED(RC)로 낮추면 갭 락을 거의 쓰지 않아 잠금 범위가 좁아지지만, 일관성 보장도 함께 약해집니다. 이 글과 2편의 내용은 모두 기본값 RR을 전제로 합니다.

5. 무슨 문장이 어떤 락을 잡나

이번 노트의 핵심 표입니다. 기본 격리 수준(RR) 기준으로, 자주 쓰는 문장이 거는 락을 정리했습니다.

문장	거는 락
일반 `SELECT`	없음 (MVCC 스냅샷 읽기)
`SELECT ... FOR SHARE`	읽은 행에 S락 (+ IS)
`SELECT ... FOR UPDATE`	읽은 행에 X락 (+ IX)
`UPDATE ... WHERE`	조건 범위에 넥스트키 락, 실제 수정 행에 X락
단순 `INSERT`	삽입 행에 X락
`INSERT ... SELECT`	읽어온 원본 행에 S락 + 삽입 행에 X락
`INSERT ... ON DUPLICATE KEY UPDATE`	중복키 감지 시 먼저 S락 → 갱신하며 X락

마지막 두 줄이 2편 데드락의 두 축입니다.

INSERT ... SELECT(또는 INSERT의 VALUES 안 서브쿼리): 값을 읽어온 원본 행에 S락이 걸립니다. 읽기만 한 것처럼 보여도, 그 값으로 다른 곳에 쓰는 이상 일관성을 지키기 위해 InnoDB가 S락을 잡습니다.
ON DUPLICATE KEY UPDATE: 중복키를 만나면 그 인덱스 레코드에 먼저 S락을 잡아 확인하고, 갱신을 진행하며 X락으로 올립니다. 여기에 락 승격(S→X)이 들어 있습니다.

6. 데드락이 만들어지는 과정

데드락은 둘 이상의 트랜잭션이 서로가 쥔 락을 맞물려 기다리는 순환 대기(circular wait)입니다. 실무에서 마주치는 형태는 크게 셋입니다.

패턴 A — 락 순서 역전. 가장 고전적인 형태입니다.

trx-1:  id=1 X락 획득 → id=2 X락 대기
trx-2:  id=2 X락 획득 → id=1 X락 대기
        └──────── 서로 물림 → 교착 ────────┘

두 트랜잭션이 같은 자원들을 반대 순서로 잠그면 발생합니다. 해결책은 모든 트랜잭션이 같은 순서로 잠그도록 맞추는 것입니다.

패턴 B — S→X 승격 경쟁. 1절에서 짚어 둔 락 승격이 여기서 문제가 됩니다.

trx-1, trx-2:  같은 행에 S락을 함께 획득   (S끼리는 공존 OK)
trx-1:  그 행을 X로 승격하려 함 → trx-2의 S락 때문에 대기
trx-2:  그 행을 X로 승격하려 함 → trx-1의 S락 때문에 대기
        └──────── 둘 다 못 올라감 → 교착 ────────┘

INSERT ... ON DUPLICATE KEY UPDATE처럼 S락을 먼저 잡고 X로 올리는 문장을 두 세션이 같은 키로 동시에 실행하면 이 패턴에 빠집니다.

패턴 C — 갭 락과 삽입 의도 락의 충돌. 3절의 비대칭("갭 락끼리는 공존, 삽입 의도 락과는 비호환")이 여기서 작용합니다.

세션1: SELECT ... FOR UPDATE (없는 id=2) → 갭 락 획득
세션2: SELECT ... FOR UPDATE (없는 id=2) → 갭 락 획득   (갭 락끼리는 공존 OK)
세션1: INSERT id=2 → 삽입 의도 락 필요, 세션2의 갭 락과 충돌 → 대기
세션2: INSERT id=2 → 삽입 의도 락 필요, 세션1의 갭 락과 충돌 → 대기
        └──────── 서로 물림 → 교착 ────────┘

존재하지 않는 값 조회·범위 조건·보조 인덱스가 갭 락을 만들고, 거기에 두 세션이 같은 갭으로 INSERT를 시도하면 교착이 됩니다. 큐(queue)처럼 쓰는 테이블이나 빈 테이블(갭이 테이블 전체로 넓어집니다)에서 특히 자주 나타납니다. 해결책은 격리 수준을 READ COMMITTED로 낮춰 갭 락을 없애거나, 범위 조회(BETWEEN)를 기본키 동등 조회(IN (...))로 바꾸거나, 선택도 높은 인덱스를 더해 잠금 범위를 좁히는 것입니다. (당근 기술블로그의 두 글이 이 패턴과, 페이지 끝의 supremum 갭까지 다룹니다 — 위 참고 링크.)

참고: 패턴 B와 C는 둘 다 공존하던 약한 락(S락 / 갭 락)을 더 강한 락(X락 / 삽입 의도 락)으로 올리는 시점에서 막힌다는 공통점이 있습니다. 여럿이 함께 쥐던 락을 동시에 독점하려는 순간이 교착의 전형적인 구도입니다.

교착이 감지되면 InnoDB는 가장 가벼운 트랜잭션 하나를 골라 롤백합니다. "가벼움"은 information_schema.INNODB_TRX의 trx_weight(변경·잠근 행 수 등을 반영한 값)로 판단합니다. 살아남은 쪽은 정상 진행하므로, 애플리케이션은 데드락(에러 코드 1213)을 만나면 재시도하도록 작성하는 것이 일반적입니다.

7. 마무리 — 2편으로

여기까지가 데드락 로그를 읽기 위한 최소한의 어휘입니다. 정리하면,

S락은 공존하고 X락은 독점한다. 그리고 S→X 승격은 다른 S락이 남아 있으면 막힌다.
행 락은 인덱스 레코드를 잠그며, 레코드 / 갭 / 넥스트키로 범위가 나뉜다.
기본 격리 수준 RR에서 일반 SELECT는 락이 없지만, 쓰기와 INSERT ... SELECT는 락을 잡는다.
INSERT ... SELECT는 원본 행에 S락, ON DUPLICATE KEY UPDATE는 중복키에 S락 → X락 승격.
데드락은 락 순서 역전(패턴 A), S→X 승격 경쟁(패턴 B), 갭 락↔삽입 의도 락 충돌(패턴 C)에서 발생한다.

이 요소들이 실제로 어떻게 맞물리는지를, 다음 편에서 운영 DB에 기록된 데드락 로그로 추적합니다. 평범해 보이는 upsert 쿼리 하나가 위 패턴 B를 그대로 재현한 사례입니다. → 2편: INSERT 한 번에 데드락이?에서 이어가겠습니다.

openjdk:21-slim 운영 환경에서 엑셀 다운로드 시 UnsatisfiedLinkError가 난 원인

Wed, 22 Jan 2025 00:00:00 GMT

대용량 처리를 위해 엑셀 파일 생성 구현체를 변경했습니다. 로컬과 DEV 환경에서 검증을 마치고 운영 서버에 배포했는데, 운영 환경의 엑셀 다운로드 API에서 에러가 발생했습니다.

1. 현상 분석: 스프링 예외로 감싸인 네이티브 에러

로그에서 가장 먼저 확인한 것은 스프링 MVC의 예외였습니다.

에러 트래킹에 잡힌 UnsatisfiedLinkError

org.springframework.web.util.NestedServletException: Request processing failed;
nested exception is org.springframework.web.handler.HandlerDispatchResolverException:
Handler dispatch failed; nested exception is java.lang.UnsatisfiedLinkError:
/usr/local/openjdk-21/lib/libfontmanager.so: libfreetype.so.6: cannot open shared object file: No such file or directory

로그 상단의 Handler dispatch failed는 Spring MVC에서 요청을 처리(컨트롤러 실행 등)하는 도중 예외가 발생했을 때 DispatcherServlet이 이를 감싸서 던지는 최상위 래퍼(Wrapper) 에러입니다.

이 문구 자체는 "요청 처리 중에 문제가 생겼다"는 범용적인 신호이므로, 원인을 찾으려면 그 안에 중첩된 실제 예외에 집중해야 합니다.

java.lang.UnsatisfiedLinkError

Java 공식 문서에 따르면, 이 예외는 JVM이 적절한 네이티브 언어 정의(Native-language definition)를 찾지 못하거나, 의존하는 네이티브 라이브러리(.so 또는 .dll 파일)를 로드하는 데 실패했을 때 발생합니다.

이번 로그에서는 JVM이 JDK 내부의 libfontmanager.so를 로드하려다, 이 파일이 의존하는 OS 레벨 공유 라이브러리인 libfreetype.so.6를 찾지 못해 발생한 경우였습니다.

2. openjdk:21 vs openjdk:21-slim

로컬 도커 환경도 Java 21이고 운영도 Java 21인데, 왜 로컬에만 해당 파일이 있는지 확인해야 했습니다. 원인은 Dockerfile의 베이스 이미지 태그 차이였습니다.

로컬 개발용 Dockerfile: FROM openjdk:21
운영(Prod)용 Dockerfile: FROM openjdk:21-slim

Debian 공식 패키지 명세를 보면 libfreetype6는 "FreeType 2 font engine, shared library files"로 정의되어 있습니다.

일반 openjdk:21 이미지에는 Linux 표준 폰트 엔진과 기본 OS 패키지가 포함되어 있는 반면, -slim 버전은 컨테이너 용량을 줄이기 위해 자바 실행에 필요한 최소 패키지만 남기고 폰트 엔진 관련 파일을 제거합니다.

3. 원인: SXSSFWorkbook이 시트 생성 시 폰트를 참조한다

이번에 변경된 코드는 한 줄이었습니다. 엑셀 생성 워크북 구현체를 기존 XSSFWorkbook에서 스트리밍 방식인 SXSSFWorkbook으로 바꾼 것입니다.

// AS-IS
Workbook workbook = new XSSFWorkbook();

// TO-BE
SXSSFWorkbook workbook = new SXSSFWorkbook();

코드 어디에도 폰트 스타일을 지정하는 로직은 없습니다. 컬럼 너비를 자동 계산하는 autoSizeColumn()도 사용하지 않았고, 셀에 값만 넣고 write()를 호출할 뿐입니다. 폰트를 직접 다루지 않는데도 폰트 라이브러리를 로드하다 실패한 이유는 SXSSFWorkbook이 시트를 생성하는 순간 내부적으로 기본 폰트를 참조하기 때문입니다. Apache POI 소스 코드를 따라가 보면 이 흐름을 확인할 수 있습니다.

SXSSFSheet는 생성자에서 무조건 AutoSizeColumnTracker를 생성합니다. 스트리밍 방식 특성상 행을 디스크로 흘려보내면서 컬럼 너비를 실시간으로 추적해야 하기 때문입니다.

// org.apache.poi.xssf.streaming.SXSSFSheet
public SXSSFSheet(SXSSFWorkbook workbook, XSSFSheet xSheet) throws IOException {
    ...
    _autoSizeColumnTracker = new AutoSizeColumnTracker(this); // ← 시트 생성 시 무조건 실행
}

그리고 이 AutoSizeColumnTracker 생성자는 내부적으로 기본 폰트의 글자 너비를 미리 계산해 둡니다.

// org.apache.poi.xssf.streaming.AutoSizeColumnTracker
public AutoSizeColumnTracker(final Sheet sheet) {
    defaultCharWidth = SheetUtil.getDefaultCharWidthAsFloat(sheet.getWorkbook());
}

이 getDefaultCharWidthAsFloat()가 바로 자바 그래픽 런타임(AWT)을 이용해 글자 폭을 재는 지점입니다. 텍스트를 가상으로 렌더링하여 픽셀 폭을 구하기 위해 TextLayout과 FontRenderContext를 사용하고, 이 과정에서 JDK 내부 폰트 네이티브 라이브러리(libfontmanager.so)를 로드하게 됩니다.

// org.apache.poi.ss.util.SheetUtil
public static float getDefaultCharWidthAsFloat(final Workbook wb) {
    Font defaultFont = wb.getFontAt(0);
    ...
    TextLayout layout = new TextLayout(str.getIterator(), fontRenderContext); // ← AWT 폰트 렌더링 발생!
    return layout.getAdvance();
}

즉 autoSizeColumn()을 직접 호출하지 않더라도, SXSSFWorkbook.createSheet()를 호출하는 순간 폰트 관련 네이티브 코드가 실행됩니다. 전체 장애 흐름을 요약하면 다음과 같습니다.

# ── 호출이 안으로 파고드는 단계 (call stack ↓) ──
1. 엑셀 다운로드 API 호출
2. └ new SXSSFWorkbook().createSheet()
3.   └ SXSSFSheet 생성자가 new AutoSizeColumnTracker(this) 실행
4.     └ AutoSizeColumnTracker → SheetUtil.getDefaultCharWidthAsFloat(workbook)
5.       └ 기본 폰트 글자 폭 측정 위해 AWT 폰트 렌더링(TextLayout / FontRenderContext) 작동
6.         └ JDK libfontmanager.so 로딩 시도 → 의존하는 libfreetype.so.6 호출
7.           ✗ 운영은 openjdk:21-slim 이라 libfreetype.so.6 파일이 없음!

# ── 에러가 밖으로 전파되는 단계 (call stack ↑) ──
8.         ↑ java.lang.UnsatisfiedLinkError 발생 → 호출 스택을 타고 위로 전파
9. ↑ Spring DispatcherServlet이 Handler dispatch failed로 감싸서 응답

XSSF는 왜 멀쩡했을까?

기존에 사용하던 XSSFSheet는 이 AutoSizeColumnTracker를 미리 생성하지 않습니다. autoSizeColumn()을 직접 호출하지 않는 한 폰트 코드가 실행되지 않습니다. 반면 SXSSFSheet는 시트를 만드는 순간 추적기를 생성하면서 폰트를 참조합니다.

동일한 코드(문자열 셀만 채우고 write)를 워크북 구현체만 바꿔서 실행하면 차이가 드러납니다. 다음은 -verbose:class 옵션으로 sun.font.* 클래스 로딩 횟수를 측정한 결과입니다.

워크북 구현체	`sun.font.*` 클래스 로드 횟수	slim 이미지에서의 동작 여부
`XSSFWorkbook`	0회 (폰트를 건드리지 않음)	정상 작동
`SXSSFWorkbook`	82회 (`FontManagerNativeLibrary` 포함)	네이티브 라이브러리 로드 실패로 `UnsatisfiedLinkError`

이는 데이터의 행 수와도 무관합니다. 데이터가 10행이든 0행이든, 시트를 생성하는 순간 발생합니다.

참고: Apache POI에는 이 상황을 대비한 방어 코드가 있습니다. SXSSFSheet 생성자는 UnsatisfiedLinkError를 catch하지만, 에러 메시지에 X11FontManager가 포함된 경우(과거 리눅스 X11 환경)에만 예외를 무시하고 넘어갑니다. 이번 에러는 메시지가 libfontmanager.so: libfreetype.so.6... 형태였기 때문에 조건에 맞지 않아 예외가 그대로 전파되었습니다.

4. 도커 이미지별 네이티브 라이브러리 특징 비교

도커는 호스트의 커널을 공유할 뿐, 베이스 이미지 내부의 '파일 시스템'을 패키징합니다. 따라서 베이스 이미지를 어떤 것으로 고르느냐에 따라 포함된 네이티브 파일 구성이 완전히 달라집니다. 흔히 쓰이는 자바 베이스 이미지들의 특징을 정리해 보았습니다.

이미지 접미사 (Variant)	기반 OS (Base OS)	특징 및 네이티브 라이브러리 구성
default (기본형)	Ubuntu / Debian 계열	기본적인 패키지, glibc, 폰트 및 그래픽 라이브러리가 풍부하게 포함되어 있어 무겁지만 안정적임.
`-slim`	Debian 계열 (경량화)	용량을 줄이기 위해 `fontconfig`, `freetype` 등 다수의 OS 패키지가 제거됨. (이번 장애의 원인)
`-alpine`	Alpine Linux	극단적인 경량화 이미지. 단, 표준 `glibc` 대신 `musl libc`를 사용하여 일부 네이티브 라이브러리와 호환성 문제가 생길 수 있음.
distroless	최소한의 런타임	패키지 매니저(`apt`, `apk`)나 Shell조차 없음. 애플리케이션 실행을 위한 최소 파일만 존재하여 보안성과 경량성이 매우 높음.

5. 마무리: dev, stage, prod 환경은 최대한 같게 맞추자

이번 장애의 원인은 코드 버그가 아니라 실행 환경의 차이였습니다. 로컬·DEV는 openjdk:21(full), 운영은 openjdk:21-slim을 사용했고, 같은 자바 코드라도 그 아래의 OS 라이브러리 구성이 달랐기 때문에 사전 검증을 통과한 변경이 운영에서만 실패했습니다.

베이스 이미지를 통일한다. 운영을 -slim으로 최적화하기로 했다면, dev와 stage도 같은 -slim 이미지를 쓰는 게 맞습니다. 그래야 이번 같은 OS 의존성 문제가 운영까지 가기 전에 로컬/스테이지에서 먼저 드러납니다.
환경 차이를 줄이면 검증의 신뢰도가 올라간다. "로컬에서 통과했다"는 말이 "운영에서도 통과한다"와 같은 의미가 되려면, 두 환경이 충분히 닮아 있어야 합니다.

자바 애플리케이션이 플랫폼 독립적으로 보여도, Apache POI의 폰트 렌더링처럼 OS 네이티브 라이브러리에 의존하는 부분은 환경 차이에 그대로 노출됩니다. 그 차이를 가장 확실하게 없애는 방법은 검증하는 환경과 배포하는 환경을 같게 만드는 것입니다.

핵사고날 아키텍처로 파이썬 레거시 DB 격리하기 (with. ArchUnit Test)

Thu, 26 Dec 2024 00:00:00 GMT

핵사고날 아키텍처(Hexagonal Architecture)를 사용하는 프로젝트에 합류했습니다. 합류 초기에는 이 아키텍처를 도입한 이유를 파악하지 못한 상태였습니다.

포트(Port) 하나, 어댑터(Adapter) 하나, 그 사이를 잇는 매퍼(Mapper)까지. 기능 하나를 추가할 때마다 비슷한 파일이 서너 개씩 늘어났습니다. 이 정도 복잡도에 레이어마다 의존성을 이렇게까지 끊어낼 필요가 있는지 저는 의문이었습니다.

1. 의문의 시작: 너무 많은 보일러플레이트

핵사고날의 핵심은 의존성 역전입니다. 도메인(Domain)은 바깥(DB·웹·외부 API)을 모르고, 바깥이 도메인을 향하도록 의존 방향을 뒤집습니다. 그 방향을 뒤집기 위한 장치가 포트와 어댑터입니다. (잘 정리된 자료가 많은 주제라 간단하게만 언급하고 넘어가겠습니다)

문제는 이 패턴이 기능 단위로 그대로 복제된다는 점이었습니다. 단순히 테이블 하나를 읽어서 내려주는 조회 API에도 관습적으로 같은 구조가 따라붙었습니다.

application/
  port/out/    FooReader (interface)         ← 포트
domain/
  Foo                                         ← 도메인 모델
adapter/out/
  FooJpaEntity                                ← JPA 엔티티
  FooPersistenceAdapter (implements FooReader)← 어댑터
  FooMapper (Foo ↔ FooJpaEntity)              ← 매퍼

도메인 모델 Foo와 JPA 엔티티 FooJpaEntity가 거의 똑같은 필드를 가지고, 그 둘을 변환하는 매퍼가 또 한 벌 필요했습니다. 필드 하나를 추가할 때 다섯 개의 파일을 손대야 하는 구조였습니다.

같은 의문을 가진 팀원이 있어 백엔드 미팅에서 안건을 올렸습니다. 도메인의 복잡도에 비해 핵사고날을 유지하는 비용이 과한 것은 아닌지가 주제였습니다.

2. 핵사고날을 쓴 진짜 이유: 파이썬 레거시 DB 격리

팀과 논의를 거치며 이 아키텍처를 도입한 목적을 확인했습니다.

이 서비스의 DB는 원래 파이썬으로 운영되던 레거시 시스템의 것이었습니다. 시스템을 자바로 전환하면서 기존 테이블들을 그대로 사용해야 했는데, 레거시 스키마를 자바나 JPA로 직접 핸들링하면 DB 구조에 의존적인 클래스가 만들어졌습니다.

테이블의 각 컬럼의 생명주기가 다름
한 테이블에 여러 책임이 섞여 있거나, 반대로 불필요하게 흩어져 있는 구조
"이 모델을 도메인 객체로 그대로 쓰면, 도메인이 레거시 DB 구조에 종속된다"는 문제

그래서 선택한 방법이 도메인 엔티티(Domain Entity)와 JPA 엔티티(JPA Entity)를 분리하는 추상화였습니다. 레거시 테이블의 생김새는 JpaEntity가 온전히 떠안고, 도메인은 어댑터 너머에서 자바답게 설계한 모델로만 세상을 바라보게 한 것입니다.

즉, 포트-어댑터(Port-Adapter) 패턴은 레거시 DB를 격리하기 위한 장치였습니다. 처음부터 프로젝트 전체를 핵사고날로 채우려던 것이 아니라, 레거시와 맞닿는 일부 영역에서만 이 패턴을 차용한 구조였습니다.

이 분리가 주는 실질적인 효과는 리팩터링 시점에 드러납니다. 도메인은 JPA 엔티티가 아니라 포트(FooReader 같은 인터페이스)에만 의존합니다. 덕분에 훗날 레거시 테이블을 걷어내고 새 스키마로 옮기더라도, 비즈니스 로직은 한 줄도 건드리지 않은 채 DB 레이어(어댑터)만 교체하면 됩니다. 도메인은 JpaEntity의 구조를 모르기 때문에, 교체의 영향이 어댑터 안쪽에서 멈춥니다.

구분	레거시 영역	(이상적인) 신규 영역
DB 스키마	파이썬 시절 그대로, 변경 권한 제약	자바 도메인에 맞춰 새로 설계 가능
모델	도메인 ↔ JPA 분리 필요	굳이 분리할 이유 없음
패턴	포트-어댑터로 격리	격리할 대상 자체가 없음
비용	보일러플레이트를 감수할 명분 있음	같은 비용을 치를 명분 없음

합류 초기의 저는 비용만 보고, 이 선택에 이르기까지의 배경은 파악하지 못한 상태였습니다.

3. 그렇다면 신규 기능은? — 레이어드로 충분하다

여기서 자연스럽게 따라오는 판단은, 격리할 레거시가 없는 신규 기능까지 같은 비용을 낼 이유는 없다는 점입니다.

신규 API는 출발점부터 다릅니다. DB 모델부터 직접 설계하기 때문입니다. 도메인에 맞는 스키마를 직접 설계할 수 있으니, 도메인 엔티티와 JPA 엔티티가 어긋날 일도 거의 없습니다. 둘을 분리하고 매퍼로 잇는 비용이 그것으로 막을 수 있는 위험보다 큽니다.

그래서 앞으로의 방향을 다음과 같이 정했습니다.

레거시와 엮인 기존 기능: 기존처럼 핵사고날(포트-어댑터) 구조를 유지해 레거시를 계속 격리한다.
신규 기능: Controller → Service → Repository로 이어지는 레이어드 아키텍처(Layered Architecture)로 단순하게 접근한다.

문제는 한 코드베이스 안에 두 아키텍처가 공존하게 되었다는 점입니다. 아키텍처 규칙은 문서에만 적어두면 시간이 지날수록 지켜지지 않습니다. 레이어드로 정한 신규 모듈에서 컨트롤러가 레포지토리를 직접 호출하거나, 리팩터링 도중 서비스가 컨트롤러를 역참조하는 일이 코드 리뷰에서 누락될 수 있습니다.

이러한 균열을 사람의 코드 리뷰에만 의존해서 막는 데는 한계가 있습니다. 그래서 이 경계를 자동화된 테스트로 검증하기로 했습니다. 이때 도입한 도구가 ArchUnit입니다.

4. 경계를 테스트로 박는다: ArchUnit

ArchUnit은 아키텍처 규칙을 일반 테스트 코드처럼 작성하여 CI에서 검증할 수 있게 도와주는 라이브러리입니다. "패키지 A는 패키지 B를 참조해서는 안 된다"와 같은 규칙을 JUnit 테스트로 표현할 수 있으며, 규칙을 위반하면 테스트가 실패합니다.

4-1. 신규 모듈의 레이어 방향 강제

신규 서비스에 한해, 레이어가 단방향으로만 흐르도록 규칙을 세웠습니다. (패키지명은 예시입니다)

@AnalyzeClasses(packages = "net.mgrv.apis.newfeature")
class LayeredArchitectureTest {

    @ArchTest
    static final ArchRule 레이어_의존성은_한_방향으로만_흐른다 =
        layeredArchitecture()
            .consideringOnlyDependenciesInLayers()
            .layer("Controller").definedBy("..controller..")
            .layer("Service").definedBy("..service..")
            .layer("Repository").definedBy("..repository..")

            .whereLayer("Controller").mayNotBeAccessedByAnyLayer()           // 아무도 컨트롤러를 의존하지 않는다
            .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")   // 서비스는 컨트롤러만 부른다
            .whereLayer("Repository").mayOnlyBeAccessedByLayers("Service");  // 레포지토리는 서비스만 부른다
    }

이제 누군가 컨트롤러에서 레포지토리를 직접 호출하면, 코드 리뷰어들이 놓치더라도 CI에서 인지할 수 있습니다.

4-2. 레거시와 공존하기 — 점진적 적용과 Freeze

여기서 한 가지 분명히 해둘 점이 있습니다. ArchUnit으로 격리하려는 건 레거시와 신규 사이의 의존 방향이 아닙니다. 신규가 레거시에 쌓인 데이터를 읽어야 할 때도 있고, 반대로 레거시가 신규 기능을 불러 써야 할 때도 있습니다. 둘이 서로를 참조하는 것 자체는 막지 않습니다.

대신 격리하는 건 '규칙을 어디에, 얼마나 빠르게 적용하느냐' 입니다. 4-1의 레이어드 규칙을 신규 모듈에만 적용하면 신규는 깨끗하게 출발합니다. 하지만 같은 규칙을 레거시까지 넓히면, 레거시 내부에 이미 쌓여 있던 수백 개의 위반이 한꺼번에 드러납니다. 그렇다고 규칙을 꺼두면 레거시는 계속 방치됩니다.

이 딜레마를 해결하는 도구가 FreezingArchRule입니다.

@ArchTest
static final ArchRule 레이어_규칙을_레거시까지_점진적으로_적용한다 =
    FreezingArchRule.freeze(
        layeredArchitecture()
            .consideringOnlyDependenciesInLayers()
            .layer("Controller").definedBy("..controller..")
            .layer("Service").definedBy("..service..")
            .layer("Repository").definedBy("..repository..")
            .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
            .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
            .whereLayer("Repository").mayOnlyBeAccessedByLayers("Service")
    );  // 레거시의 기존 위반은 baseline에 기록하고, 새로 생기는 위반만 실패시킨다

freeze()는 현재 존재하는 위반 사항들을 기준선(baseline)으로 기록해 두고, 그 이후에 새롭게 추가되는 위반에 대해서만 테스트를 실패시킵니다. 기존의 기술 부채는 인정하되, 부채가 더 늘어나는 것만 확실히 막는 방식입니다.

제가 적용한 '격리(Isolation)'는 이런 의미였습니다. 레거시를 당장 완벽하게 고치는 게 아니라, 레거시에 이미 쌓인 위반은 baseline에 묶어 더는 늘어나지 않게 동결하고, 신규 코드만큼은 규칙을 지키도록 테스트로 감시하는 것입니다.

규칙	적용 대상	효과
`layeredArchitecture()`	신규 모듈	레이어 의존 방향(Controller→Service→Repository)을 강제
`FreezingArchRule.freeze()`	레거시 포함 전체	기존 위반은 baseline으로 동결, 새로 생긴 위반만 실패

5. 마무리

처음에 핵사고날 구조를 보고 복잡도에 비해 과하다고 느꼈던 이유는, 그 아키텍처가 해결하려던 문제를 제가 제대로 이해하지 못했기 때문이었습니다. 핵사고날의 목적은 구조를 깔끔하게 그리는 것이 아니라 파이썬 레거시 DB를 격리하는 것이었고, 그 목적이 존재하는 곳에서는 보일러플레이트도 필요한 요소였습니다.

반대로, 그러한 목적이 없는 신규 기능에까지 같은 패턴을 관습적으로 복제하는 것은 적절하지 않았습니다. 격리해야 할 레거시 자체가 없기 때문입니다.

목적을 모르는 패턴은 비용만 보이고 명분은 보이지 않습니다. 핵사고날이든 레이어드든, 먼저 던져야 할 질문은 "이 아키텍처가 지금 어떤 문제를 풀고 있는가"입니다.
한 레포지토리에 두 아키텍처가 공존할 수 있습니다. 레거시는 핵사고날로 격리하고, 신규 기능은 레이어드로 단순하게 가져갑니다. 각자 해결하려는 문제가 다르기 때문입니다.
단, 그 경계는 사람이 아니라 테스트가 지키게 해야 합니다. 구두 약속과 컨벤션 문서는 쉽게 무너집니다. ArchUnit은 그 경계를 테스트로 검증하게 해 줍니다.

녹차 주도 개발 시작

Sun, 01 Sep 2024 00:00:00 GMT

시작

녹차 한 잔과 함께.