DEV Community: Sanha Ko

Netty 내부 동작 원리로 파헤친 WebClient 초기 지연 이슈

Sanha Ko — Fri, 26 Dec 2025 16:25:03 +0000

물류 인프라를 보유하고 있는 회사들은 3PL이라는 서비스를 제공합니다. 3PL이란 물류 인프라를 갖춘 회사가 그렇지 못한 판매처로부터 배송 업무를 위탁받아 제공하는 서비스를 말합니다.

판매처는 배송이 필요한 주문 목록을 3PL 시스템에 등록하게 되는데, 이 과정에서 입력된 주문이 유효한 주문인지 확인하기 위해서 여러 시스템과 소통하게 됩니다.

외부 API 호출을 위한 도구로는 WebClient를 사용하고 있었는데요. 아래 지표에서 보듯이, 외부 API 호출까지의 지연 시간이 원인을 알 수 없이 길어지는 현상이 '간헐적'으로 발견되었습니다.

이번 포스트에서는 해당 현상의 원인을 파악하며 알게 된 WebClient의 내부 동작 원리와 Reactor Netty의 아키텍처, 그리고 해결책을 공유하고자 합니다.

원인 파악을 위한 가정

지연이 발생한다는 것은 요청이 어딘가에서 즉시 처리되지 못하고 대기하고 있었을 가능성이 높다는 의미입니다.

이전 사진에서 빨간 박스로 표시된 메서드는 객체 생성과 WebClient 호출만을 담당하고 있었습니다. WebClient 내부의 어느 처리 단계에서 병목이 발생할 수 있는지 명확히 식별하려면 아키텍처에 대한 이해가 선행되어야 했습니다. 이를 위해 WebClient의 요청 처리 방식과 Reactor Netty의 아키텍처를 분석했습니다.

WebClient 실행 메커니즘

먼저 문제가 발생한 코드의 구조를 살펴보겠습니다.

OrderRegistrationService.java

private final static int CONCURRENCY_CALL = 10;

List<RefineResult> results = Flux.fromIterable(registerDtos)
    .flatMap(dto -> Mono.defer(() ->
       omsService.refineAddress(dto.getPrimaryAddress(), dto.getSecondaryAddress())
       .defaultIfEmpty(ApiResponse.failure("NO_RESPONSE", false))
    ).map(resp -> new RefineResult(dto, resp)), CONCURRENCY_CALL)
    .collectList()
    .block();

OmsService.java

@Override
public Mono<ApiResponse<RefineAddressDto>> refineAddress(String primaryAddress, String secondaryAddress) {
    RefineAddressInput request = RefineAddressInput.builder()
        .primaryAddress(primaryAddress)
        .secondaryAddress(secondaryAddress)
        .build();

    return omsClient.post()
        .uri("/refine-address")
        .bodyValue(request)
        .retrieve()
        .bodyToMono(RefineAddressOutput.class)
        .timeout(Duration.ofSeconds(5))
        .retryWhen(RetryPolicy.fixedDelay(1, Duration.ofMillis(100), "[OMS 주소정제] 재시도 요청: " + request))
        .map(output -> output.isSuccess() ? ApiResponse.success(RefineAddressDto.from(output))
            : ApiResponse.<RefineAddressDto>failure("응답 결과에 데이터가 없음", false))
        .onErrorResume(ex -> ExternalErrorHandler.handleError(ex, extractOmsErrorMessage(ex), "OMS 주소정제"));
}

Cold Sequence와 구독 시점

위 코드에서 실제 HTTP 요청이 언제 발생하는지 이해하려면 WebClient의 Cold Sequence 특성을 먼저 이해해야 합니다.

WebClient의 리액티브 체인은 Cold Sequence로 동작합니다. 구독이 발생하기 전까지는 파이프라인만 정의될 뿐, 실제 실행은 일어나지 않습니다. HTTP 요청 발송 시점은 subscribe()가 호출되는 순간이며, 코드상의 block()이 내부적으로 이를 트리거합니다.

List<RefineResult> results = Flux.fromIterable(registerDtos)
    .flatMap(dto -> Mono.defer(() -> ...))
    .collectList()
    .block();  // ← 구독 시작점

block()의 구독 신호는 역방향(upstream)으로 전파됩니다

block() → collectList() → flatMap() → Mono.defer() → WebClient 체인

flatMap(Function, int concurrency)은 인자로 전달된 concurrency 수 만큼의 Mono를 동시에 구독합니다. Mono.defer()는 각 구독 시점마다 내부 람다를 실행하여 새로운 Mono를 생성하므로, 각 DTO마다 독립적인 HTTP 요청 파이프라인이 생성됩니다.

// 구독될 때마다 새로운 WebClient 체인 생성
Mono.defer(() -> omsService.refineAddress(...))

TaskQueue로의 전달

omsService.refineAddress(...)가 반환하는 Mono가 구독되면 요청 설정을 빌드하고, .retrieve() 이후 체인이 구독되면서 쓰기 요청이 TaskQueue에 저장됩니다.

omsClient.post()
    .uri("/refine-address")
    .bodyValue(request)
    .retrieve()
    .bodyToMono(RefineAddressOutput.class)

POST 요청이 NioEventLoop의 TaskQueue에 저장되면, WebClient를 호출한 스레드의 역할은 여기서 끝납니다. 이후 작업은 EventLoop 스레드가 담당합니다.

Netty EventLoop 스레드의 동작 원리

WebClient의 HTTP 요청이 TaskQueue에 저장되는 이유는 Netty의 이벤트 루프 기반 비동기 처리 모델 때문입니다. 이 모델을 이해하려면 먼저 네트워크 통신의 기본 개념을 짚고 넘어가야 합니다.

User Space와 Kernel Space

서로 다른 머신의 애플리케이션이 통신하려면 시스템 콜로 유저 모드와 커널 모드를 오가며 커널 내 소켓 버퍼에 데이터를 읽거나 써야 합니다.

소켓 버퍼에 데이터를 어떻게 읽고 쓰느냐에 따라 Blocking I/O와 Non-blocking I/O로 나뉩니다. 둘의 차이는 스레드가 시스템 콜 후 응답을 기다리는지 여부입니다.

Blocking I/O: 데이터가 준비될 때까지 스레드가 대기
Non-blocking I/O: 데이터가 없으면 즉시 반환, 스레드는 다른 작업 수행 가능

효율적인 Non-blocking I/O를 구현하려면 특정 이벤트를 등록해 놓고 해당 이벤트가 발생했을 때만 처리하는 방식이 필요합니다. 이렇게 하면 하나의 스레드로 여러 채널을 관리할 수 있습니다.

Multiplexing I/O와 Selector

이벤트 기반 소켓 통신에서는 하나의 Selector가 여러 소켓 채널의 변화를 감지하며 이벤트가 발생했을 때만 처리합니다. 이를 Multiplexing I/O라고 합니다.

Linux에서 이 Multiplexing I/O는 epoll 시스템 콜로 구현됩니다. Java NIO의 Selector는 내부적으로 이 epoll을 사용합니다.

Selector.select()의 실제 동작

OS 커널이 능동적으로 I/O 이벤트를 Selector에 알려주는 것처럼 보이지만, 실제로는 그렇지 않습니다.

Selector.select()가 호출되면 유저 모드에서 커널 모드로 전환되고, 내부적으로 epoll_wait() 시스템 콜이 호출되면서 호출 스레드는 커널에서 블로킹 상태로 대기합니다.

epoll_wait을 호출하면, OS 커널은 이전에 epoll_ctl로 등록된 파일 디스크립터(소켓)들을 모니터링하다가, 네트워크 카드에 데이터가 도착하거나 소켓 버퍼에 쓰기가 가능해지는 등의 I/O 이벤트가 발생하면 이를 감지합니다. I/O가 발생한 소켓은 커널 내 Ready Queue에 추가되고, epoll_wait()이 반환되어 대기 중이던 스레드가 깨어납니다.

즉, User Space가 커널에 요청하고 시스템 콜로 응답받는 pull 구조입니다.

select() 자체는 블로킹 호출이지만, 하나의 스레드가 여러 소켓을 감시하고 이벤트가 발생한 소켓들만 골라서 처리합니다. 따라서 각 소켓 입장에서는 전용 스레드 없이도 비동기적으로 처리되는 것과 같은 효과를 얻게 됩니다.

NioEventLoop의 구조

이제 Netty의 EventLoop가 Selector를 어떻게 활용하는지 살펴보겠습니다.

EventLoop의 구현체인 NioEventLoop는 1 Thread + 1 Selector + 1 TaskQueue로 구성됩니다.

EventLoop 스레드는 기본적으로 CPU 코어 수만큼 생성됩니다. Math.max(Runtime.getRuntime().availableProcessors(), 4)

각 EventLoop 스레드는 전용 NioEventLoop 인스턴스를 실행하며, 단일 스레드가 무한 루프를 돌면서 두 가지 작업을 수행합니다.

I/O 이벤트 처리 (네트워크 읽기/쓰기)
TaskQueue의 작업 처리 (사용자가 등록한 Runnable)

// 개념적인 코드
while (true) {
    // 1. 네트워크에서 뭔가 일어났는지 확인
    네트워크_이벤트_확인();
    // 2. 일어난 일들 처리
    이벤트들_처리();
    // 3. 누가 시켜놓은 작업들 처리
    작업큐에서_작업꺼내서_실행();
}

실제 Netty 코드를 보면 (Netty 4.2 기준)

// SingleThreadIoEventLoop.java:153-164
protected void run() {
    do {
        runIo();                    // ← 1+2: I/O 확인 및 처리
        runAllTasks(maxTasksPerRun); // ← 3: 작업큐 처리
    } while (!confirmShutdown());
}

runIo()는 내부적으로 NioIoHandler.run()을 호출합니다.

// NioIoHandler.java:420-485
public int run(IoExecutionContext runner) {
    // 1단계: select - I/O 이벤트 존재 여부 확인
    select(runner, wakenUp.getAndSet(false));

    // 2단계: 있으면 처리
    return processSelectedKeys();
}

이제 각 단계를 자세히 살펴보겠습니다.

1. select() - I/O 이벤트 감지

EventLoop는 I/O 이벤트 처리와 TaskQueue에 쌓인 작업 처리, 두 가지 역할을 수행합니다. 이때 Selector.select()를 사용하여 처리할 I/O 이벤트가 있는지 확인합니다.

select() 메서드는 TaskQueue에 작업이 존재하는지 여부에 따라 적절한 select 방식을 결정합니다.

// NioIoHandler.java
private void select(IoExecutionContext runner, boolean oldWakenUp) {
    Selector selector = this.selector;

    for (;;) {
        // 태스크가 있으면 즉시 확인하고 넘어감
        if (!runner.canBlock() && wakenUp.compareAndSet(false, true)) {
            selector.selectNow();   // 작업 있으면 바로 확인
            break;
        }

        // 태스크가 없으면 이벤트 올 때까지 대기
        int selectedKeys = selector.select(timeoutMillis);
    }
}

@Override
public boolean canBlock() {
   assert inEventLoop();
   return !hasTasks() && !hasScheduledTasks();
}

TaskQueue가 비었을 때

TaskQueue가 비어있으면 Netty는 select(timeout)을 호출하여 커널로 부터 I/O 이벤트 신호를 받거나 타임아웃이 될 때까지 블로킹 상태로 대기하여 CPU 사용을 줄입니다.

만약 대기 중 TaskQueue에 새 task가 들어오면, wakeup 메커니즘을 통해 select()의 블로킹을 깨워서 즉시 반환시키고, 루프를 돌며 TaskQueue를 처리할 수 있게 합니다.

TaskQueue가 있을 때

TaskQueue에 작업이 있으면 selectNow()를 호출하여 I/O 이벤트가 있는지 빠르게 확인하고, 곧바로 테스크 실행으로 넘어가 작업 지연을 줄입니다.

만약 TaskQueue에 작업이 있는 상황에서 select(timeout)을 호출해 블로킹되면, EventLoop 스레드가 잠들어 테스크 처리가 지연되고 응답성이 떨어지게 됩니다. 반대로 selectNow()만 계속 수행하면 준비된 I/O 이벤트가 없어도 계속 확인하므로 불필요한 반복으로 busy-wait(CPU 낭비)이 발생할 수 있습니다.

즉, Netty의 select()는 상황에 따라 적절한 방식을 선택하여 CPU를 낭비하지 않고 효율적으로 I/O 이벤트를 대기합니다.

select() 호출 이후의 내부 동작

앞서 Netty가 상황에 따라 select(timeout) 또는 selectNow()를 선택적으로 호출한다는 것을 살펴보았습니다. 이제 이 호출이 실제로 어떤 과정을 거쳐 커널까지 도달하고, 다시 돌아오는지 살펴보겠습니다.

Selector.select()를 호출하면 JDK 내부의 SelectorImpl 클래스가 이를 처리합니다.

// SelectorImpl.java
@Override
    public final int select(long timeout) throws IOException {
        return lockAndDoSelect(null, (timeout == 0) ? -1 : timeout);
    }

lockAndDoSelect()는 동기화를 수행한 뒤 Multiplexing I/O를 담당하는 doSelect()를 호출합니다.

// SelectorImpl.java
private int lockAndDoSelect(Consumer<SelectionKey> action, long timeout)
      throws IOException
{
    synchronized (this) {
        ensureOpen();
        if (inSelect)
            throw new IllegalStateException("select in progress");
        inSelect = true;
        try {
            synchronized (publicSelectedKeys) {
                return doSelect(action, timeout);
            }
        } finally {
            inSelect = false;
        }
    }
}

여기서 doSelect()는 추상 메서드입니다. 운영체제마다 효율적인 Multiplexing I/O 메커니즘이 다르기 때문에, JDK는 플랫폼별로 다른 구현체를 제공합니다.

OS	구현 클래스	시스템 콜
Linux	EPollSelectorImpl	epoll_wait()
macOS	KQueueSelectorImpl	kevent()
Windows	WindowsSelectorImpl	IOCP

이 글에서는 서버 환경에서 가장 많이 사용되는 Linux의 epoll 기반 구현을 중심으로 살펴보겠습니다. (JDK 21 기준)

EPollSelectorImpl 인스턴스는 언제 생성되는가?

EPollSelectorImpl 인스턴스는 Selector.open() 호출 시점에 초기화됩니다.

애플리케이션에서 new NioEventLoopGroup(n) 호출

내부적으로 n개의 NioIoHandler 생성

각 NioIoHandler 생성자에서 provider.openSelector() 호출

Linux 환경에서는 EPollSelectorImpl 인스턴스 생성

EPollSelectorImpl 생성 시 다음과 같은 초기화가 이루어집니다.

EPollSelectorImpl(SelectorProvider sp) throws IOException {
   super(sp);

   // 1. epoll 인스턴스 생성 (epoll_create 시스템 콜)
   this.epfd = EPoll.create();

   // 2. epoll_wait 결과를 저장할 네이티브 메모리 할당
   this.pollArrayAddress = EPoll.allocatePollArray(NUM_EPOLLEVENTS);

   // 3. wakeup용 EventFD 생성
   this.eventfd = new EventFD();
   IOUtil.configureBlocking(IOUtil.newFD(eventfd.efd()), false);

   // 4. EventFD를 epoll에 EPOLLIN으로 등록
   EPoll.ctl(epfd, EPOLL_CTL_ADD, eventfd.efd(), EPOLLIN);
}

즉, 하나의 EventLoop마다 하나의 epoll 인스턴스가 매핑됩니다.

epoll의 세 가지 시스템 콜

epoll은 세 가지 시스템 콜을 제공합니다

epoll_create: epoll 인스턴스(채널 감시 저장소) 생성
epoll_ctl: 감시할 FD 추가/수정/삭제
epoll_wait: 이벤트(read/write)가 발생할 때까지 대기하고, 이벤트가 발생한 FD 목록을 반환

JDK의 EPoll.wait()는 JNI를 통해 커널의 epoll_wait() 시스템 콜을 직접 호출합니다.

epoll_wait()는 미리 할당된 네이티브 메모리의 epoll_event 구조체 배열에 준비된 이벤트 정보를 채우고, 준비된 이벤트 개수를 반환합니다. 이 배열에는 각 FD와 발생한 이벤트 타입(EPOLLIN/EPOLLOUT/EPOLLERR 등)이 담겨 있습니다.

EPollSelectorImpl.doSelect()에서 이 메서드들이 실제로 호출되는 흐름을 보면:

// EpollSelectorImpl.java
@Override
protected int doSelect(Consumer<SelectionKey> action, long timeout) throws IOException {
    int to = (int) Math.min(timeout, Integer.MAX_VALUE);

    int numEntries;
    processUpdateQueue();      // epoll_ctl로 관심 이벤트 변경 반영
    processDeregisterQueue();

    try {
        begin(blocking);
        // epoll_wait 시스템 콜 호출
        numEntries = EPoll.wait(epfd, pollArrayAddress, NUM_EPOLLEVENTS, to);
    } finally {
        end(blocking);
    }

    // 반환된 이벤트 처리
    return processEvents(numEntries, action);
}

2. processSelectedKeys() - I/O 이벤트 처리

EPoll.wait()가 이벤트 개수를 반환하면, EPollSelectorImpl.processEvents()가 해당 개수만큼 이벤트 배열을 순회하며 각 FD에 연결된 SelectionKey를 찾아 selectedKeys에 추가합니다. 이후 Netty의 NioIoHandler.processSelectedKeys()가 seletedKeys를 순회하며 각 채널의 이벤트를 처리합니다.

 // NioIoHandler.java
  private int processSelectedKeysOptimized() {
      int handled = 0;
      for (int i = 0; i < selectedKeys.size; ++i) {
          SelectionKey k = selectedKeys.keys[i];
          selectedKeys.keys[i] = null;  // GC를 위해 null 처리

          processSelectedKey(k);  // 각 이벤트 처리
          ++handled;
      }
      return handled;
  }

  private void processSelectedKey(SelectionKey k) {
      final DefaultNioRegistration registration = (DefaultNioRegistration) k.attachment();

      // 준비된 이벤트를 핸들러에 전달
      // OP_READ  → 데이터 수신
      // OP_WRITE → 데이터 송신
      // OP_CONNECT → 연결 완료
      // OP_ACCEPT → 새 연결 요청
      registration.handle(k.readyOps());
  }

registration.handle()은 내부적으로 AbstractNioChannel.AbstractNioUnsafe.handle()을 호출합니다. 이 메서드는 이벤트 타입에 따라 적절한 처리를 수행합니다.

// AbstractNioChannel.java:420-450
@Override
public void handle(IoRegistration registration, IoEvent event) {
    NioIoOps nioReadyOps = ((NioIoEvent) event).ops();

    // 1. OP_CONNECT: 연결 완료 처리 (가장 먼저 처리)
    if (nioReadyOps.contains(NioIoOps.CONNECT)) {
        removeAndSubmit(NioIoOps.CONNECT);
        unsafe().finishConnect();
    }

    // 2. OP_WRITE: 쓰기 가능 상태 - 대기 중인 버퍼 전송
    if (nioReadyOps.contains(NioIoOps.WRITE)) {
        forceFlush();
    }

    // 3. OP_READ / OP_ACCEPT: 데이터 수신 또는 새 연결 수락
    if (nioReadyOps.contains(NioIoOps.READ_AND_ACCEPT) || nioReadyOps.equals(NioIoOps.NONE)) {
        read();
    }
}

3. runAllTasks() - Non-I/O Task 처리

I/O 이벤트 처리가 끝나면 runAllTasks()가 호출되어 TaskQueue에 쌓인 작업들을 처리합니다. WebClient의 HTTP 요청도 바로 이 단계에서 실제로 전송됩니다.

// SingleThreadEventExecutor.java
protected boolean runAllTasks(long timeoutNanos) {
     // 스케줄 큐에서 실행 가능한 태스크를 TaskQueue로 이동
     fetchFromScheduledTaskQueue();
     Runnable task = pollTask();

     final long deadline = timeoutNanos > 0 ? getCurrentTimeNanos() + timeoutNanos : 0;
     long runTasks = 0;

     for (;;) {
         safeExecute(task); // 테스크 실행

         runTasks ++;

         task = pollTask();
         if (task == null) {
             lastExecutionTime = getCurrentTimeNanos();
             break;
          }
      }

     afterRunningAllTasks();
     return true;
}

전체 흐름 요약

지금까지 살펴본 내용을 하나의 다이어그램으로 정리하면 다음과 같습니다.

병목이 발생한 인스턴스의 vCPU 수는 2개였습니다. Netty의 EventLoop 스레드 수는 기본적으로 Math.max(availableProcessors(), 4)로 결정되므로, 이 환경에서는 EventLoop 스레드가 총 4개 존재합니다.

지금까지 살펴본 바와 같이 Netty의 EventLoop는 Multiplexing I/O 방식으로 동작하기 때문에 적은 수의 스레드로도 많은 동시 요청을 처리할 수 있습니다. epoll_wait()은 수천 개의 채널이 등록되어 있어도 실제로 I/O 이벤트가 발생한 채널만 반환하므로, 동시 요청 수가 EventLoop 스레드 수보다 많다고 해서 병목이 발생하지는 않습니다.

따라서 "동시 요청 10개 > EventLoop 스레드 4개"는 병목의 원인이 아닙니다.

또 다른 가설: Parallel Scheduler 스레드 경합

그렇다면 무엇이 문제였을까요? 문제가 발생한 코드를 다시 살펴보겠습니다.

return omsClient.post()
   .uri("/refine-address")
   .bodyValue(request)
   .retrieve()
   .bodyToMono(RefineAddressOutput.class)
   .timeout(Duration.ofSeconds(5)) // ← 여기
   .retryWhen(RetryPolicy.fixedDelay(1, Duration.ofMillis(100), "...")) // ← 여기
   // ...

timeout()과 retryWhen()의 fixedDelay()는 내부적으로 Schedulers.parallel()을 사용하여 타이머를 스케줄링합니다. 그리고 Parallel Scheduler의 스레드 수 역시 CPU 코어 수에 비례합니다.

vCPU 2개 환경에서 동시 요청 수가 10개인 환경에서 할당된 Parallel Scheduler 스레드 수보다 많은 요청을 처리하면서 병목이 발생했을 가능성이 있습니다.

검증

실제로 CPU 코어 수 제한이 WebClient 동시 호출 성능에 미치는 영향을 측정하기 위해 JMH(Java Microbenchmark Harness)를 사용하여 벤치마크를 수행했습니다.

테스트 환경

공통 설정

동시 호출 수 (Concurrency): 10
총 요청 수 (totalRequests): 50
서버 응답 지연 (serverLatencyMs): 200m
측정 방식: 10회 반복 측정 후 평균값 산출

Case 1: CPU 코어 10개 (refineAddress_concurrency10_cpu10)

JVM 옵션: -XX:ActiveProcessorCount=10
Available Processors: 10
Reactor Schedulers DefaultPoolSize: 10

Case 2: CPU 코어 2개 (refineAddress_concurrency10_cpu2)

JVM 옵션: -XX:ActiveProcessorCount=2
Available Processors: 2
Reactor Schedulers DefaultPoolSize: 2

결과

지표	CPU 10 코어	CPU 2 코어
평균 처리 시간	1035.498 ms	1049.652 ms
안정성 (Stdev)	7.496	18.554
신뢰구간 폭	22.667 ms	56.103 ms
Reactor 워커 수	10	2

예상과 달리, CPU 코어 수(Parallel Scheduler Pool Size)에 따른 처리 시간 차이는 약 14ms(1.4%) 로 거의 없었습니다.

스레드 수가 2개에서 10개로 증가해도 성능 향상이 미미합니다. timeout/retry의 스케줄링 자체는 매우 가벼운 작업이므로, 스레드 수가 적어도 큰 영향을 주지 않는것을 확인할 수 있었습니다.

벤치 마크 코드

public class RunBenchmark {

    public static void main(String[] args) throws RunnerException {

        Options options = new OptionsBuilder()
            .include(OmsWebClientConcurrencyBenchmark.class.getSimpleName())
            .forks(1)
            .warmupIterations(10) // 각 벤치 마크 실행 전 최적화를 위한 웜업
            .warmupTime(TimeValue.seconds(5))
            .measurementIterations(10) // 각 벤치마크 측정. 10회 반복
            .measurementTime(TimeValue.seconds(5))
            .timeUnit(TimeUnit.MILLISECONDS)
            .addProfiler(JavaFlightRecorderProfiler.class)  // JFR 프로파일러 추가
            .resultFormat(ResultFormatType.JSON)
            .result("jmh-results.json")
            .build();

        new Runner(options).run();
    }
}

@BenchmarkMode(Mode.AverageTime)
public class OmsWebClientConcurrencyBenchmark {

    private static final int CONCURRENCY_CALL = 10;

    @State(Scope.Benchmark)
    public static class BenchState {

        @Param({"50"})
        public int totalRequests; // 한 번의 벤치마크 호출당 요청 총 개수

        @Param({"200"})
        public int serverLatencyMs; // 목 서버가 응답 전 인위적으로 대기할 지연(ms)

        private DisposableServer server;
        private OmsService omsService;

        @Setup(Level.Trial)
        public void setup() {
            int availableProcessors = Runtime.getRuntime().availableProcessors();
            String reactorPoolSize = System.getProperty("reactor.schedulers.defaultPoolSize", String.valueOf(availableProcessors));
            System.out.println("\n========================================");
            System.out.println("Benchmark started: OMS WebClient concurrency(10) under different CPU core caps");
            System.out.println("Params: totalRequests=" + totalRequests + ", serverLatencyMs=" + serverLatencyMs);
            System.out.println("Available processors (current JVM): " + availableProcessors);
            System.out.println("Reactor Schedulers DefaultPoolSize: " + reactorPoolSize);
            System.out.println("========================================");

            // 목 응답 JSON
            String json = "{" +
                "\"jibeonAddress\":{\"primaryAddress\":\"서울시 강남구\",\"secondaryAddress\":\"테스트로 123\",\"zipCode\":\"06200\"}," +
                "\"roadAddress\":{\"primaryAddress\":\"서울시 강남구\",\"secondaryAddress\":\"테스트로 123\",\"zipCode\":\"06200\"}," +
                "\"sigungu\":\"강남구\",\"dong\":\"역삼동\",\"provider\":\"OMS\",\"hcode\":\"11110\",\"bcode\":\"1111010100\",\"buildingNumber\":\"123\"" +
                "}";

            this.server = HttpServer.create()
                .host("127.0.0.1")
                .port(0)
                .route(routes -> routes.post("/refine-address", (req, res) ->
                    res.header("Content-Type", "application/json")
                        .sendString(Mono.delay(Duration.ofMillis(serverLatencyMs))
                            .then(Mono.just(json)))))
                .bindNow();

            int port = server.port();
            WebClient omsClient = WebClient.builder().baseUrl("http://127.0.0.1:" + port).build();
            WebClient fbkClient = WebClient.builder().baseUrl("http://127.0.0.1:" + port).build();
            this.omsService = new OmsServiceImpl(omsClient, fbkClient);
        }

        @TearDown(Level.Trial)
        public void tearDown() {
            if (server != null) {
                server.disposeNow();
            }
        }
    }

    private List<ApiResponse<RefineAddressDto>> invokeRefineAddressBatch(OmsService omsService, int totalRequests) {
        return Flux.range(0, totalRequests)
            .flatMap(i -> Mono.defer(() -> omsService.refineAddressIgnore("서울시 강남구", "테스트로 123")
                .defaultIfEmpty(ApiResponse.failure("NO_RESPONSE", false))), CONCURRENCY_CALL)
            .collectList()
            .block();
    }

    // 코어 수 2로 실행
    @Benchmark
    @Fork(value = 1, jvmArgsAppend = {
        "-XX:ActiveProcessorCount=2",
        "-XX:FlightRecorderOptions=threadbuffersize=16k,globalbuffersize=10m,memorysize=50m",
        "-XX:StartFlightRecording=settings=profile"
    })
    public List<ApiResponse<RefineAddressDto>> refineAddress_concurrency10_cpu2(BenchState state, Blackhole blackhole) {
        var result = invokeRefineAddressBatch(state.omsService, state.totalRequests);
        blackhole.consume(result);
        return result;
    }

    // 코어 수 10으로 실행
    @Benchmark
    @Fork(value = 1, jvmArgsAppend = {
        "-XX:ActiveProcessorCount=10",
        "-XX:FlightRecorderOptions=threadbuffersize=16k,globalbuffersize=10m,memorysize=50m",
        "-XX:StartFlightRecording=settings=profile"
    })
    public List<ApiResponse<RefineAddressDto>> refineAddress_concurrency10_cpu10(BenchState state, Blackhole blackhole) {
        var result = invokeRefineAddressBatch(state.omsService, state.totalRequests);
        blackhole.consume(result);
        return result;
    }
}

지연의 원인: Cold Start

원인을 분석하는 동안 유사한 지표를 가진 Trace를 추가로 수집할 수 있었는데요. 지표에서 한 가지 공통된 패턴을 발견할 수 있었습니다.

지연이 발생한 모든 케이스가 애플리케이션 배포 직후 첫 번째 외부 API 호출 시점에 발생한다는 사실을 발견했습니다.

Netty의 리소스는 Lazy Initialization 방식으로 동작합니다. 즉, WebClient를 생성하는 시점이 아니라 실제로 첫 번째 HTTP 요청을 보내는 시점에 초기화가 이루어집니다.

Cold Start 해결책

두 가지 해결책을 검토했습니다.

Connection Pool에 사전 커넥션 맺기: 미리 연결을 생성해 대기
Warmup 옵션: 리소스를 사전 로드하되 실제 연결은 필요 시점에 생성

Connection Pool에 사전 커넥션 생성

처음에는 애플리케이션 시작 시점에 미리 커넥션을 생성하여 풀에 대기시키는 방법을 고려하였습니다. 커넥션은 maxIdleTime, maxLifeTime 만큼 살아있다가 종료되는데, 기본값은 -1로 무제한입니다. 즉, 별도로 설정하지 않으면 커넥션이 시간 제한 없이 풀에 유지됩니다.

단, 두 설정값을 기본값(-1)으로 두면 서버 측의 keepAliveTimeout 설정과 충돌할 수 있습니다.

서버에서 커넥션을 먼저 끊으면 클라이언트는 이미 닫힌 커넥션으로 요청을 보내게 되어 "Connection reset by peer" 오류가 발생할 수 있습니다. 따라서 실무에서는 서버의 keepAliveTimeout보다 작은 값으로 maxIdleTime을 설정하는 것이 권장됩니다.

결국 애플리케이션 시작 시점에 미리 커넥션을 생성해 놓더라도 일정 시간 요청이 없으면 유휴 커넥션이 자동 해제되므로 트래픽이 간헐적인 '주문 등록'과 같은 케이스에는 적합하지 않습니다.

Netty 이슈에서도 ConnectionPool을 웜업하는건 해결책이 아니며 고려사항이 아니라는것을 확인할 수 있습니다. (Add warmup functionality for the servers/clients #1455)

Warmup 옵션

반면 warmup은 실제 TCP 커넥션을 맺지 않고, 이후 요청에서 재사용되는 네트워크 리소스들을 애플리케이션 시작 시점에 미리 초기화 합니다. 따라서 커넥션이 해제되더라도 EventLoop, DNS 리졸버 등은 이미 로드되어 있어, 후속 요청에서 초기화 비용이 발생하지 않습니다.

@Configuration
public class WebClientConfig {

   @Bean
   public WebClient omsWebClient() {
      HttpClient httpClient = HttpClient.create()
         .baseUrl("https://oms-api.example.com");

       // 애플리케이션 시작 시 warmup 수행
       httpClient.warmup().block();

       return WebClient.builder()
           .clientConnector(new ReactorClientHttpConnector(httpClient))
           .build();
   }
}

Warmup으로 미리 준비되는 리소스

Warmup을 호출하면, HttpClient/TcpClient 내부에서 다음 리소스들이 구성에 따라 사전에 초기화됩니다.

EventLoopGroup: EventLoop 스레드 풀 생성
DNS Resolver: 비동기 DNS 리졸버 초기화
Native transport 라이브러리: epoll 등 네이티브 루프 및 관련 라이브러리 로드
SSL Context: TLS 핸드셰이크용 SSL 엔진 (HTTPS인 경우)

마무리

지금까지 WebClient의 간헐적 지연 문제를 추적하며 Netty EventLoop가 Selector와 TaskQueue를 관리하는 방식, Linux epoll의 Multiplexing I/O 메커니즘, 그리고 실제 원인이었던 Netty의 Lazy Initialization과 warmup 해결책까지 살펴보았습니다.

이 과정을 통해 단순히 라이브러리를 사용하는 것을 넘어, 내부 동작 원리를 이해하는 것이 얼마나 중요한지 다시 한번 깨달았습니다. 표면적인 증상만 보고 '코어 수를 느리자'거나 '타임아웃을 조정하자'는 식의 접근 대신, 각 레이어를 단계별로 파고들면서 병목이 발생할 수 있는 지점을 하나씩 가시화하고 범위를 좁혀나갈 수 있었습니다.

AI 브라우저를 활용한 PR 메세지 자동화

Sanha Ko — Sun, 14 Dec 2025 07:07:05 +0000

개발자에게 "코드 작성"과 "PR(Pull Request) 작성" 중 무엇이 더 고통스러운지 묻는다면, 의외로 많은 분이 후자를 택합니다. 구현은 즐겁지만, 그것을 남에게 글로 설명하는데는 생각보다 상당한 시간이 소모되기 때문입니다.

최근 Copilot이나 IntelliJ AI 등 다양한 도구가 등장하며 PR 작성을 돕고 있지만, 여전히 '2%' 부족함을 느낍니다. 오늘은 그 부족한 2%를 채우고, 리뷰어와 작성자 모두가 행복해지는 PR 자동화 워크플로우를 공유하고자 합니다.

1. 좋은 Pull Request 란?

기술적인 자동화를 논하기 전에, 우리가 작성해야 할 '좋은 PR'의 정의부터 명확히 해야 합니다.

좋은 PR의 핵심은 '리뷰어에 대한 공감'입니다. 리뷰어는 바쁜 시간을 쪼개서 코드를 봅니다. 리뷰어의 시간을 아껴주고, 코드의 의도를 명확하게 전달하는것이 PR의 가장 중요한 목표입니다.

좋은 PR의 구성요소

명확한 맥락: 단순히 코드가 '무엇'이 변했는지는 diff만 봐도 알 수 있습니다. 중요한 것은 '왜 이 변경이 필요했는가'입니다.
직관적 시각 자료: 백 마디 말보다 한 장의 스크린샷이나 다이어그램이 훨씬 빠른 이해를 돕습니다.
작고 집중된 단위: 하나의 PR은 하나의 이슈만 다루어야 리뷰와 병합의 리스크가 줄어듭니다.

코드 리뷰를 하는 이유 중 하나는 팀원 간의 작업 방향 정렬과 개발 과정에서의 실수 방지입니다.

작업 배경을 상세히 기술하면 리뷰어는 단순히 코드 변경사항만 보는 것이 아니라, 왜 이런 변경이 필요했는지 맥락을 이해할 수 있습니다. 이러한 컨텍스트 공유는 리뷰어가 더 넓은 시야에서 코드를 바라볼 수 있게 하여, 단순 문법적 오류나 컨벤션 위반을 넘어 아키텍처적 개선점, 잠재적 사이드 이펙트, 대안적 접근 방식 등 다양한 관점의 피드백을 제공할 수 있게 됩니다.

결과적으로 배경 설명이 잘 된 PR은 리뷰의 질을 높이고, 팀 전체의 도메인 지식과 시스템 이해도를 향상시키는 효과적인 지식 공유의 수단이 됩니다.

2. 현재 AI Assistant의 한계: '맥락'의 부재

최근의 생성형 AI 도구들(GitHub Copilot, IntelliJ AI 등)은 코드 변경 사항(Diff)을 요약하는 데 탁월한 능력을 보여줍니다. 버튼 하나만 누르면 아래와 같은 요약을 순식간에 만들어냅니다.

Copilot Agent가 생성한 PR

그러나 AI가 만든 PR 메시지는 초안으로는 충분하지만, 작업의 배경까지는 담아내지 못해 코드 수정의 근본적인 이유를 파악하기 어렵다는 한계가 있습니다.

배경 정보 누락: AI는 코드 자체만 보고 요약하므로, "사용자가 특정 상황에서 겪은 불편함"이나 "기획 의도" 같은 외부 맥락을 알지 못합니다.
근본적 이유 부재: 코드를 '수정했다'는 사실은 알지만, '왜 수정해야만 했는지'에 대한 비즈니스적/기술적 배경은 설명하지 못합니다.

결국, 리뷰어가 가장 궁금해하는 '작업 배경'을 채우는 일은 여전히 사람의 몫으로 남게 됩니다. 그리고 배경을 간결하고 핵심적으로 정리하는 것은 PR 작성에서 가장 많은 시간을 잡아먹습니다.

이 과정을 AI가 대신할 수 있다면, 리뷰어에게 코드의 의도를 명확하게 전달하면서 PR 작성에 드는 시간을 크게 줄일 수 있을 것입니다.

3. Jira 티켓에서 맥락 가져오기

그렇다면 어디서 맥락을 가져올 수 있을까요? 저는 개발을 시작하기 전에 티켓에 해결하고자 하는 문제와 목표를 명확히 정의합니다.

티켓에는 작업을 한눈에 파악할 수 있도록 "무엇을", "왜" 하는지를 간결하게 담습니다. 예를 들어 "주문 취소 시 재고 복구 실패 이슈 수정"처럼 핵심 문제와 해결 방향을 제목에서부터 드러냅니다.

그 다음 작업의 배경과 목적을 상세히 기술합니다. 현재 어떤 문제가 발생하고 있는지(AS-IS), 왜 이 작업이 필요한지, 어떤 비즈니스 영향이 있는지를 구체적으로 작성하고, 작업을 통해 달성하고자 하는 상태(TO-BE)와 명확한 완료 기준을 함께 정의합니다.

"PR 쓰기도 귀찮은데 Jira까지 자세히 쓰라고요?"라고 반문하실 수 있습니다. 하지만 문제 정의는 AI가 아닌 사람이 해야 할 영역입니다. 티켓을 충실히 작성하면 다음과 같은 이점이 있습니다.

작업 전 Jira 티켓을 풍부하게 작성하면 좋은점

명확한 목표 설정과 작업 집중: "로그인 버그 수정"이라는 한 줄짜리 티켓은 '어떤 상황에서', '어떤 사용자가', '어떻게' 버그를 겪는지 알려주지 않습니다. 상세한 설명, 재현 방법, 기대 결과가 담긴 티켓은 내가 무엇을 해야 하는지 명확히 알려주어 불필요한 고민 없이 작업에만 집중하게 해줍니다.
정확한 계획 수립과 예측 가능성 확보: 티켓이 상세할수록 작업의 규모와 복잡도를 더 정확하게 예측할 수 있습니다.
미래의 나를 위한 기록: 몇 달 뒤 내가 작성한 코드를 다시 보게 될 때, Jira 티켓은 "내가 왜 이 코드를 이렇게 작성했더라?"에 대한 완벽한 답변이 되어 줍니다. 유지보수와 기능 확장이 훨씬 쉬워집니다.

4. AI 브라우저로 워크플로우 완성하기

우리의 목표는 "PR 작성에 드는 시간과 노력을 최소화하면서, 퀄리티는 극대화하는 것"입니다. 이를 위해 AI 브라우저인 Commet(혹은 Dia)의 기능을 활용할 수 있습니다.

Commet은 단순한 브라우징을 넘어, 사용자가 자주 사용하는 프롬프트를 'Shotcuts' 형태로 저장하고 /Shotcuts로 호출할 수 있는 기능을 제공합니다. 이를 통해 매번 긴 프롬프트를 작성할 필요 없이, Jira의 문맥과 코드 변경 사항을 결합할 수 있습니다.

자동화 워크플로우

Jira 티켓 작성: 작업 전, 이슈의 배경(Why)과 해결 방안(What)을 Jira에 명확히 기록합니다.
Commet Shortcuts 등록: Commet 브라우저에 PR 자동 생성을 위한 Shortcuts를 등록해줍니다.
PR 수정 화면에서 Commet의 사이드 패널을 열고 미리 등록해 둔 PR 작성 Shortcuts을 호출
합니다.

이렇게 하면 AI는 Jira에서 '작업의 의도(Why)'를 가져오고, Git Diff에서 '구현 내용(What)'을 가져와 PR 메시지를 생성해 줍니다.

PR 자동 생성에 사용한 프롬프트

마지막으로 PR 자동 생성에 사용한 프롬프트를 공유드리며 글을 마무리하도록 하겠습니다.

당신은 명확하고 규칙적인 Pull Request 설명을 잘 작성하는 숙련된 소프트웨어 엔지니어입니다.  
당신의 주요 목표는 주어진 Jira 티켓과 PR 세부 정보를 기반으로, 우리 팀의 컨벤션을 **엄격히 준수하는 PR 메시지**를 생성하는 것입니다.

이 페이지의 브랜치 정보를 참고하고, “ABCD”로 시작하는 관련 Jira 티켓을 열어 그 안에 작성된 맥락(context)을 활용해 Pull Request 설명을 작성하세요.  
아래 링크를 통해 Jira 보드에 접속한 뒤, 해당 DPDD 티켓을 검색하여 열 수 있습니다.

Jira 보드 링크:  
`https://jiraboard.atlassian.net/jira/software/c/projects/DPDD/boards/5218?assignee=712020%3A8ef336bd-458e-4630-a79f-d0ea76930601`

PR 메시지는 **한국어로 작성하세요.**

---

### 따라야 할 PR 메시지 템플릿

## 요약 ✍️  
*Jira 티켓과 PR 정보를 기반으로 간결한 요약을 작성하세요.*  
먼저 이번 변경의 **배경과 목적(Why)** 을 설명하고,  
그 다음 **구체적인 변경 내용(What, How)** 을 불릿 포인트로 정리하세요.

이 문서에 포함된 클래스나 주요 구성요소 간의 관계, 역할, 상호작용을 설명하기 위해  
`mermaid` 다이어그램을 코드 블록 안에 렌더링하세요.  
다이어그램은 문서의 변경점과 새롭게 추가된 부분에 초점을 맞추어야 합니다.

**형식(Format):**
- 익숙한 ASCII 문자만 사용합니다. 결과는 고정폭(monospaced) 폰트로 렌더링됩니다.  
- 문서의 **첫 줄과 마지막 줄에는 60개의 “_” 문자로 된 수평선**을 추가합니다.  
- 각 줄은 **최대 60자 이내**로 제한합니다.  
- 파일 관계를 설명할 필요가 있다면 디렉터리/계층 구조를 사용하고,  
  그렇지 않다면 흐름도(Flowchart) 또는 시각적인 형태로 표현합니다.  
- 문서나 내용이 제공되지 않았다면, 내용을 요청하세요.

---

## 리뷰어가 참고하면 좋은 링크 🔗  
- Jira url: [여기에 Jira URL 삽입]

---

## 먼저 읽기 좋은 진입점 🚘️  
*PR 세부 정보를 기반으로, 리뷰 시 가장 먼저 보면 좋은 주요 진입 파일(Controller, Consumer 등)을 나열하세요.*

---

## 리뷰어에게 🙏  
*PR의 복잡한 로직, 트레이드오프, 또는 집중해서 봐주었으면 하는 부분을 짧게 설명하세요.*  
너무 세부적이지 않게, 상위 레벨에서 작성합니다.

---

## 체크 리스트 ✅  
- [x] 테스트 코드를 작성했습니다. (코드 변경이 있는 경우)  
- [x] 커밋 전 SonarLint 분석을 수행했습니다.  
- [x] 셀프 리뷰를 진행했습니다.  
- [x] Jira 티켓을 업데이트했습니다.

Swagger의 사실과 오해: API-First Development

Sanha Ko — Mon, 01 Dec 2025 14:07:04 +0000

개발에서 가장 중요하게 생각하는것 중 하나는 '인터페이스'입니다.
인터페이스를 잘 정의하는 것은 시스템의 일관성과 확장성을 보장하고 변화에 유연하게 대응할 수 있는 기반이 되어줍니다.

새로운 API를 개발할때 가장 먼저 마주하게 되는 인터페이스는 바로 API 명세인데요. API 명세를 잘 정의하기 위해서는 프론트엔드 개발자와 백엔드 개발자간의 효율적인 소통이 필수적입니다.

그렇다면 어떻게 해야 효율적으로 API 명세에 대해 소통할 수 있을까요?
저의 경우, 컨플루언스나 지라 티켓에 API 명세를 작성하거나 임의의 Controller를 구현한 Mock API를 개발환경에 배포한 뒤 Swagger 문서를 공유하는 방식으로 프론트와 소통하였는데요.

이러한 소통 방식은 평소에는 문제가 없지만 짧은 개발 일정 속에 제공해야할 API 수가 많을 경우, 문서와 실제 API가 불일치하거나 다른 작업의 영향으로 인해 빠르게 Mock API를 개발 환경에 제공하지 못하는 상황이 발생했습니다.

무엇이 문제인가

문제의 근본적인 원인은 Swagger를 단순히 코드 작성 후 자동으로 문서를 생성해주는 도구로만 생각하고 사용했기 때문입니다. 즉, 코드를 작성해야 Swagger 문서가 만들어지다 보니 API 디자인과 소통이 Code-First 방식으로 진행되었습니다.

코드와 동기화된 Swagger 문서는 서버가 배포된 이후에 갱신되기 때문에 API 논의 시점에 딜레이가 발생합니다. 이러한 딜레이를 해결하기 위해 별도의 문서를 만들어 공유해야 했습니다. 하지만 작성자마다 문서 포맷과 표현 방식이 달라 일관성을 유지하기 어려웠습니다. 뿐만 아니라 Swagger 문서가 생성되고 나서는 제대로 관리되지 않았기 때문에 신뢰할 수 없는 문서가 되어갔습니다.

결국 API 소통을 위해서는 코드보다 먼저 문서가 선행되어야 합니다. 이러한 접근 방식을 실현하기 위해 등장한 것이 바로 OpenAPI Specification을 활용한 API-First 개발 방식입니다.

OpenAPI Specification이란?

OpenAPI Specification(OAS)에 대해 알아보기 전에 OAS가 어떠한 문제를 해결하기 위해 등장한 기술인지 먼저 알아보도록 하겠습니다.

사실 OAS의 기원은 Swagger에서 시작되었습니다.

The Swagger API project was created in 2011 by Tony Tam, technical co-founder of the dictionary site Wordnik. During the development of Wordnik's products, the need for automation of API documentation and client SDK generation became a major source of frustration. Tam designed a simple JSON representation of the API...
https://en.wikipedia.org/wiki/Swagger_(software)

Swagger의 시작점은 단순한 문서 자동화 툴이 아니었습니다. 2010년대 초, 온라인 사전 서비스 Wordnik를 개발하던 Tony Tam은 API 문서화와 클라이언트 SDK 반복 생성에 점점 지쳐가던 중, “API의 동작을 사람이 아닌 명세(specification)로 정의할 수 있다면 서버와 클라이언트가 동일한 계약을 공유할 수 있지 않을까?”라는 질문에서 Swagger를 고안하게 되었습니다.

Tony Tam은 API를 간결하게 JSON(YAML)으로 기술하는 방식을 설계했고, "코드보다 먼저 계약을 정의하자"라는 단순하지만 강력한 철학을 내세웠습니다. Swagger 명세는 단순한 문서 형식을 넘어, API의 요청-응답 구조와 스키마, 보안, 상태 코드 등 동작의 규약을 포괄하는 '계약(contract)' 그 자체를 기술하는 수단이었습니다. 즉, Swagger의 본래 목적은 API-First(Contract-First) 개발 문화의 정착에 있었던 셈입니다.

실제로 많은 개발자가 말하는 Swagger는 Swagger 그 자체가 아니라 Spring 진영에서 구현된 Springdoc 혹은 Springfox 라이브러리 입니다.

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
}

Springdoc은 코드에 @Tag, @Operation 같은 어노테이션을 붙이면 자동으로 Swagger 형식의 JSON 혹은 YAML 명세를 생성해주는 도구입니다. 명세를 작성하는 게 아니라 코드로부터 명세를 추출하는 Code-First 접근인 것입니다.

Code-First 접근의 가장 큰 한계는 명세와 실제 구현 사이의 신뢰가 무너진다는 점입니다. 명세는 항상 이미 작성된 코드를 전제로 생성되기 때문에, 변화가 생길 때마다 명세가 뒤처지게 마련입니다.

반면 API-First 방식은 명세가 먼저 존재하고, 구현은 그 계약을 이행하는 수단일 뿐입니다. API의 요청 구조, 응답 형식, 각종 제약 조건과 오류 모델까지 우선적으로 합의한 뒤, 서버와 클라이언트가 명세를 기준으로 각자 코드를 작성하거나 검증합니다. 이 때 명세서는 단순한 문서가 아니라, 팀 간 신뢰를 담은 실행 가능한 계약이 됩니다.

OAS를 통한 API-First 실천

이제 API-First 방식을 적용해서 간단한 게시판 서비스를 만들어보겠습니다.

먼저 API 명세를 관리할 별도의 GitHub 저장소를 생성합니다. 클라이언트와 서버 개발자는 각자의 프로젝트에 이 저장소를 서브모듈로 추가해 동일한 명세를 공유하고 효율적으로 관리할 수 있습니다.

Git 서브모듈 추가 방법

각자의 레포지토리에서 아래 명령어로 서브모듈을 추가합니다.

git submodule add https://github.com/headF1rst/simple-dash-board-oas.git contract

여기서 contract는 서브모듈이 생성될 디렉터리 이름입니다. 명령어 실행 후 프로젝트 안에 서브모듈이 정상적으로 추가된 것을 확인할 수 있습니다.

API 명세 작성은 서비스의 전역 정보를 담는 메인 진입점 파일인 openapi.yaml 부터 시작합니다.

openapi.yaml

openapi: 3.0.0
info:
  title: Simple Dashboard API
  description: 게시판 서비스 API
  version: 1.0.0
servers:
  - url: 'https://api.simpledashboard.com'
    description: Production server
  - url: 'http://localhost:8080'
    description: Local development server

paths:
  # 게시글 목록 조회 및 생성 엔드포인트
  /v1/articles:
    $ref: './paths/articles.yaml'
    # 특정 게시글 조회, 수정, 삭제 엔드포인트
  /v1/articles/{id}:
    $ref: './paths/articles-by-id.yaml'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

$ref 키워드를 사용해 다른 위치의 스키마 파일을 참조할 수 있습니다. 이를 통해서 진입점 역할을 하는 openapi.yaml 파일이 지나치게 비대해지는 것을 막고, 하나의 정의를 여러 곳에서 재사용할 수 있습니다.

./paths 디렉터리 하위에 게시글 목록 API 명세를 별도의 YAML 파일로 분리해 관리해 주었습니다.

articles.yaml

# GET/POST /v1/articles
get:
  summary: 게시글 목록 조회
  description: 게시글 목록을 조회합니다. 페이징을 지원합니다.
  operationId: listArticles
  tags:
    - Article
  parameters:
    - $ref: '../components/parameters/BoardIdQuery.yaml'
    - $ref: '../components/parameters/WriterIdQuery.yaml'
    - $ref: '../components/parameters/PageQuery.yaml'
    - $ref: '../components/parameters/SizeQuery.yaml'
    - $ref: '../components/parameters/SortQuery.yaml'
  responses:
    '200':
      description: 조회 성공
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ArticleListResponse.yaml'
    '400':
      $ref: '../components/responses/400BadRequest.yaml'
    '500':
      $ref: '../components/responses/500ServerError.yaml'

post:
  summary: 새로운 게시글 생성
  operationId: createArticle
  tags:
    - Article
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '../components/schemas/ArticleCreateRequest.yaml'
  responses:
    '201':
      description: 생성 성공
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ArticleResponse.yaml'
    '400':
      $ref: '../components/responses/400BadRequest.yaml'

전체 디랙토리 구조는 다음과 같습니다.

contract/
├── openapi.yaml                      # 메인 진입점 (다른 파일들을 $ref로 참조)
├── paths/                            # API 엔드포인트 정의
│   ├── articles.yaml                 # GET/POST /v1/articles
│   └── articles-by-id.yaml           # GET/PUT/DELETE /v1/articles/{id}
├── components/
│   ├── schemas/                      # 데이터 모델 (DTO)
│   ├── parameters/                   # 공통 파라미터
│   ├── responses/                    # 공통 응답
│   └── examples/                     # 예제 데이터
├── openapi-templates/spring/         # 커스텀 Mustache 템플릿
│   ├── api.mustache                  # API 인터페이스 템플릿
│   ├── generatedAnnotation.mustache  # @Generated 제거용
│   └── licenseInfo.mustache          # 라이선스 헤더
└── build.gradle                      # OpenAPI Generator 설정

yaml 파일을 작성할 때는 IntelliJ Plugin인 OpenAPI Specifications이나 Swagger Editor를 활용하면 즉각적인 피드백을 받을 수 있어, 명세 작성과 검증을 훨씬 수월하게 진행할 수 있습니다.

OpenAPI Generator 인터페이스 자동 생성

OpenAPI Generator를 사용하면 애플리케이션 빌드 시점에, yaml로 정의한 API 명세를 기반으로 인터페이스를 자동 생성할 수 있습니다. 이렇게 생성된 인터페이스를 기반으로 Controller 구현체를 작성하면, “코드로부터 명세를 생성하는 방식”이 아니라 “명세로부터 코드를 생성하는 방식”으로 개발할 수 있습니다.

먼저 OpenAPI Generator를 사용하기 위한 Gradle 설정을 추가합니다.

build.gradle

plugins {
    id 'org.openapi.generator' version '7.17.0' apply false
}

build.gradle (:contract)

apply plugin: 'org.openapi.generator'

openApiGenerate {
    generatorName = 'spring'

    // 입력 스펙 경로 (번들링된 파일 사용)
    inputSpec = layout.buildDirectory.file("openapi.bundle.yaml").get().asFile.absolutePath

    // 출력 경로
    outputDir = layout.buildDirectory.dir("generated/openapi").get().asFile.absolutePath

    // 커스텀 Mustache 템플릿 디렉터리
    templateDir = "$projectDir/openapi-templates/spring"

    // 패키지 설정
    apiPackage = 'simple.board.contract.api'
    modelPackage = 'simple.board.contract.model'

    // API/Model 파일만 생성 (supporting 파일 제외)
    globalProperties = [
        apis           : '',
        models         : '',
        supportingFiles: ''
    ]

    // 코드 생성 옵션
    configOptions = [
        interfaceOnly          : 'true',   // 인터페이스만 생성 (구현체 X)
        useTags                : 'true',   // 태그 기반 API 분리
        addGeneratedAnnotation : 'false',  // @Generated 어노테이션 제거
        dateLibrary            : 'java8',  // java.time.* 사용
        serializableModel      : 'true',   // 모델 직렬화 가능
        documentationProvider  : 'none',   // Swagger/SpringDoc 어노테이션 제거
        useBeanValidation      : 'true',   // Bean Validation 사용
        useJakartaEe           : 'true',   // Jakarta EE 사용 (javax → jakarta)
        skipDefaultInterface   : 'true',    // default 메서드 본문 제거
        useSpringBoot3         : 'true'
    ]
}

// 이 모듈은 라이브러리이므로 bootJar 비활성화
tasks.named('bootJar') { enabled = false }
tasks.named('jar') { enabled = true }

// 생성된 소스를 컴파일에 포함
sourceSets {
    main {
        java {
            srcDir layout.buildDirectory.dir("generated/openapi/src/main/java").get().asFile
        }
    }
}

// 컴파일 전에 코드 생성 실행
tasks.named('compileJava') {
    dependsOn tasks.named('openApiGenerate')
}

// OpenAPI 스펙 번들링 태스크
// $ref로 분리된 YAML 파일들을 build 디렉터리로 복사하여 참조 해소
tasks.register('bundleOpenApi') {
    group = 'openapi'
    description = 'Prepare OpenAPI spec files for code generation'

    inputs.file("$projectDir/openapi.yaml")
    inputs.dir("$projectDir/paths")
    inputs.dir("$projectDir/components")

    outputs.file(layout.buildDirectory.file("openapi.bundle.yaml"))
    outputs.dir(layout.buildDirectory.dir("paths"))
    outputs.dir(layout.buildDirectory.dir("components"))

    doLast {
        copy {
            from "$projectDir/openapi.yaml"
            into layout.buildDirectory.get().asFile
            rename { 'openapi.bundle.yaml' }
        }
        if (file("$projectDir/paths").exists()) {
            copy {
                from "$projectDir/paths"
                into layout.buildDirectory.dir("paths").get().asFile
            }
        }
        if (file("$projectDir/components").exists()) {
            copy {
                from "$projectDir/components"
                into layout.buildDirectory.dir("components").get().asFile
            }
        }
    }
}

// 코드 생성 태스크 설정
tasks.named('openApiGenerate') {
    dependsOn tasks.named('bundleOpenApi')

    // 불필요한 생성 파일 삭제
    doLast {
        delete layout.buildDirectory.file("generated/openapi/README.md").get().asFile
        delete layout.buildDirectory.file("generated/openapi/.openapi-generator").get().asFile
    }
}

dependencies {
    // 생성된 코드의 컴파일 의존성 (런타임은 소비 모듈에서 제공)
    compileOnly 'org.springframework:spring-web'
    compileOnly 'jakarta.validation:jakarta.validation-api'
    compileOnly 'com.fasterxml.jackson.core:jackson-annotations'
    compileOnly 'org.openapitools:jackson-databind-nullable:0.2.6'
}

빌드를 실행하면 아래와 같이 API 인터페이스와 스펙 기반의 모델 객체가 자동으로 생성된 것을 확인할 수 있습니다.

커스텀 Mustache 템플릿

OpenAPI Generator가 생성한 API 인터페이스를 확인해보면, 저희의 관심사와는 거리가 먼 다양한 보일러플레이트 코드가 함께 생성되어 다소 장황하게 느껴질 수 있습니다.

Mustache 템플릿을 직접 커스터마이징하면, 프로젝트 상황에 맞춰 생성 코드를 한층 더 최적화할 수 있습니다.

Mustache는 다양한 프로그래밍 언어를 지원하는 Logic-less 템플릿 엔진으로, 복잡한 로직을 최소화하고 간단한 조건문과 반복문만을 지원합니다. 이러한 특성 덕분에 데이터 표현에만 집중할 수 있으며, View와 서버 로직이 명확하게 분리되어 코드가 단순하고 가독성이 높아집니다. OpenAPI Generator는 기본적으로 Mustache 템플릿을 사용해 코드를 생성하기 때문에, 이 템플릿을 직접 수정하여 생성 결과물을 원하는 형태로 제어할 수 있습니다.

다음과 같이 mustache로 불필요한 보일러플레이트를 제거하거나 프로젝트에 필요한 커스텀 어노테이션과 메서드를 추가할 수 있습니다.

package {{package}};

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
{{#useBeanValidation}}
import jakarta.validation.Valid;
{{/useBeanValidation}}
import {{modelPackage}}.*;

/**
 * {{classname}} - API interface
 */
public interface {{classname}} {
{{#operations}}
{{#operation}}

    @RequestMapping(method = RequestMethod.{{httpMethod}}, value = "{{{path}}}")
    ResponseEntity<{{#returnType}}{{returnType}}{{/returnType}}{{^returnType}}Object{{/returnType}}> {{operationId}}({{#allParams}}{{^-first}}
            {{/-first}}{{#isPathParam}}@PathVariable("{{baseName}}") {{/isPathParam}}{{#isQueryParam}}@RequestParam(value = "{{baseName}}", required = {{required}}) {{/isQueryParam}}{{#isHeaderParam}}@RequestHeader(value = "{{baseName}}", required = {{required}}) {{/isHeaderParam}}{{#isBodyParam}}{{#useBeanValidation}}@Valid {{/useBeanValidation}}@RequestBody {{/isBodyParam}}{{dataType}} {{paramName}}{{^-last}},{{/-last}}{{/allParams}});
{{/operation}}
{{/operations}}
}

장황했던 ArticleApi 인터페이스가 간결하게 개선된 것을 볼 수 있습니다.

마무리

지금까지 API-First 방식으로 OpenAPI Specification을 활용한 효율적인 API 개발 프로세스에 대해 알아보았습니다. Git 서브 모듈을 통해 명세를 공유하고, OpenAPI Generator로 백엔드 인터페이스를 자동 생성하며, Mustache 템플릿을 커스터마이징하여 프로젝트에 최적화하는 방법까지 살펴보았습니다.

이러한 접근 방식의 진정한 가치는 프론트엔드 개발자와의 협업에서 더욱 빛을 발합니다. OpenAPI 명세를 공유하면 프론트엔드에서도 typescript-axios나 typescript-fetch 같은 Generator를 사용해 API 호출 코드와 타입을 자동으로 생성할 수 있습니다.

더 나아가 Prism 같은 Mock 서버를 활용하면 백엔드 API 구현이 완료되기 전에도 프론트엔드에서 명세 기반의 Mock 테스트를 진행할 수 있어, 진정한 의미의 병렬 개발이 가능해집니다.

다만, API-First 방식이 도입 초기부터 즉각적인 생산성 향상을 가져다주진 않을 것으로 생각됩니다. OpenAPI Specification 문법에 익숙해지는 과정, YAML 파일 구조화 방법, 그리고 Mustache 템플릿 커스터마이징까지 생각보다 학습 곡선이 가팔랐습니다.

무엇보다 아직 OpenAPI Specification 관련 라이브러리들이 전반적으로 미성숙하다는 느낌을 받았습니다. 자잘한 버그들이 존재했고, 이를 해결하는 과정에서 생각보다 많은 시간이 소비되었습니다.

하지만 이러한 초기 투자는 장기적으로 충분한 가치가 있다고 생각합니다. OpenAPI Specification이 단일 진실 공급원이 되면 "문서와 실제 동작이 다르다", "이 필드가 필수인지 선택인지 모르겠다"라는 식의 불필요한 오해와 소통 비용이 사라지고, 팀 전체가 동일한 명세를 기준으로 대화할 수 있게 될 것이라 생각합니다.

Resilience4j Bulkhead 패턴: 대용량 데이터 처리 안정성 높이기

Sanha Ko — Fri, 24 Oct 2025 15:28:20 +0000

물류 시스템을 개발하다 보면, 대량의 데이터를 엑셀 파일로 내보내야 하는 요구사항을 자주 마주합니다. 사용자가 지정한 기간의 데이터를 엑셀로 제공하려면, 먼저 데이터를 조회한 뒤 Apache POI로 엑셀 형식으로 변환하는 과정이 필요합니다.

다만 이 과정을 한 번에 처리하면 메모리 사용량이 급증해 ‎OutOfMemoryException이 발생할 수 있습니다. 따라서 데이터를 N개 단위로 나누어 조회하고 변환하는 작업을 반복하는 것이 안전합니다. 특히 POI의 SXSSF는 슬라이딩 윈도우 방식으로 설정된 행 수만 메모리에 유지하고, 초과분은 임시 파일로 디스크에 플러시 하여 메모리 상한을 넘지 않도록 합니다.

하지만 요청이 동시에 몰리는 상황에서는 얘기가 달라집니다. 동시 다운로드 건수와 윈도우 크기가 곱해지면서 ‎요청 수 × 윈도우 크기에 해당하는 데이터가 동시에 메모리에 올라가 OOM 위험이 다시 커집니다.

이를 방지하는 방법으로는

서비스 레벨에서 동시 요청 수를 제한하는 방법,

요청마다 독립 프로세스를 띄워 비동기로 처리해 격리하는 방법

이 있습니다.

이번 포스트에서는 Bulkhead 패턴을 활용해 동시 요청을 효과적으로 제한하는 방법을 중심으로 정리해 보도록 하겠습니다.

Bulkhead 패턴이란

Bulkhead는 본래 선박 구조에서 온 용어로, 선체 내부를 여러 개의 격벽으로 나누어 한 구획에 물이 차도 다른 구획으로 침수 피해가 번지지 않게 하는 설계를 뜻합니다. 이러한 선박 설계에서 착안한 Bulkhead 패턴은 시스템 자원을 영역별로 분리하여, 한 영역에 과부하나 장애가 발생해도 전체로 확산하지 않도록 합니다.

구체적으로는 특정 기능이나 엔드포인트를 논리/물리적으로 구분하고, 각 구획에 허용할 동시 처리 수와 대기열 상한을 고정합니다. 이렇게 하면 한 구획의 트래픽이 급증하거나 해당 구획이 리소스를 모두 소진하더라도, 다른 API 처리를 위한 자원은 보존되어 한 작업 때문에 다른 작업이 지연되는 상황을 예방할 수 있습니다.

엑셀 파일 생성은 메모리 소모가 크고 일반적인 API보다 처리 시간이 길기 때문에, 동일 서버가 다른 중요한 요청까지 함께 처리하는 환경에서는 엑셀 다운로드가 몰릴 때 톰캣 스레드나 메모리 같은 공용 리소스를 잠식하여 다른 API까지 느려지는 등 문제가 발생할 수 있습니다. Bulkhead 패턴은 작업별로 리소스를 분리하고 상한을 설정해 이러한 장애 전파를 차단합니다.

Resilience4j를 사용한 Bulkhead 패턴 적용

이러한 Bulkhead 패턴은 직접 구현할 필요 없이 라이브러리를 사용하여 간단하게 구현할 수 있습니다.

대표적인 라이브러리에는 Resilience4j, Netflix Hystrix, Alibaba Sentinel 등이 있는데 가장 활발하게 개발되고 있고, Spring 생태계와의 통합도 잘 되어있는 Resilience4j를 사용하도록 하겠습니다.
(Resilience4j는 이 외에도 서킷 브레이커나 재시도 등 시스템의 회복 탄력성을 위한 다양한 기능들을 제공합니다)

Resilience4j를 사용하여 Bulkhead 패턴을 적용하는 방법은 간단합니다.

의존성 추가

아래와 같이 의존성을 추가해 줍니다.

// Resilience4j
implementation 'io.github.resilience4j:resilience4j-spring-boot3:2.3.0'

참고: https://mvnrepository.com/artifact/io.github.resilience4j

그리고 application.yml에 아래와 같이 추가합니다

resilience4j:
  bulkhead:
    instances:
      excelStream: # 벌크헤드의 이름
        maxConcurrentCalls: 5   # 동시에 5건까지만 스트리밍 생성
        maxWaitDuration: 100ms    # 100ms 초과 시 거절

maxConcurrentCalls는 허용할 최대 동시 호출 수(기본값: 25), maxWaitDuration은 최대 동시 호출 수에 도달했을 때 추가 요청이 들어온 경우 얼마나 대기할 것인지를 나타냅니다. 기본값인 0s로 설정할 경우 대기 없이 즉시 거절하게 됩니다.

application.yml에 옵션을 추가하지 않고 Bulkhead 인스턴스를 만들고 주입해서 사용하는 방법도 가능합니다.

BulkheadSemaphoreConfig.java

@Configuration
public class BulkheadSemaphoreConfig {

    @Bean
    public BulkheadConfigCustomizer excelStreamSemaphore() {
        return BulkheadConfigCustomizer.of("excelStream", builder -> builder
                .maxConcurrentCalls(5)
                .maxWaitDuration(Duration.ofMillis(100))
            );
    }
}

BulkheadThreadPoolConfig.java

@Configuration
public class BulkheadThreadPoolConfig {

    @Bean
    public ThreadPoolBulkheadConfigCustomizer excelStreamThreadPool() {
        return ThreadPoolBulkheadConfigCustomizer.of("excelStream", builder -> builder
                .coreThreadPoolSize(4)
                .maxThreadPoolSize(8)
                .queueCapacity(16)
            );
    }
}

구현 예시

Bulkhead를 적용한 간단한 Controller와 검증을 위한 테스트 코드를 만들어보겠습니다.

ExcelDownloadController.java

@RestController
@RequiredArgsConstructor
public class ExcelDownloadController {

    @Bulkhead(name = "excelStream", type = Type.SEMAPHORE, fallbackMethod = "excelStreamFallback")
    @PostMapping(value = "/orders/download")
    public void download(
        @RequestBody @Valid OrderDownloadRequest request,
        HttpServletResponse response
    ) {
        try {
            // 엑셀 다운로드 처리 시뮬레이션 (500ms 소요)
            Thread.sleep(500);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    public void excelStreamFallback(
        OrderDownloadRequest request,
        HttpServletResponse response,
        BulkheadFullException ex
    ) {
        throw new TooManyRequestsException("Too many concurrent requests");
    }
}

@Bulkhead의 ‎type에는 ‎Bulkhead.Type.SEMAPHORE와 ‎Bulkhead.Type.THREADPOOL 두 가지가 있으며, 기본값은 ‎SEMAPHORE입니다. 두 방식의 차이는 아래에서 자세히 설명하겠습니다.

실패 시 호출할 ‎fallbackMethod 또한 지정할 수 있습니다.

주의할 점:

• ‎fallback 메서드의 시그니처는 원본 컨트롤러 메서드와 호환되어야 합니다. 즉, 원본 메서드의 파라미터를 동일한 순서로 모두 받아야 하며, 마지막 인자로 예외 타입을 추가할 수 있습니다.
• 반환 타입도 일치해야 합니다. 원본이 ‎void면 ‎fallback도 ‎void여야 하고, ‎ResponseEntity<T>를 반환하면 ‎fallback 역시 같은 타입을 반환해야 합니다.

ExcelDownloadControllerBulkheadTest.java

@SpringBootTest(classes = SampleApplication.class)
@AutoConfigureMockMvc
@ActiveProfiles("test")
class ExcelDownloadControllerBulkheadTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void bulkhead가_최대_동시_호출_수를_제한한다() throws InterruptedException {
        // given
        int totalRequests = 10;
        int maxConcurrentCalls = 5;
        CountDownLatch startLatch = new CountDownLatch(1);
        CountDownLatch doneLatch = new CountDownLatch(totalRequests);
        ExecutorService executorService = Executors.newFixedThreadPool(totalRequests);

        AtomicInteger successCount = new AtomicInteger(0);
        AtomicInteger rejectedCount = new AtomicInteger(0);

        // when
        for (int i = 0; i < totalRequests; i++) {
            executorService.submit(() -> {
                try {
                    startLatch.await(); // 모든 스레드가 동시에 시작하도록 대기

                    mockMvc.perform(post("/orders/download")
                            .contentType(MediaType.APPLICATION_JSON)
                            .content("{}"))
                        .andExpect(status().isOk());

                    successCount.incrementAndGet();
                } catch (Exception e) {
                    // TooManyRequestsException이 발생하면 거절된 것으로 카운트
                    if (e.getCause() instanceof TooManyRequestsException ||
                        (e.getMessage() != null && e.getMessage().contains("Too many concurrent requests"))) {
                        rejectedCount.incrementAndGet();
                    } else {
                        // 다른 예외도 거절로 간주 (Bulkhead 관련)
                        rejectedCount.incrementAndGet();
                    }
                } finally {
                    doneLatch.countDown();
                }
            });
        }

        startLatch.countDown(); // 모든 요청 동시 시작
        doneLatch.await(5, TimeUnit.SECONDS); // 모든 요청 완료 대기
        executorService.shutdown();

        // then
        System.out.println("[DEBUG_LOG] Success count: " + successCount.get());
        System.out.println("[DEBUG_LOG] Rejected count: " + rejectedCount.get());

        // maxConcurrentCalls(5)를 초과하는 요청은 거절되어야 함
        assertThat(successCount.get()).isLessThanOrEqualTo(maxConcurrentCalls);
        // 일부 요청은 거절되어야 함 (10개 요청 중 5개 초과분)
        assertThat(rejectedCount.get()).isGreaterThan(0);
        // 전체 처리된 요청 수 확인
        assertThat(successCount.get() + rejectedCount.get()).isEqualTo(totalRequests);
    }

application-test.yml

resilience4j:
  bulkhead:
    instances:
      excelStream: # 벌크헤드의 이름
        maxConcurrentCalls: 5   # 동시에 5건까지만 스트리밍 생성
        maxWaitDuration: 100ms    # 100ms 초과시 거절

테스트를 실행해 보면 다음과 같이 테스트가 성공하고, 10건의 동시 요청 중 5건만 수행되고 나머지 5건은 거절된 걸 확인할 수 있습니다.

SEMAPHORE vs THREADPOOL

Resilience4j의 Bulkhead는 내부적으로 두 가지 실행 모델을 제공합니다.

SEMAPHORE와 THREADPOOL 두 방식 모두 동시 처리량을 제한하고 격리하는 목적은 같지만, 격리 수준과 적용 시점에서 차이가 있습니다.

SemaphoreBulkhead

SemaphoreBulkhead는 java.util.concurrent.Semaphore를 내부적으로 사용하여 동시 호출 수를 제어하며, 현재 스레드에서 동기적으로 코드를 실행합니다.

자바의 세마포어는 permit이라는 내부 카운터를 기반으로 동시 접근을 제어하는 동기화 메커니즘입니다. Resilience4j의 Bulkhead는 maxConcurrentCalls에 설정된 최대 동시 호출 수만큼 permit이 초기화됩니다.

스레드가 호출을 시도할 때, 설정된 동시 호출 수 한도 내라면 즉시 실행되고 한도를 초과했다면 maxWaitDuration 동안 대기하게 됩니다. 이 시간 내에 permit을 얻지 못하면 BulkheadFullException이 발생하게 됩니다.

세마포어 방식은 다양한 스레딩 모델과 I/O 모델에서 잘 동작하며, 호출 응답이 빠를고 예측 가능한 동기 작업에 효과적입니다. 별도의 스레드 풀을 관리하지 않으므로 오버헤드가 적고, 단순한 동시성 제어가 필요한 경우에 유용합니다.

ThreadPoolBulkhead

ThreadPoolBulkhead는 내부적으로 ArrayBlockingQueue와 ThreadPoolExecutor를 사용하여 작업을 비동기적으로 실행하며,
특정 작업을 전용 스레드 풀로 격리하여 동시 호출을 관리합니다.

스레드 풀에 사용 가능한 스레드가 있다면 작업이 즉시 실행되고, 모든 스레드가 사용 중이면 작업은 큐에 추가되어 스레드가 사용 가능해질 때까지 대기합니다. 만약 큐까지 가득 차면 BulkheadFullException이 발생하여 요청이 거부됩니다.

이러한 스레드 풀 방식은 응답 시간이 길거나 예측 불가능한 I/O 바운드 작업에 적합합니다. 비동기 처리가 필요하거나, 느린 외부 서비스 호출로부터 메인 스레드 풀을 보호해야 하는 경우에 적합합니다.

언제 뭘 사용해야 할까

세마포어는 호출 스레드에서 직접 동기적으로 실행되기 때문에 별도의 스레드 생성이나 컨텍스트 스위칭 등의 오버헤드가 발생하지 않습니다. 만약 수행시간이 적게 걸리는 작업이라면 스레드 풀로 작업을 위임하고 컨텍스트 스위칭하는 데 드는 비용이 오히려 더 클 수 있습니다.

반면 느린 작업에 세마포어를 사용할 경우 호출

단순히 동시 호출 수만 제한하는 것이 목적이라면 세마포어 방식이 효율적입니다. 하지만 외부 API 호출처럼 작업 시간이 길고 완전한 리소스 격리가 필요하다면 전용 스레드 풀을 할당하는 스레드 풀 방식이 더 적합합니다.

마무리

지금까지 Bulkhead 패턴과 Resilience4j를 활용하여 시스템 전체의 안정성을 확보하는 방법을 알아보았습니다.

촉박한 개발 일정 속에서 장애 방어 로직을 추가하는 것이 때로는 오버엔지니어링처럼 느껴질 수 있습니다. 하지만 리소스 소모가 많고 장애 전파 위험이 큰 기능에서 발생하는 한 번의 장애는, 시스템 전체를 마비시키며 훨씬 더 큰 비용을 초래할 수 있습니다.

특히 Resilience4j는 Bulkhead 뿐만 아니라 서킷 브레이커와 같은 강력한 회복탄력성 패턴들을 제공합니다. 복잡한 구현 없이 어노테이션과 간단한 설정만으로 시스템의 안정성을 크게 높일 수 있으니, 이 글이 도입에 도움이 되었으면 합니다.

Solving the Billion-Dollar Mistake: Modern Java Null Safety with JSpecify and NullAway

Sanha Ko — Wed, 24 Sep 2025 23:39:15 +0000

Whether you're a developer just starting with Java or a senior engineer with two decades of experience, the most frequently encountered error is undoubtedly the NullPointerException.

In fact, statistics show that the NullPointerException is the second most common software defect, highlighting just how many developers struggle with NPEs.

Tony Hoare famously called it his "billion-dollar mistake."

“I call it my billion-dollar mistake. It was the invention of the null reference in 1965. … This has led to innumerable errors, vulnerabilities, and system crashes, which have probably caused a billion dollars of pain and damage in the last forty years.”

To improve null safety, various attempts have been made in the Java ecosystem. Following Optional and the @NonNull annotation from JSR 305, JSpecify has emerged as the modern standard.

This article will demonstrate how to use JSpecify to enhance your project's stability and why it's a low-overhead choice for new and existing systems alike.

NullPointerException: Why Is It Still a Problem?

Consider this code, which calls an API to extract a token and uses the result without any null checks.

// TokenExtractor.java
public interface TokenExtractor {
    String extractToken(String authorization);
}

// Main.java
TokenExtractor tokenExtractor = new DefaultTokenExtractor();
String token = tokenExtractor.extractToken("some-auth-header");
System.out.println("Token length: " + token.length()); // <-- NullPointerException!

This code will throw a NullPointerException if the extractToken method returns null. When it does, the token variable becomes null, and any attempt to access its members, like token.length(), triggers the exception.

The fundamental problem in Java is that nullability is implicit. Unless explicitly stated in API documentation, developers can't be sure whether a return value can be null, leading to misunderstandings and bugs.

JSpecify: A Standard for Explicit Null Safety

To solve this problem, teams from Google, JetBrains, Spring, and others collaborated to create the JSpecify standard.

JSpecify is more than just a set of annotations; it provides a clear specification for null safety, ensuring consistent behavior across tools like IDEs and static analyzers.

JSpecify defines nullability in three states:

Unspecified: The default state in Java, where a value may or may not be null.
Nullable (@Nullable): Explicitly indicates that a value can be null.
Non-null (@NonNull): Guarantees that a value will never be null.

Adding the JSpecify Dependency

implementation 'org.jspecify:jspecify:1.0.0'

Now, we can annotate the TokenExtractor interface to make its nullability explicit.

import org.jspecify.annotations.Nullable;

public interface TokenExtractor {

    @Nullable // Specifies that the return value can be null
    String extractToken(String authorization);
}

With this change, an IDE like IntelliJ IDEA will warn you of a potential NullPointerException at the token.length() call, helping you fix the issue before it becomes a runtime error.

Improving Readability: Setting Defaults with `@NullMarked`

In most APIs (around 90% of the time), values are expected to be non-null. Adding @NonNull to every parameter and return type is tedious, clutters the code, and harms readability.

To address this, JSpecify provides the @NullMarked annotation.

By applying @NullMarked at the package level (in a package-info.java file), all types within that package are considered non-null by default.

// src/main/java/com/example/package-info.java
@NullMarked
package com.example;

import org.jspecify.annotations.NullMarked;

Now, everything is treated as non-null unless explicitly marked with @Nullable, resulting in much cleaner and more manageable code.

Build-Time Verification: Strengthening Null Safety with NullAway

IDE warnings are helpful, but they can't prevent developers from committing code that ignores them.

To enforce null safety, you can use a static analysis tool like NullAway. NullAway is an Error Prone plugin that analyzes JSpecify annotations during the build process and will cause the build to fail if it finds any null-safety violations.

You can configure it in Gradle as follows:

plugins {
  id 'net.ltgt.errorprone' version '4.1.0'
}

dependencies {
    implementation 'org.jspecify:jspecify:1.0.0'

    errorprone "com.google.errorprone:error_prone_core:2.37.0"
    errorprone "com.uber.nullaway:nullaway:0.12.6"
}

tasks.withType(JavaCompile).configureEach {
    options.errorprone {
        disableAllChecks = true
        option("NullAway:OnlyNullMarked", "true")
        error("NullAway")
    }
}

If you ignore the IDE warning and run the build, it will fail with a compile-time error, preventing code that violates null safety from being deployed.

JSpecify in the Spring Ecosystem

Starting with Spring Framework 7 (included in Spring Boot 4), the entire codebase has been migrated to use JSpecify annotations. This means Spring developers can leverage null-safety information from Spring APIs directly in their IDEs and build tools without any additional setup.

For example, the RestClient.body() method returns a @Nullable String, reminding developers to handle the possibility of a null response appropriately.

// Spring's RestClient API
@Nullable
String body = restClient.get().uri("/user").retrieve().body(String.class);

// The IDE warns that 'body' can be null, prompting a null check.
System.out.println(body.length());

The Future of Null Safety in Java

In the long term, null-safety features are planned for the Java language itself as part of Project Valhalla.

New syntax like String? (nullable) and String! (non-null) has been proposed. However, due to Java's commitment to backward compatibility, the default for unannotated types will likely remain "unspecified". (https://openjdk.org/jeps/8303099)

Since this feature is still in the proposal stage and will likely take several years to materialize, JSpecify and NullAway currently represent the most practical and powerful way to improve the stability of Java applications.

Conclusion

JSpecify and NullAway are a powerful combination for addressing Java's "billion-dollar mistake." By using explicit annotations, you clarify your code's intent and can eliminate potential NullPointerExceptions at compile time through IDE and build tool integration.

Based on my experience introducing JSpecify to my team, I've seen firsthand how a simple configuration can significantly improve application stability and code quality. A major advantage is the ability to adopt it gradually on a package-by-package basis, which makes applying it to existing projects far less daunting.

I encourage you to try JSpecify in your projects and start writing safer, more robust Java code today.

10억 달러짜리 실수 해결하기: JSpecify와 NullAway를 사용한 최신 Java Null 안전성

Sanha Ko — Wed, 24 Sep 2025 15:39:56 +0000

자바 프로그래밍을 처음 시작한 개발자부터 20년 경력의 시니어 개발자까지, 경력을 불문하고 개발자들이 가장 자주 마주치는 에러는 NullPointerException 일 것입니다.

실제로 한 통계 자료에 따르면 NullPointerException이 소프트웨어 결함 통계 2위에 해당할 정도로 많은 개발자가 NPE로 고통받고 있다고 하는데요.

'Null 참조를 만든건 나의 10억 달러짜리 실수다' 라는 토니 호어(Tony Hoare)의 말도 너무 유명하죠.

“I call it my billion-dollar mistake. It was the invention of the null reference in 1965. … This has led to innumerable errors, vulnerabilities, and system crashes, which have probably caused a billion dollars of pain and damage in the last forty years.”

이러한 null 안전성을 높이기 위해서 Java에서는 다양한 시도들이 있었고, Optional, JSR 305의 @NonNull 어노테이션을 거쳐, 마침내 JSpecify가 표준 어노테이션으로 제정되었습니다.

지금부터 JSpecify를 사용하여 어떻게 프로젝트에 안정성을 높일 수 있는지, 신규 프로젝트 뿐만 아니라 기존 시스템에 도입하기에도 부담이 없을지에 대해 소개해 드리고자 합니다.

NullPointerException: 왜 여전히 문제인가?

토큰을 추출하는 API를 호출하고, 그 결과를 아무런 확인 없이 사용하는 코드가 있습니다.

// TokenExtractor.java
public interface TokenExtractor {
    String extractToken(String authorization);
}

// Main.java
TokenExtractor tokenExtractor = new DefaultTokenExtractor();
String token = tokenExtractor.extractToken("some-auth-header");
System.out.println("Token length: " + token.length()); // <-- NullPointerException 발생!

이 코드는 extractToken 메서드가 null을 반환할 가능성이 있을 때 NullPointerException을 발생시킵니다.

extractToken 메서드가 null을 반환하게되면 token에 null값이 들어가고 token.length()로 token 값에 접근할 때 NullPointerException이 발생하게 됩니다.

이처럼 Java의 근본적인 문제는 Null 가능성(Nullability)이 암시적(implicit)이라는 점입니다.

API 문서에 명시되어 있지 않으면 개발자는 반환 값이 null일 수 있는지 아닌지 알기 어렵고, 이는 오해와 버그로 이어지게 됩니다.

JSpecify: 명시적인 Null 안전성을 향한 표준

이 문제를 해결하기 위해 Google, JetBrains, Spring 등 여러 팀이 협력하여 JSpecify 표준을 만들었습니다.

JSpecify는 단순한 어노테이션 집합이 아니라, Null 안전성에 대한 명확한 명세를 제공하여 다양한 도구(IDE, 정적 분석기)가 일관되게 동작하도록 하는 것을 목표로 합니다.

JSpecify는 Null 가능성을 세 가지 상태로 정의합니다.

미지정(Unspecified): Java의 기본 상태로, null일 수도 아닐 수도 있습니다.
Nullable (@Nullable): 명시적으로 null 값을 가질 수 있음을 나타냅니다.
Non-null (@NonNull): 절대 null 값을 가지지 않음을 보장합니다.

JSpecify 의존성 추가

implementation 'org.jspecify:jspecify:1.0.0'

이제 TokenExtractor 인터페이스에 어노테이션을 추가하여 Null 가능성을 명시할 수 있습니다.

import org.jspecify.annotations.Nullable;

public interface TokenExtractor {

    @Nullable // 반환 값이 null일 수 있음을 명시
    String extractToken(String authorization);
}

이렇게 하면 IntelliJ IDEA와 같은 IDE는 token.length()를 호출하는 부분에서 잠재적인 NullPointerException을 경고해 주어, 개발자가 런타임 오류가 발생하기 전에 문제를 해결할 수 있게 도와줍니다.

가독성 향상: `@NullMarked`로 기본값 설정하기

대부분의 경우(약 90%) API는 null이 아닌 값을 다룹니다. 모든 매개변수와 반환 값에 @NonNull을 붙이는 것은 귀찮은 일이며 코드를 지저분하게 만들고 자칫 가독성을 해칠 수 있습니다.

이를 해결하기 위해 JSpecify는 @NullMarked 어노테이션을 제공합니다.

@NullMarked 어노테이션을 패키지 수준(package-info.java 파일)에 적용하면 해당 패키지 내의 모든 타입은 기본적으로 Non-null로 간주됩니다.

// src/main/java/com/example/package-info.java
@NullMarked
package com.example;

import org.jspecify.annotations.NullMarked;

이제 명시적으로 @Nullable을 붙인 경우를 제외하고는 모두 Non-null로 처리되므로 코드가 훨씬 깔끔하게 관리할 수 있습니다.

빌드 시간 검증: NullAway로 Null 안전성 강화하기

IDE의 경고는 유용하지만, 이를 무시하고 코드를 커밋하는 것을 막을 수는 없는데요.

Null 안전성을 강제하기 위해 NullAway와 같은 정적 분석 도구를 사용할 수 있습니다. NullAway는 Error Prone의 플러그인으로, 빌드 과정에서 JSpecify 어노테이션을 분석하여 Null 안전성 위반 시 빌드를 실패시킵니다.

Gradle에 다음과 같이 설정할 수 있습니다.

plugins {
  id 'net.ltgt.errorprone' version '4.1.0'
}

dependencies {
    implementation 'org.jspecify:jspecify:1.0.0'

    errorprone "com.google.errorprone:error_prone_core:2.37.0"
    errorprone "com.uber.nullaway:nullaway:0.12.6"
}

tasks.withType(JavaCompile).configureEach {
    options.errorprone {
        disableAllChecks = true
        option("NullAway:OnlyNullMarked", "true")
        error("NullAway")
    }
}

IDE의 경고를 무시하고 빌드를 하면 다음과 같이 컴파일 시점에 에러가 발생하여 Null 안전성을 위반하는 코드가 배포되는 것을 막을 수 있습니다.

Spring 생태계에서의 JSpecify

Spring Framework 7(Spring Boot 4에 포함)부터는 코드베이스 전체가 JSpecify 어노테이션으로 마이그레이션되었습니다. 이는 Spring 개발자들이 별도의 설정 없이도 Spring API의 Null 안전성 정보를 IDE와 빌드 도구에서 바로 활용할 수 있음을 의미합니다.

예를 들어, RestClient의 .body() 메서드는 @Nullable String을 반환하므로, 개발자는 반환 값이 null일 가능성을 인지하고 적절히 처리해야 합니다.

// Spring의 RestClient API
@Nullable
String body = restClient.get().uri("/user").retrieve().body(String.class);

// IDE는 body가 null일 수 있음을 경고
System.out.println(body.length());

앞으로의 Java의 Null 안전성

장기적으로 Java 언어 자체에 Null 안전성 기능이 도입될 예정이라고 하는데요(Project Valhalla의 일부).

? (nullable)와 ! (non-null) 같은 새로운 구문이 제안되었지만, Java의 하위 호환성 원칙 때문에 기본값은 여전히 "미지정(unspecified)"으로 남을 것이라고 합니다.(https://openjdk.org/jeps/8303099)

하지만 어디까지나 제안 단계이고 이 기능이 현실화되기까지는 수년이 걸릴 것이므로, 현재로서는 JSpecify와 NullAway가 Java 애플리케이션의 안정성을 높이는 가장 현실적이고 강력한 방법입니다.

마무리

JSpecify와 NullAway는 Java의 "10억 달러짜리 실수"를 해결하기 위한 강력한 조합입니다. 명시적인 어노테이션을 통해 코드의 의도를 명확히 하고, IDE와 빌드 도구를 연동하여 컴파일 시간에 잠재적인 NullPointerException을 제거할 수 있습니다.

실제로 팀에 JSpecify를 공유하고 프로젝트에 적용하면서 느낀 경험에 비추어 볼때, 간단한 설정으로 어플리케이션 안정성과 코드 품질이 향상 되는것을 경험하였으며, 패키지 단위의 점진적 도입이 가능하기 때문에 기존 프로젝트에 적용하는 데 부담이 적다는 것 역시 큰 장점으로 느껴졌습니다.

이 글을 읽어주시는 분들께서도 JSpecify를 프로젝트에 적용하여 더 안전하고 견고한 코드를 작성해 보시기 바랍니다.

PostgreSQL MVCC Internals: From xmin/xmax to Isolation Levels

Sanha Ko — Sun, 06 Jul 2025 16:10:18 +0000

When multiple users access a database concurrently, how can we guarantee Isolation, one of the core ACID properties? While we could apply locks when reading or writing data, this approach is inefficient because other users must wait for the lock to be released.

To address this challenge, modern RDBMSs like PostgreSQL and MySQL (InnoDB) employ a technique called MVCC (Multi-Version Concurrency Control).

The core idea of MVCC is to create a new version of a row each time it's modified, instead of overwriting the existing data. This method controls concurrency by storing version information for each row, tracking which transaction created or deleted it.

While various database vendors share this core concept of MVCC, their implementations differ. Let's explore these differences by examining the MVCC methods of two of the most popular databases: PostgreSQL and MySQL.

How PostgreSQL Implements MVCC

In PostgreSQL, each row in a table (internally called a 'tuple') contains several system columns that are not directly visible to the user. The key columns for transaction control are xmin and xmax.

xmin: The transaction ID that created this row version.
xmax: The transaction ID that deleted this row version.

Using these two columns, PostgreSQL operates as follows:

INSERT: A new row is created, and the current transaction's ID is recorded in the xmin column. The xmax column remains null.
DELETE: Instead of being physically removed immediately, the row's xmax column is updated with the current transaction's ID. This row is now considered a 'dead tuple'.
UPDATE: This operates as a combination of a DELETE and an INSERT. First, the xmax of the current row is marked with the transaction ID. Then, a new row with the updated values is inserted, and its xmin is set to the current transaction ID.

For a specific row to be visible to a transaction, it must satisfy both of the following visibility rules:

Creation Rule (xmin): The transaction that created the row version (xmin) must have been committed before the current transaction's snapshot was taken.
Deletion Rule (xmax): If the row version was deleted, the deleting transaction (xmax) must not have been committed before the current transaction's snapshot was taken.

How MySQL (InnoDB) Implements MVCC

InnoDB, MySQL's default storage engine, also employs MVCC, but it manages old versions in a distinct way.

Core Metadata: Each row contains important hidden columns, including DB_TRX_ID (the transaction ID that created the version, similar to xmin) and DB_ROLL_PTR (the rollback pointer).
Previous Version Storage: Unlike PostgreSQL, which keeps old versions within the table itself, InnoDB stores the before-images of data in a separate area called the Undo Log. The DB_ROLL_PTR is an address that points to the previous version of the data in this Undo Log.
Operation: When a transaction encounters a data version that is newer than its snapshot, it follows the DB_ROLL_PTR to traverse the Undo Log, reconstructing a version of the data that is visible to it.

Visibility in PostgreSQL by Isolation Level

Ultimately, visibility in PostgreSQL is determined by xmin, xmax, and a snapshot. The differences between isolation levels arise from when this snapshot is created.

Let's explain the visibility rules from the perspective of a transaction, Tx A, using a users table that contains two rows.

READ COMMITTED (Default)

In the READ COMMITTED level, a new snapshot is created for every SQL statement. This means changes committed by other transactions become visible immediately. (Non-Repeatable Read)

1. `Tx A` starts (TXID: 100) and executes its first `SELECT`.

A new snapshot, Snapshot_1, is created for this statement, capturing the current state of the database.

Snapshot_1 Contents: {'Committed TXs': {90, 91}, 'In-Progress TXs': {100}}

Visibility Check (based on Snapshot_1):

'Alice' row (xmin=90): xmin is in the committed list. -> Visible.
'Bob' row (xmin=91): xmin is in the committed list. -> Visible.

Result for Tx A: It sees two records: 'Alice' and 'Bob'.

2. Tx B modifies data and commits.

The original 'Alice' row is updated with xmax=101, and a new 'Alicia' row is created with xmin=101.

The database's global list of committed transactions is updated to {90, 91, 101}.

3. Tx A executes its second SELECT within the same transaction.

According to the READ COMMITTED rule, a completely new Snapshot_2 is created for this SELECT statement.

Snapshot_2 Contents: {'Committed TXs': {90, 91, 101}, 'In-Progress TXs': {100}}

Visibility Check (based on Snapshot_2):

Original 'Alice' row (xmax=101): xmax is in the committed list. -> Not visible.
New 'Alicia' row (xmin=101): xmin is in the committed list. -> Visible.
'Bob' row (xmin=91): xmin is in the committed list. -> Visible.

Final Result for Tx A: It now sees two records: 'Alicia' and 'Bob'.

Tx A executed the same query twice within the same transaction but received different results. This phenomenon, known as a Non-Repeatable Read, is the expected behavior for the READ COMMITTED isolation level.

REPEATABLE READ / SERIALIZABLE

In REPEATABLE READ, a snapshot is created only once, when the first SQL statement in the transaction is executed. This same snapshot is then reused until the transaction ends.

Because of this, even if Tx B changes data and commits, Tx A continues to judge visibility based on its old, fixed snapshot and therefore does not see the changes. This provides a consistent view of the data throughout the transaction, preventing Non-Repeatable Reads. The SERIALIZABLE level uses the same snapshot policy but adds more sophisticated dependency tracking to prevent all concurrency anomalies.

Why the Different Methods? (Design Philosophy Trade-offs)

The different MVCC implementations in PostgreSQL and MySQL reflect trade-offs in their design philosophies.

PostgreSQL: This approach is optimized for read performance. Because previous versions are stored in the table itself, there is no overhead from reconstructing rows, which makes reads very fast. However, since 'dead tuples' accumulate within the table, a periodic cleanup process called VACUUM is essential. Without it, the table can suffer from 'bloat', becoming unnecessarily large.
MySQL (InnoDB): This approach prioritizes table space efficiency. Change history is managed in a separate Undo Log, so the table itself remains clean and contains only the latest data. However, reading past data may incur the additional cost of traversing the Undo Log to reconstruct a row version, and the Undo Log space itself requires management.

Both approaches have their pros and cons. Neither is absolutely superior; rather, they represent different choices made to achieve the distinct goals of each system.

Prompt Engineering Tips from Anthropic Engineers

Sanha Ko — Tue, 24 Jun 2025 13:20:18 +0000

Here are a few impressive points from youtube (AI prompt engineering: A deep dive) where Anthropic engineers shared their prompt writing tips and experiences.

Impressive Prompt Writing Tips

When the model makes a mistake, it can be helpful to ask why it was wrong and directly ask the model how to instruct it next time to avoid the mistake.
When the model faces unexpected input or ambiguous situations, you should provide clear instructions on what to do (e.g., output an "UNCERTAIN" tag) to prevent it from giving a wrong answer.
Inducing the model to explain its reasoning process before providing an answer (Chain of Thought) improves the model's accuracy.
You can ask the model to "interview" you. When it's difficult to clearly grasp what you want, you can get help constructing the prompt by asking the model to ask you questions and elicit the necessary information.

Tips for Improving Prompt Engineering Skills

Read many other people's prompts and model outputs: You can learn a lot by looking at great prompts, analyzing their structure and intent, and by carefully observing the model's outputs.
Attempt many conversations with the model: You need to practice improving prompts by directly and repeatedly communicating with the model.
Show your prompts to others: Showing a prompt you've written to someone without prior knowledge of the task can help you discover parts that are not clear.
Test the model's limits: Trying the most difficult tasks you think the model cannot do and exploring its limits leads to the greatest learning.

인상 깊었던 프롬프트 작성 팁

모델이 실수를 했을 때, 왜 틀렸는지 묻고, 다음에는 어떻게 지시해야 틀리지 않을지 모델에게 직접 물어보는것이 도움이 될 수 있다.
모델이 예상치 못한 입력이나 모호한 상황에 직면했을 때 어떻게 해야 할지 (예: "불확실" 태그 출력) 명확한 지시를 제공하여 잘못된 답변을 내놓는 것을 방지해야 한다.
모델이 답변을 제공하기 전에 자신의 추론 과정을 설명하도록 유도하면(Chain of Thought) 모델의 정확도가 향상된다.
모델에게 자신을 "인터뷰"하도록 요청할 수 있다. 자신이 원하는 바를 명확히 파악하기 어려울 때, 모델한테 나에게 필요한 정보를 질문하고 이끌어내도록 요청하여 프롬프트를 구성하는 데 도움을 받을 수 있다.

프롬프트 엔지니어링 기술 향상 팁

다른 사람의 프롬프트와 모델 출력 많이 읽기: 훌륭한 프롬프트를 보고 그 구조와 의도를 분석하며, 모델의 출력을 면밀히 관찰하면 많은 것을 배울 수 있다.
모델과 많은 대화 시도: 직접 모델과 반복적으로 소통하면서 프롬프트를 개선하는 연습을 해야 한다.
타인에게 프롬프트 보여주기: 자신이 작성한 프롬프트를 그 작업에 대한 사전 지식이 없는 다른 사람에게 보여주면, 명확하지 않은 부분을 발견하는 데 도움이 된다.
모델의 한계 시험: 모델이 할 수 없을 것이라고 생각하는 가장 어려운 작업을 시도하며 모델의 한계를 탐색하는 것이 가장 큰 학습으로 이어진다.

From Theory to Practice: A JMH Showdown Between Sequential and Parallel Streams

Sanha Ko — Sun, 15 Jun 2025 14:33:54 +0000

In our previous post, we delved into the mechanics of ForkJoinPool, the powerful engine behind Java's parallel processing capabilities. Theory is essential, but seeing the real-world impact is what truly matters. Now, it's time to put that theory to the test.

This post presents a practical performance comparison between traditional sequential processing and parallel processing using parallelStream. We'll use the Java Microbenchmark Harness (JMH) to precisely measure the performance gains achieved when validating a large set of data (transportation plans in our example).

The Benchmark: Setting the Stage

This section covers all the details required to understand how the test was designed, configured, and implemented.

Test Environment and JMH Configuration

To ensure a fair and reliable comparison, we established a controlled test environment using JMH. The objective is to measure the average execution time of the TransportPlanExcelUploadValidator's validation logic.

Test Data: A list containing 1,000 to 10,000 transport plan entries.
Benchmark Tool: JMH (Java Microbenchmark Harness).
Warmup Iterations: 5 rounds to allow the JVM to perform initial optimizations.
Measurement Iterations: 10 rounds to capture a stable average execution time.
Forks: 1 fork to run the test in a separate process, ensuring isolation.

It’s important to briefly discuss why the warmup iterations are critical for accurate results on the JVM. When Java code is first run, the JVM may interpret it or use a baseline compiler. Only after code has been executed multiple times (making it "hot"), does the Just-In-Time (JIT) compiler step in to perform significant optimizations, translating bytecode into highly efficient native code. The warmup phase ensures that this JIT compilation and other optimizations have completed, so that our measurements reflect the true performance of the optimized code, not the initial, slower startup phase.

The Benchmark Code

The core of our benchmark lies in the TransportPlanExcelUploadValidatorBenchmark class. We've defined two separate methods, each annotated with @Benchmark, to measure the performance of the sequential and parallel approaches.

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
@State(Scope.Benchmark)
public class TransportPlanExcelUploadValidatorBenchmark {

    private ParallelValidator parallelValidator;
    private SequentialValidator sequentialValidator;

    private LocalDate transportDate;
    private List<TransportPlanExcelUploadInfo> uploadPlans;
    private Set<TransportPlan> registeredPlans;
    private Map<String, Route> routes;

    @Setup
    public void setup() {
        // Prepare test data
        ManagerService managerService = mock(ManagerService.class);
        parallelValidator = new ParallelValidator(managerService);
        sequentialValidator = new SequentialValidator(managerService);

        // Setup Fixtures...

        // Mock manager service methods
        given(managerService.findAllByFullCarNumberAndUsableIsTrue(anySet()))
                .willReturn(Collections.emptyList());

        // Generate test data
        uploadPlans = IntStream.range(0, 1_000)
                .mapToObj(i -> {
                    DawnMiddleMileTransportPlanInfo info = new DawnMiddleMileTransportPlanInfo();
                    info.setTransportDate(transportDate);
                    info.setDeparture("Test Departure");
                    info.setDestination("Test Destination");
                    info.setExpectedEntryTime(String.format("%02d:00", (i % 24)));
                    info.setCarNumber("12가" + (3000 + i));
                    info.setDeliveryRound(1);
                    info.setRowNumber(i + 1);
                    return info;
                })
                .collect(Collectors.toList());
    }

    @Benchmark
    public void sequentialValidation(Blackhole blackhole) {
        var result = sequentialValidator.validateExcelUpload(transportDate, uploadPlans, registeredPlans, routes);
        blackhole.consume(result);
    }

    @Benchmark
    public void parallelValidation(Blackhole blackhole) {
        var result = parallelValidator.validateExcelUpload(transportDate, uploadPlans, registeredPlans, routes);
        blackhole.consume(result);
    }
}

Implementation: Sequential vs. Parallel Validators

Here is a brief look at the two different validator implementations being tested. The core difference lies in how they iterate over the data and collect results.

The SequentialValidator uses a standard for loop. It iterates through the list of plans one by one, validates each item in a single thread, and adds the results directly to standard ArrayLists. This represents a traditional, single-threaded approach.

The ParallelValidator, in contrast, leverages parallelStream().forEach() to process the plans concurrently. To safely collect results from multiple threads without causing race conditions, it uses thread-safe ConcurrentLinkedQueue collections. Once the parallel processing is complete, these queues are drained into ArrayLists to form the final result.

ParallelValidator.java

@Service
@RequiredArgsConstructor
public class ParallelValidator {

    private final ManagerService managerService;

    public TransportPlanUploadValidationResult validateExcelUpload(...) {
        // ...
        ConcurrentLinkedQueue<TransportPlanExcelUploadInfo> validInfosQueue = new ConcurrentLinkedQueue<>();
        ConcurrentLinkedQueue<ValidationFailure> failuresQueue = new ConcurrentLinkedQueue<>();

        sortedUploadPlans.parallelStream().forEach(uploadPlan -> {
            List<String> failedReasons = validateExcelUploadRow(uploadPlan, validationContext);

            if (failedReasons.isEmpty()) {
                validInfosQueue.add(uploadPlan);
            } else {
                failuresQueue.add(ValidationFailure.of(uploadPlan.getRowNumber(), failedReasons));
            }
        });

        List<TransportPlanExcelUploadInfo> validInfos = new ArrayList<>(validInfosQueue);
        List<ValidationFailure> failures = new ArrayList<>(failuresQueue);

        return TransportPlanUploadValidationResult.of(validInfos, failures);
    }
    // ...
}

SequentialValidator.java

@Service
@RequiredArgsConstructor
public class SequentialValidator {

    private final ManagerService managerService;

    public TransportPlanUploadValidationResult validateExcelUpload(...) {
        List<TransportPlanExcelUploadInfo> validInfos = new ArrayList<>();
        List<ValidationFailure> failures = new ArrayList<>();
        // ...
        for (TransportPlanExcelUploadInfo uploadPlan : sortedUploadPlans) {
            List<String> failedReasons = validateExcelUploadRow(uploadPlan, validationContext);

            if (!failedReasons.isEmpty()) {
                failures.add(ValidationFailure.of(uploadPlan.getRowNumber(), failedReasons));
            } else {
                validInfos.add(uploadPlan);
            }
        }

        return TransportPlanUploadValidationResult.of(validInfos, failures);
    }
    // ...
}

Running the Benchmark

The benchmark was executed using the following main class, which configures and runs the JMH Runner.

public class RunBenchmark {

    public static void main(String[] args) throws RunnerException {

        Options accurateOptions = new OptionsBuilder()
                .include(TransportPlanExcelUploadValidatorBenchmark.class.getSimpleName())
                .forks(1)  // Use 1 JVM forks
                .warmupIterations(5)  // 5 warmup iterations
                .warmupTime(TimeValue.seconds(1))  // 1 seconds per warmup iteration
                .measurementIterations(10)
                .measurementTime(TimeValue.seconds(2))  // 2 seconds per measurement iteration
                .resultFormat(ResultFormatType.JSON)
                .result("jmh-results.json")
                .build();

        int availableProcessors = Runtime.getRuntime().availableProcessors();
        System.out.println("Benchmark started: Sequential vs Parallel processing performance comparison");
        System.out.println("Data size: 1,000 transport plans");
        System.out.println("Available processors (cores): " + availableProcessors);
        System.out.println("---------------------------------------------");

        new Runner(accurateOptions).run();
    }
}

The Results: Quantifying the Performance Gain

Now, let's examine the findings from our benchmark tests.

Case 1: A 1,000-Item Dataset

First, let's look at the results for a dataset of 1,000 items. The parallelValidation benchmark scored 6.392 ms/op, while sequentialValidation came in at 20.359 ms/op.

This translates to a 68.60% performance improvement, a significant gain even for a moderately sized dataset.

Case 2: A 10,000-Item Dataset

When we increased the load to 10,000 items, the advantage of parallel processing became even more stark. The parallel version clocked in at 321.574 ms/op compared to the sequential version's 1917.098 ms/op. The performance improvement jumped to an impressive 83.23%. This demonstrates that the benefits of parallelStream become more pronounced as the data volume grows and the initial thread management overhead becomes less significant relative to the total work.

Visualizing the Results

To make the results easier to interpret, the output JSON from JMH can be uploaded to the JMH Visualizer. This free tool generates clear charts that compare the performance scores, making it easy to see the difference at a glance.

Conclusion

Before applying parallelStream across your application, always consider the following:

Parallelism is Not a Silver Bullet. Unconditional parallel processing is not always better. For small datasets or very simple tasks, the overhead costs can lead to performance degradation. You must consider if the cost of task splitting, merging, and Fork/Join scheduling is more expensive than the actual operation (like a simple string comparison).
Benchmarking is Essential. The success in this scenario does not guarantee success in others. The only way to know for sure if a change yields a performance benefit is to test it in a controlled environment.

This leads to the most critical takeaway: Measure, Don't Assume. While theory provides a strong foundation, only empirical data from a benchmark can confirm whether a change is a true optimization for your specific use case.

Discover how ForkJoinPool powers Java's high-performance parallel processing

Sanha Ko — Tue, 03 Jun 2025 06:54:07 +0000

Recently, I optimized our transport operation plan Excel upload feature, boosting performance for logistics system administrators. This tool allows them to upload weekly transportation schedules that our system processes and registers. The upload includes critical validation checks: verifying vehicle numbers, preventing duplicate plans, and identifying scheduling conflicts. By implementing parallel processing for these validations, processing time significantly reduced, enabling logistics managers to finalize transportation plans more efficiently.

To achieve this, I leveraged parallel stream, a powerful feature introduced in Java 8. While the specific performance metrics and a deep dive into parallel stream with JMH will be covered in a future post, this article focuses on ForkJoinPool, engine that parallel stream uses internally to work its parallel processing.

What is ForkJoinPool?

At its core, ForkJoinPool is a specialized ThreadPoolExecutor designed to efficiently run a large number of tasks using a pool of worker threads. It's built around the divide-and-conquer principle. Large tasks are recursively broken down into smaller, more manageable subtasks (the "fork" step). These subtasks are then processed independently by different threads. Once these smaller tasks complete, their results are progressively combined (the "join" step) to produce the final result of the original large task.

This approach is particularly well-suited for CPU-intensive operations where work can be easily parallelized.

The Work-Stealing Algorithm: Keeping Threads Busy

One of the standout features of ForkJoinPool is its work-stealing algorithm, which significantly boosts efficiency. Here's how it works:

Each worker thread in the ForkJoinPool maintains its own deque (double-ended queue) of tasks assigned to it.
A thread primarily processes tasks from the head of its own deque.
If a thread finishes all its tasks and becomes idle, it doesn't just sit there. Instead, it looks at the deques of other busy threads and "steals" a task from the tail of their deque.

This work-stealing mechanism ensures that threads remain busy as long as there's work to be done anywhere in the pool. It provides excellent load balancing, maximizes CPU utilization, and helps improve overall throughput, especially for tasks with unpredictable execution times.

ParallelStream and CommonPool

When you use parallelStream() in Java 8 and later, you're implicitly using a ForkJoinPool. Specifically, parallelStream operations are executed on the static ForkJoinPool.commonPool().

The commonPool() is a JVM-managed, globally available instance of ForkJoinPool. It's convenient because you don't need to manually create, configure, or shut down the pool; the JVM handles its lifecycle. This makes it very easy to introduce parallelism into your applications.

By default, the number of threads in the commonPool() (its parallelism level) is typically set to the number of available processor cores - 1.
(Runtime.getRuntime().availableProcessors() - 1).

The "minus one" is to leave a core for the main application thread or other non-ForkJoinPool tasks. However, if the system has only a single processor, the commonPool()'s parallelism will be 1.

CommonPool is a Shared Resource

It's crucial to note that the commonPool() is a shared resource throughout your application. Not only parallelStream but also CompletableFuture's asynchronous methods (like supplyAsync() and runAsync(Runnable)) use the commonPool() by default if no specific Executor is provided.

Because it's shared, you need to be careful about the types of tasks you submit to it. ForkJoinPool is optimized for CPU-bound tasks – computations that keep the CPU busy. If you use the commonPool() for long-running I/O-bound tasks (e.g., network requests, database queries, file operations) where threads might block and wait for extended periods, you risk starving the pool.

If all threads in the commonPool() become blocked on I/O operations, other parts of your application relying on it (including other parallelStream operations or CompletableFutures) will be unable to get processing time, leading to severe performance degradation or even deadlocks.

For I/O-bound tasks, it's generally better to use a separate, dedicated ExecutorService (like a cached thread pool or a fixed-size thread pool configured for the expected number of blocking tasks) to avoid monopolizing the commonPool().

Conclusion

In essence, ForkJoinPool provides a powerful and efficient framework for parallel task execution, especially for computational workloads. Understanding its mechanics, particularly the work-stealing algorithm and its use in the commonPool(), can help you write more performant and scalable Java applications.

Why @Transactional Sometimes Fails: A Deep Dive into Spring AOP Proxies

Sanha Ko — Sun, 01 Jun 2025 10:18:20 +0000

How @Transactional Works

Transaction Management via AOP and the Proxy Pattern

AOP (Aspect-Oriented Programming) is a programming paradigm that complements Object-Oriented Programming (OOP) by addressing its limitations in enterprise application development. It allows developers to separate and modularize cross-cutting concerns like transactions, caching, and logging, enabling them to focus on business logic.

Spring supports AOP using the Proxy Pattern. A proxy object intercepts method calls to the real object, applying common functionalities before and after the business logic executes.

Similarly, for transaction management, when a method annotated with @Transactional is called, a proxy object handles the transaction's start and end (commit/rollback) before and after the method execution. So, how is this proxy object created?

Two Proxy Creation Methods in Spring AOP

Spring offers two ways to create proxy objects: JDK Dynamic Proxy and CGLIB Proxy.

1. JDK Dynamic Proxy

This method uses JDK's java.lang.reflect.Proxy class to dynamically create proxy objects at runtime that implement interfaces. The target object must implement at least one interface, and the proxy object is created based on the abstract methods of that interface.

Interface-based proxy objects intercept method calls via an InvocationHandler to process additional functionalities.
For example, if logging is added in addition to transaction handling, another necessary proxy object is created, and methods are called in the following order:

ProxyLogging -> ProxyTransaction -> Target

2. CGLIB Proxy (Default Method)

CGLIB (Code Generation Library) is a library that can dynamically generate classes at runtime by manipulating bytecode. Unlike JDK Dynamic Proxy, it creates proxy objects by subclassing the target object. This means a proxy can be created even if the target object doesn't implement an interface. The proxy object overrides the target object's methods to intercept calls and process additional functionalities before and after method execution.

Since Spring Boot 2.x, CGLIB proxy is the default method for creating AOP proxies, including for @Transactional behaviour, regardless of whether the target object implements an interface.

While this proxy-based AOP mechanism is very powerful, it also creates certain scenarios that require caution. One common point of confusion for developers is method calls within the same class, i.e., self-invocation scenarios. With this understanding of how @Transactional operates through proxies, let's now delve into why transactions might not be applied in such self-invocation cases and the reasons behind it.

Internal Method Calls and AOP Proxies

Now that we understand the principle behind @Transactional, let's examine why transactions are not applied when an internal method (a method within the same class) is called, and the reasons for this behavior.

@Service
@RequiredArgsConstructor
public class TransportService {

    private final TransportRepository transportRepository;

    public void sendTransportEvents(List<Long> transportIds) {
        transportRepository.changeStatuses(transportIds);
        // Sending...
    }
}

@Repository
public interface TransportRepository {
    void save(Transport transport);

    default void changeStatuses(List<Long> transportIds) {
        for (Long transportId : transportIds) {
            changeStatus(transportId); // Internal call within the proxy if TransportRepositoryImpl is proxied
        }
    }

    void changeStatus(Long transportId);

    Optional<Transport> findById(Long id);
}

@Repository
@RequiredArgsConstructor
public class TransportRepositoryImpl implements TransportRepository {

    private final TransportJpaRepository transportJpaRepository;

    @Override
    public void save(Transport transport) {
        transportJpaRepository.save(transport);
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    @Override
    public void changeStatus(Long transportId) {
        Transport transport = transportJpaRepository.findById(transportId).orElseThrow();
        transport.updateStatus(TransportStatus.SENT);
    }

    @Override
    public Optional<Transport> findById(Long id) {
        return transportJpaRepository.findById(id);
    }
}

@SpringBootTest
class TransportServiceTest {

    @Autowired
    private TransportService sut;
    @Autowired
    private TransportRepository transportRepository; // This will be a proxy

    @Test
    void whenTransportEventsAreSent_statusChangesToSENT() {
        // given
        var transportA = new Transport(1L, TransportStatus.PENDING);
        var transportB = new Transport(2L, TransportStatus.PENDING);
        List.of(transportA, transportB).forEach(transportRepository::save);

        // when
        sut.sendTransportEvents(List.of(1L, 2L));

        // then
        var result1 = transportRepository.findById(1L).get();
        var result2 = transportRepository.findById(2L).get();

        assertThat(result1.getStatus()).isEqualTo(TransportStatus.SENT);
        assertThat(result2.getStatus()).isEqualTo(TransportStatus.SENT);
    }
}

In TransportRepositoryImpl.changeStatus(transportId), we attempt to change the transport's status from PENDING to SENT using JPA's dirty checking. If dirty checking worked as intended, the test should pass. However, the test fails, and the status remains PENDING.

Why Does This Happen?

@Repository
@RequiredArgsConstructor
@Slf4j
public class TransportRepositoryImpl implements TransportRepository {

    private final TransportJpaRepository transportJpaRepository;
    private final EntityManager em;
    // ...

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    @Override
    public void changeStatus(Long transportId) {
        Transport transport = transportJpaRepository.findById(transportId).orElseThrow();
        transport.updateStatus(TransportStatus.SENT);

        if (em.contains(transport)) {
            log.info("Entity is managed");
        } else {
            log.info("Entity is detached"); // This will be logged
        }
        log.info("Transaction active: {}", TransactionSynchronizationManager.isActualTransactionActive()); // false
    }
}

For dirty checking to work correctly, the entity must be managed by the persistence context.

However, the logs would show that the Transport entity is not managed by the persistence context (Entity is detached) and that no transaction is active (Transaction active: false). This is because the transaction was not applied to this method call.

The lifecycle of the persistence context is tied to the transaction. If a transaction is not active, a persistence context is not created (or an existing one isn't joined), and thus, the entity is not managed within it. Consequently, in the changeStatus() method where no transaction is applied during this specific invocation path, a persistence context isn't effectively used for dirty checking.

Spring creates a proxy object for TransportRepositoryImpl (likely using CGLIB by default). This proxy object overrides the changeStatus() method (which is annotated with @Transactional) to inject transaction-related logic before and after the actual method call.

The problem arises because the TransportRepository's default method changeStatuses() calls changeStatus() through the this reference of the proxy. However, when changeStatuses() (which itself is not @Transactional on the interface proxy) iterates and calls changeStatus(transportId), this call is an internal invocation within the target TransportRepositoryImpl object if the proxy delegates to it without re-intercepting.

More precisely:
When transportRepository.changeStatuses() is called on the proxy:

The proxy might invoke the default method changeStatuses() on itself.
Inside changeStatuses(), the call changeStatus(transportId) is effectively this.changeStatus(transportId). If this refers to the raw TransportRepositoryImpl instance or if the proxy doesn't re-intercept calls from within itself to itself, the proxy's transactional advice for changeStatus() is bypassed.

Spring proxies can only apply transactional (and other AOP) advice to calls that go through the proxy from an external caller. Methods called from within the same class instance (self-invocation) typically bypass the proxy mechanism, so transactions are not applied to the inner call.

Why Do Internal Calls Bypass the Proxy?

In Spring AOP, proxies operate when called by an external client (another bean or component). When an external client calls a method on a bean that is proxied, it's actually calling a method on the proxy object. The proxy then intercepts this call, applies any configured AOP advice (like starting a transaction), and then delegates to the actual method on the target object.

However, when a method is called from within the same class instance (e.g., this.someOtherMethod()), it's not an external call being made through the proxy. Instead, the method is invoked directly on the current instance's this reference, which refers to the raw target object, not the proxy. Therefore, the proxy's AOP advice (including transactional behavior) is bypassed.

To resolve this:

It's recommended to apply @Transactional to methods that are called externally (e.g., directly from the TransportService to transportRepository.changeStatus(id) for each ID).
Alternatively, you can separate the internal method that needs its own transaction into a different Spring bean so it can be called externally (i.e., injected and then called, ensuring the call goes through its proxy).

In the given example, the most straightforward fix to ensure changeStatus is transactional would be to call it directly from TransportService in a loop, or refactor TransportRepository so changeStatuses itself is @Transactional (if that's the desired transactional boundary) and handles the logic appropriately, or to make changeStatuses a method on TransportRepositoryImpl directly and have TransportService call it. The current default method on the interface makes the proxy interaction complex.

Conclusion

To summarize, Spring's @Transactional annotation relies on AOP proxies (typically CGLIB in modern Spring Boot) to manage transactions by intercepting external method calls. A critical takeaway is that @Transactional may not apply to self-invocations because these internal calls bypass the proxy mechanism.

It's important to understand that this self-invocation challenge and the underlying proxy behavior are not exclusive to @Transactional. This is a fundamental aspect of how Spring AOP functions. Consequently, other AOP-driven features, such as declarative caching (@Cacheable), method security (@Secured, @PreAuthorize), or any custom aspects you implement, can be similarly affected by internal calls bypassing the proxy.

Therefore, a solid understanding of AOP's core working principles—especially how proxies intercept external calls and why self-invocations are not subject to this interception—is paramount. This knowledge is key not just for mastering @Transactional, but for effectively utilizing the full spectrum of Spring's powerful AOP capabilities, ultimately leading to more robust and predictable applications.

Java ClassLoaders: How the JVM Dynamically Loads & Executes Your Code.

Sanha Ko — Tue, 27 May 2025 16:28:01 +0000

Java’s "Write Once, Run Anywhere" principle is foundational to its sustained popularity. This portability is powered by the Java Virtual Machine (JVM), specifically its sophisticated system of ClassLoaders and dynamic class-loading mechanisms. Understanding these components can greatly improve your insight into Java’s runtime behaviour and performance characteristics.
Let’s explore step-by-step how Java transforms your code into executable functionality.

What are Java ClassLoaders?

A Java ClassLoader is responsible for dynamically loading Java classes into the JVM at runtime. When the JVM requires a class, it’s the ClassLoader’s task to locate the class definition (typically a .class file) and load it into memory.
Java uses a hierarchical ClassLoader structure composed of three built-in loaders:

Bootstrap ClassLoader:
- The root ClassLoader, implemented in native code.
- Loads Java's core API classes from JAVA_HOME/lib (e.g., rt.jar, tools.jar).
Platform ClassLoader (formerly Extension ClassLoader):
- Loads extension classes from JAVA_HOME/lib/ext or directories specified by the java.ext.dirs property.
- Typically handles classes prefixed with javax.*.
Application ClassLoader (System ClassLoader):
- Loads classes specified by the application’s classpath (CLASSPATH or -cp option).
- Handles application-level classes and JARs.

The ClassLoader Hierarchy & Parent Delegation Model

Java ClassLoaders operate according to the Parent Delegation Model. Under this model, class loading requests are first delegated up to the parent ClassLoader. Only when all parent loaders fail to find the class does the current loader attempt to load it.
The hierarchy looks like this:

Bootstrap ClassLoader
      ↑ delegates to
Platform ClassLoader
      ↑ delegates to
Application ClassLoader

Advantages of Parent Delegation:

Prevents Redundant Loading: Ensures classes are loaded just once.
Maintains Consistency: Core classes like java.lang.Object are uniformly loaded by the Bootstrap loader.
Security: Protects core Java classes from malicious overrides by lower-level loaders.

The JVM Class Loading Process

Java's class loading consists of three main phases:

1. Loading

The ClassLoader reads the class bytecode into memory.
Parses class metadata (name, superclass, interfaces, methods, fields).
Stores metadata in the JVM Method Area.
Creates a corresponding java.lang.Class instance in heap memory.
Classes are loaded dynamically, triggered upon their first usage (object instantiation, static method invocation, or static field access).

2. Linking

This prepares a loaded class for execution, divided into three sub-steps:

Verification:
- Ensures bytecode integrity, adherence to JVM specifications.
- Checks class structure, inheritance rules, interface implementation, bytecode validity, and symbolic reference correctness.
Preparation:
- Allocates memory for static fields and assigns default values (e.g., numeric fields to 0, object references to null).
Resolution:
- Converts symbolic references into direct memory addresses or offsets.
- JVM implementations can perform resolution eagerly (at link-time) or lazily (upon first reference).

3. Initialization

This is the final phase of class loading. During initialization:

Static variables are assigned their actual values as defined in the code (e.g., static int count = 100; would set count to 100, overriding the default 0 from the preparation phase).
Static initialization blocks (if any) are executed. This process is triggered only when the class is actively used for the first time (e.g., an instance is created, a static method is called, or a static field is accessed that is not a compile-time constant). The JVM ensures that initialization is done in a thread-safe manner.

Dynamic Class Loading and Binding in Java

Java’s dynamic loading and binding capabilities provide substantial flexibility:

Dynamic Loading

Java loads classes at runtime, only when needed.
You can explicitly load classes via:

Class<?> clazz = Class.forName("com.example.MyClass");

if (someCondition) {
    try {
        Class<?> clazz = Class.forName("com.example.MyClass");
        Object instance = clazz.getDeclaredConstructor().newInstance();
        // use instance
    } catch (Exception e) {
        e.printStackTrace();
    }
}

Dynamic Binding (Late Binding)

JVM determines the exact method to invoke at runtime.

Essential for polymorphism:

class Animal {
    void sound() { System.out.println("Animal makes a sound"); }
}

class Dog extends Animal {
    @Override
    void sound() { System.out.println("Dog barks"); }
}

public class DynamicBindingExample {
    public static void main(String[] args) {
        Animal animal = new Dog();
        animal.sound();  // Outputs: "Dog barks"
    }
}

Pros and Cons of Java’s Dynamic Features

Performance Cost: Runtime loading, verification, and binding introduce slight overhead.
Enhanced Flexibility: Enables runtime decisions, dynamic plugins, and extensible designs without recompilation.

Interface-Driven Runtime Decisions

Using interfaces allows runtime determination of implementations:

public interface PaymentService { void pay(); }

public class CreditCardPayment implements PaymentService {
    public void pay() { System.out.println("Paying with Credit Card"); }
}

public class PayPalPayment implements PaymentService {
    public void pay() { System.out.println("Paying with PayPal"); }
}

public class PaymentProcessor {
    public static void main(String[] args) throws Exception {
        String paymentType = "CreditCardPayment"; // This could come from config or user input
        PaymentService paymentService = (PaymentService)
            Class.forName("com.example." + paymentType)
                 .getDeclaredConstructor().newInstance();

        paymentService.pay();  // "Paying with Credit Card"
    }
}

Java Object Layout and JOL

Java Object Layout (JOL) helps developers understand object memory structures:

Object Header: Metadata (hash code, garbage collection info, lock states).
Instance Fields: Object’s actual data.
Padding: Ensures memory alignment (typically multiples of 8 bytes).

Using JOL Library

You can use the JOL library to inspect these details. Add the dependency:

dependencies {
    implementation 'org.openjdk.jol:jol-core:0.16'
}

Then, observe the layout:

import org.openjdk.jol.info.ClassLayout;

class SimpleObject {
    int intField;
    long longField;
    byte byteField;
    Object refField;
}

public class JolTest {
    public static void main(String[] args) {
        SimpleObject obj = new SimpleObject();

        System.out.println("Before hashCode():");
        System.out.println(ClassLayout.parseInstance(obj).toPrintable());

        // Calling hashCode() can trigger its computation and storage in the Mark Word
        obj.hashCode();

        System.out.println("After hashCode():");
        System.out.println(ClassLayout.parseInstance(obj).toPrintable());
    }
}

Running this code will show the internal layout of SimpleObject. The output before and after calling obj.hashCode() might reveal changes in the object's Mark Word, as the hash code, if not already computed, gets stored there.

Object Header

Mark Word: Stores hash codes, GC status (age bits), synchronization states (lock information). Its structure can change depending on the object's state.
Class Pointer (Klass Pointer): References class metadata in the Method Area, linking the object instance to its class definition.

Conclusion

Java’s ClassLoader and dynamic class loading system enable JVM’s platform-independent and extensible runtime environment. By loading, verifying, initializing, and binding classes on-demand, Java strikes a balance between performance and flexibility, making it ideal for complex, secure applications. A deep understanding of these internals transforms your role from a Java developer into a confident operator of the JVM.

DEV Community: Sanha Ko

Netty 내부 동작 원리로 파헤친 WebClient 초기 지연 이슈

원인 파악을 위한 가정

WebClient 실행 메커니즘

Cold Sequence와 구독 시점

TaskQueue로의 전달

Netty EventLoop 스레드의 동작 원리

User Space와 Kernel Space

Multiplexing I/O와 Selector

Selector.select()의 실제 동작

NioEventLoop의 구조

1. select() - I/O 이벤트 감지

TaskQueue가 비었을 때

TaskQueue가 있을 때

select() 호출 이후의 내부 동작

EPollSelectorImpl 인스턴스는 언제 생성되는가?

epoll의 세 가지 시스템 콜

2. processSelectedKeys() - I/O 이벤트 처리

3. runAllTasks() - Non-I/O Task 처리

전체 흐름 요약

또 다른 가설: Parallel Scheduler 스레드 경합

검증

테스트 환경

Case 1: CPU 코어 10개 (refineAddress_concurrency10_cpu10)

Case 2: CPU 코어 2개 (refineAddress_concurrency10_cpu2)

결과

지연의 원인: Cold Start

Cold Start 해결책

Connection Pool에 사전 커넥션 생성

Warmup 옵션

마무리

AI 브라우저를 활용한 PR 메세지 자동화

1. 좋은 Pull Request 란?

좋은 PR의 구성요소

2. 현재 AI Assistant의 한계: '맥락'의 부재

3. Jira 티켓에서 맥락 가져오기

작업 전 Jira 티켓을 풍부하게 작성하면 좋은점

4. AI 브라우저로 워크플로우 완성하기

자동화 워크플로우

PR 자동 생성에 사용한 프롬프트

Swagger의 사실과 오해: API-First Development

무엇이 문제인가

OpenAPI Specification이란?

OAS를 통한 API-First 실천

Git 서브모듈 추가 방법

OpenAPI Generator 인터페이스 자동 생성

커스텀 Mustache 템플릿

마무리

Resilience4j Bulkhead 패턴: 대용량 데이터 처리 안정성 높이기

Bulkhead 패턴이란

Resilience4j를 사용한 Bulkhead 패턴 적용

의존성 추가

구현 예시

SEMAPHORE vs THREADPOOL

SemaphoreBulkhead

ThreadPoolBulkhead

언제 뭘 사용해야 할까

마무리

Solving the Billion-Dollar Mistake: Modern Java Null Safety with JSpecify and NullAway

NullPointerException: Why Is It Still a Problem?

JSpecify: A Standard for Explicit Null Safety

Adding the JSpecify Dependency

Improving Readability: Setting Defaults with @NullMarked

Build-Time Verification: Strengthening Null Safety with NullAway

JSpecify in the Spring Ecosystem

The Future of Null Safety in Java

Conclusion

10억 달러짜리 실수 해결하기: JSpecify와 NullAway를 사용한 최신 Java Null 안전성

NullPointerException: 왜 여전히 문제인가?

JSpecify: 명시적인 Null 안전성을 향한 표준

JSpecify 의존성 추가

가독성 향상: @NullMarked로 기본값 설정하기

빌드 시간 검증: NullAway로 Null 안전성 강화하기

Spring 생태계에서의 JSpecify

앞으로의 Java의 Null 안전성

마무리

PostgreSQL MVCC Internals: From xmin/xmax to Isolation Levels

How PostgreSQL Implements MVCC

How MySQL (InnoDB) Implements MVCC

Visibility in PostgreSQL by Isolation Level

Improving Readability: Setting Defaults with `@NullMarked`

가독성 향상: `@NullMarked`로 기본값 설정하기

1. `Tx A` starts (TXID: 100) and executes its first `SELECT`.