[트러블슈팅] 외부 API 호출과 DB 반영의 트랜잭션 경계 분리

외부 API 호출과 DB 반영의 트랜잭션 경계 분리

요약
마일스톤 기반 크라우드펀딩 서비스에서 OpenAI를 이용한 AI 검증을 비동기로 처리했습니다. 검증 요청 자체는 사용자 요청과 분리되어 있었지만, 비동기 작업 내부에서는 OpenAI API 호출과 결과 저장이 하나의 DB 트랜잭션에 포함되어 있었습니다.

외부 API 응답을 기다리는 동안에도 JDBC 커넥션이 점유되는 구조였고, 10초 지연 환경에서 동시 DB 조회가 3,005ms 후 실패하는 것을 확인했습니다. 외부 API 호출과 DB 작업의 트랜잭션 경계를 분리한 뒤에는 동일한 조건에서 커넥션이 풀에 반환됐고 동시 DB 조회도 8ms 만에 정상 처리됐습니다.

 

목차

1. 배경
2. 문제
3. 해결
4. 결과
5. 남은 한계
6. 정리

 

1. 배경

아이디어 제안자와 전문가, 스폰서를 연결하는 마일스톤 기반 크라우드펀딩 서비스를 팀 프로젝트로 개발했습니다. 아이디어가 공개되기 전에 AI가 과대광고 표현, 유사 서비스 존재 여부, 마일스톤 구체성 등을 검증하고, 결과를 신뢰도 점수와 후속 전문가 심사에 반영하는 기능을 구현했습니다.

 

OpenAI API는 응답 시간이 일정하지 않기 때문에 외부 API 지연이 아이디어 등록 요청에 직접 영향을 주지 않도록 했습니다. 검증 요청과 상태를 DB에 저장한 뒤 사용자에게 응답하고, 실제 AI 검증은 Spring Event를 이용해 별도 스레드에서 비동기로 처리했습니다.

@Async("verificationTaskExecutor")
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void processAiVerification(VerificationRequestedEvent event) {
    // AI 검증 처리
}

 

@TransactionalEventListener(AFTER_COMMIT)을 적용해 아이디어 생성 트랜잭션이 정상적으로 커밋된 이후에만 검증이 시작되도록 했습니다. @Async와 전용 ThreadPoolTaskExecutor를 사용해 실제 검증 작업은 별도 스레드에서 실행했습니다.

사용자 요청과 AI 검증 작업 자체는 분리되어 있었지만, 비동기 처리 내부의 트랜잭션 범위를 다시 확인하면서 다른 문제가 보였습니다.

---

2. 문제

AI 검증을 비동기로 처리하는 과정에서 TransactionTemplate로 시작한 트랜잭션 내부에서 검증 엔티티 조회부터 OpenAI API 호출, 결과 저장까지 모두 수행하고 있었습니다.

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void processAiVerification(VerificationRequestedEvent event) {
    transactionTemplate.executeWithoutResult(
            status -> processAiVerificationInTransaction(event)
    );
}

public void processAiVerificationInTransaction(VerificationRequestedEvent event) {
    // 검증 엔티티 조회

    AiVerificationStructuredResult result =
            openAiVerificationService.verify(event.request());

    // 결과 저장
    // 신뢰도 점수 갱신
    // 상태 변경
}

 

즉 원본 요청의 트랜잭션과는 분리되어 있었지만, 별도 스레드에서 다시 시작한 트랜잭션이 OpenAI 응답을 기다리는 동안 계속 유지되는 구조였습니다.

DB 트랜잭션이 유지되는 동안에는 JDBC 커넥션도 함께 점유됩니다. 따라서 실제 DB 작업이 없는 외부 API 대기 시간에도 커넥션이 풀로 반환되지 않을 수 있습니다.

 

OpenAI 클라이언트의 read timeout은 300초로 설정되어 있었습니다. 단일 호출이 timeout까지 지연될 경우 최대 300초 가까이 커넥션이 점유될 수 있는 구조였습니다.

openai:
  verification:
    timeout-seconds: 300

 

검증 요청이 동시에 증가하면 AI 검증과 직접 관련이 없는 요청까지 DB 커넥션을 할당받지 못할 가능성이 있습니다. 외부 API 응답 지연이 DB 커넥션 점유를 통해 다른 요청으로 전파될 수 있는 구조였습니다.

 

직접 측정해 확인

코드만으로 구조적인 위험은 확인할 수 있었지만, 실제로 외부 API 대기 중 커넥션이 점유되는지 확인하기 위해 측정 환경을 구성했습니다.

• HikariCP maximum-pool-size=1
• 커넥션 획득 제한 시간 3,000ms
• OpenAI Mock 응답 10초 지연
• OpenAI 대기 중 별도의 DB 조회 실행

실제 read timeout인 300초를 그대로 재현하지 않고 10초 지연을 사용한 이유는 확인하려는 대상이 외부 API 대기 시간 동안 DB 커넥션이 함께 점유되는지 여부였기 때문입니다.

 

[초기] active=0, idle=1, waiting=0
[DelayedMock] OpenAI 호출 진입 - 10000ms 지연 시작

[OpenAI 대기 중] active=1, idle=0, waiting=0

[동시 DB 조회] 실패 | 소요=3005ms
[동시 DB 조회] 예외=CannotGetJdbcConnectionException

 

OpenAI 응답을 기다리는 동안 HikariCP가 active=1, idle=0 상태를 유지했고, 같은 시점에 실행한 DB 조회는 커넥션을 할당받지 못해 3,005ms 후 CannotGetJdbcConnectionException으로 실패했습니다.

---

3. 해결

비동기 검증의 트랜잭션 경계를 외부 API 호출 단위가 아니라 실제 DB 작업 단위로 다시 나눴습니다.

1. 짧은 트랜잭션에서 검증 상태와 취소 여부 확인
2. OpenAI API 호출은 트랜잭션 밖에서 수행
3. 응답을 받은 이후 새로운 트랜잭션을 시작해 결과 저장

검증 요청
    ↓
상태 확인
[짧은 TX]
    ↓
OpenAI API 호출
[TX 없음]
    ↓
검증 결과 · 신뢰도 점수 · 상태 반영
[짧은 TX]

 

먼저 짧은 트랜잭션에서 현재 검증 상태와 취소 여부만 확인하고 종료합니다. 이미 취소된 요청이라면 OpenAI API를 호출하지 않습니다.

이후 OpenAI API 호출은 트랜잭션 없이 수행하고, 응답을 받은 뒤에만 새로운 TransactionTemplate을 시작해 검증 결과, 신뢰도 점수, 아이디어 상태 등 실제 DB 변경이 필요한 작업을 처리하도록 변경했습니다.

 

기존의 @TransactionalEventListener(AFTER_COMMIT)과 @Async 구조는 그대로 유지했습니다.

원본 요청 트랜잭션이 정상적으로 커밋된 후 별도 스레드에서 AI 검증을 실행한다는 구조 자체가 문제가 아니라, 그 비동기 작업 내부에서 외부 API 호출까지 DB 트랜잭션에 포함한 것이 문제였기 때문입니다.

핵심은 비동기 처리 여부가 아니라 비동기 작업 내부의 트랜잭션 범위였습니다.

---

4. 결과

변경 후에도 동일하게 HikariCP 풀 크기를 1로 제한하고 OpenAI Mock 응답을 10초 지연시킨 뒤 다시 측정했습니다.

 

Before - 트랜잭션 내부에서 외부 API 호출

========== 커넥션 점유 측정 ==========
[초기] active=0, idle=1, waiting=0
[DelayedMock] OpenAI 호출 진입 - 10000ms 지연 시작
[OpenAI 대기 중] active=1, idle=0, waiting=0
HikariPool - Timeout failure stats (total=1/1, idle=0/1, active=1, waiting=0)
[동시 DB 조회] 실패 | 소요=3005ms
[동시 DB 조회] 예외=CannotGetJdbcConnectionException
[동시 DB 조회] 메시지=Failed to obtain JDBC Connection
[DelayedMock] 지연 종료 - 응답 반환
[완료 후] active=0, idle=1
=====================================

 

 

OpenAI 응답을 기다리는 동안 active=1, idle=0 상태가 유지됐습니다. 같은 시점에 실행한 DB 조회는 커넥션을 할당받지 못해 3,005ms 후 CannotGetJdbcConnectionException으로 실패했습니다.

 

After - 외부 API 호출을 트랜잭션 밖으로 분리

========== 커넥션 점유 측정 ==========
[초기] active=0, idle=1, waiting=0
[DelayedMock] OpenAI 호출 진입 - 10000ms 지연 시작
[OpenAI 대기 중] active=0, idle=1, waiting=0
[동시 DB 조회] 성공 | 소요=8ms | 결과=1
[DelayedMock] 지연 종료 - 응답 반환
[완료 후] active=0, idle=1
=====================================

 

 

동일한 10초 지연 환경에서는 active=0, idle=1 상태가 유지되어 커넥션이 풀에 반환된 것을 확인했습니다. 같은 시점에 실행한 DB 조회도 8ms 만에 정상 처리됐습니다.

 

측정 항목	Before	After
OpenAI 대기 중 Hikari active	1	0
OpenAI 대기 중 Hikari idle	0	1
동시 DB 조회	3,005ms 후 실패	8ms 성공
조회 결과	CannotGetJdbcConnectionException	정상 조회

측정 조건: HikariCP maximum-pool-size=1, connection-timeout=3,000ms, OpenAI Mock delay=10s

 

측정 결과도 함께 검증

첫 측정에서는 기대했던 active=0이 나왔지만, 확인해보니 지연 Mock 자체가 활성화되지 않은 상태였습니다. 전체 실행 시간과 Mock 진입 로그를 확인해 해당 측정이 유효하지 않다는 것을 발견했고, 측정 환경을 수정한 뒤 Before와 After를 동일한 조건에서 다시 측정했습니다.

이를 통해 원하는 수치가 나왔는지만 확인하는 것이 아니라, 실제로 의도한 조건에서 측정이 이루어졌는지도 함께 확인했습니다.

---

5. 남은 한계

이번 측정은 단일 AI 검증 요청을 기준으로 진행했습니다. 따라서 동시 검증 요청 수와 커넥션 풀 크기를 단계적으로 증가시켰을 때 처리량과 대기 시간이 어떻게 달라지는지까지는 확인하지 못했습니다.

maximum-pool-size=1 역시 커넥션 경합을 명확하게 관찰하기 위한 측정 조건입니다. 운영 환경의 풀 크기가 더 크더라도 외부 API 호출 중 트랜잭션이 유지되는 구조에서는 동시 요청이 증가할수록 동일한 유형의 커넥션 경합이 발생할 가능성이 있습니다.

 

또한 외부 API 호출 최종 실패 시에는 PENDING_ADMIN_REVIEW 상태로 전환하고 관리자가 다시 검증할 수 있는 경로를 두었지만, 백오프 기반 자동 재시도나 스케줄러 기반 자동 회수까지는 구현하지 못했습니다.

---

6. 정리

코드를 읽으면서 문제 가능성은 확인할 수 있었지만, 실제로 어느 정도의 영향을 주는지는 측정이 필요했습니다. 직접 측정한 뒤에는 "커넥션 풀이 고갈될 수 있다"는 가능성 대신 "10초 지연 환경에서 동시 DB 조회가 3,005ms 후 CannotGetJdbcConnectionException으로 실패했다"는 결과로 문제를 설명할 수 있었습니다.

 

측정 과정에서는 결과 자체가 신뢰할 수 있는지도 함께 확인했습니다. 첫 실행에서 기대했던 수치가 나왔더라도 실제 지연 Mock이 실행되지 않았다면 유효한 결과가 아니었습니다. 그래서 수치뿐 아니라 로그와 실행 조건까지 확인한 뒤 동일한 조건에서 변경 전후를 다시 비교했습니다.

 

이번 개선을 통해 비동기 처리 여부와 트랜잭션의 범위는 별개의 문제라는 점을 확인했습니다. 외부 API 호출을 별도 스레드로 분리하더라도 그 내부에서 트랜잭션이 계속 유지되면 API 응답을 기다리는 동안 DB 커넥션도 함께 점유될 수 있습니다.

이후 비슷한 구조를 설계할 때는 외부 API 호출과 실제 DB 작업의 경계를 먼저 구분하고, 네트워크 대기 구간에 불필요한 트랜잭션과 커넥션 점유가 포함되어 있지 않은지 확인하려 합니다.