Spring WebFlux 스트리밍 처리 완전 가이드

🤔 스트리밍이란 무엇인가?

일상생활 비유로 이해하기

🚰 수도꼭지 vs 🪣 물통

기존 방식 (물통):
1. 큰 물통에 물을 가득 채움
2. 물통이 다 찰 때까지 기다림  
3. 물통을 들고 이동 (무거움!)
4. 한 번에 모든 물을 사용

스트리밍 (수도꼭지):
1. 수도꼭지를 틀어놓음
2. 물이 조금씩 계속 나옴
3. 필요한 만큼만 받아서 바로 사용
4. 사용한 물은 바로 버림 (가벼움!)

 

 

 

💾 메모리 관점에서 보는 스트리밍

기존 방식 (전체 로드)

// 🪣 물통 방식: 모든 데이터를 한 번에 메모리에 저장
String 거대한JSON = "{ 50만개 데이터... }"; // 200MB 메모리 점유!

// 메모리 상황:
// ████████████████████████ (200MB 사용 중)
// 사용자: "아직 파싱도 안 했는데 벌써 200MB나 써요!"

 

 

 

스트리밍 방식 (조금씩 처리)

 

// 🚰 수도꼭지 방식: 8KB씩 받아서 바로 처리
while (hasMoreData) {
    byte[] 작은청크 = readNextChunk(); // 8KB만 메모리 사용
    process(작은청크);                  // 바로 처리
    작은청크 = null;                   // 즉시 메모리 해제!
}

// 메모리 상황:
// █ (8KB만 사용) → 처리 → 해제 → █ (다음 8KB) → 처리 → 해제...
// 사용자: "계속 8KB만 사용하네요!"

 

 

 

 

🔄 실제 코드로 보는 차이점

1. 기존 방식 (Non-Streaming)

// ❌ 한 번에 모든 데이터를 메모리에 로드
public AJAX_RES 기존방식(String url) {
    // 1단계: 전체 JSON을 String으로 받음 (200MB!)
    String 전체JSON = webClient
        .get()
        .uri(url)
        .retrieve()
        .bodyToMono(String.class)  // ← 여기서 200MB 메모리 점유
        .block();
    
    // 2단계: 전체 JSON을 파싱 (400MB 추가!)
    AJAX_RES result = objectMapper.readValue(전체JSON, AJAX_RES.class);
    
    // 총 메모리: 200MB + 400MB = 600MB 사용 중!
    return result;
}

 

 

 

 

2. 스트리밍 방식 (Streaming)

// ✅ 조금씩 받아서 바로 처리
public AJAX_RES 스트리밍방식(String url) {
    return webClient
        .get()
        .uri(url)
        .retrieve()
        .bodyToFlux(DataBuffer.class)  // ← 8KB 청크로 받음
        .collectList()                 // 청크들만 모음 (String 변환 안함)
        .map(청크들 -> {
            // 청크들을 스트림으로 바로 파싱
            InputStream stream = 청크들을스트림으로변환();
            AJAX_RES result = objectMapper.readValue(stream, AJAX_RES.class);
            청크들을즉시해제(); // 메모리 해제!
            return result;
        })
        .block();
    
    // 총 메모리: 400MB만 사용! (200MB 절약)
}

 

 

📊 DataBuffer와 청크 개념

DataBuffer란?

 

// DataBuffer = 작은 데이터 조각 (보통 8KB)
DataBuffer chunk1 = { "id": 1, "name": "홍길동" }     // 8KB
DataBuffer chunk2 = { "id": 2, "name": "김철수" }     // 8KB  
DataBuffer chunk3 = { "id": 3, "name": "이영희" }     // 8KB
// ...
// DataBuffer chunk25000 = 마지막 조각                // 8KB

// 전체 데이터 = chunk1 + chunk2 + ... + chunk25000 = 200MB

 

 

 

청크 처리 과정

// 1. 청크들을 하나씩 받음
Flux<DataBuffer> 청크스트림 = webClient...bodyToFlux(DataBuffer.class);

// 2. 청크들을 리스트로 모음 (아직 String 변환 안함!)
List<DataBuffer> 청크리스트 = 청크스트림.collectList().block();

// 3. 청크들을 InputStream으로 연결
InputStream 연결된스트림 = new SequenceInputStream(
    청크1의InputStream,
    청크2의InputStream,
    청크3의InputStream,
    // ...
);

// 4. Jackson 파서가 스트림에서 직접 읽어서 객체 생성
AJAX_RES result = objectMapper.readValue(연결된스트림, AJAX_RES.class);

// 5. 사용한 청크들 즉시 해제
청크리스트.forEach(DataBufferUtils::release); // 메모리 해제!

 

 

 

🧠 스트리밍의 핵심 아이디어

"필요할 때만, 조금씩, 바로 버리기"

// 🎯 핵심 원리
while (데이터가_더_있나요?) {
    작은조각 = 다음_8KB_받기();           // 1. 조금만 받기
    처리결과 = 즉시_처리(작은조각);        // 2. 바로 처리  
    작은조각 = null;                    // 3. 즉시 버리기
    // 메모리는 계속 8KB만 사용!
}

 

 

왜 메모리가 절약될까?

// 기존 방식: 동시에 메모리에 존재
String 원본JSON = "200MB 데이터";      // 200MB 점유
AJAX_RES 파싱결과 = parse(원본JSON);    // 400MB 추가 점유
// 총 600MB 동시 사용!

// 스트리밍: 순차적으로 처리
// 시점 1: 청크1 처리 (8KB 사용)
// 시점 2: 청크1 해제, 청크2 처리 (8KB 사용)  
// 시점 3: 청크2 해제, 청크3 처리 (8KB 사용)
// ...
// 최종: 파싱결과만 남음 (400MB 사용)
// 총 400MB만 사용! (200MB 절약)

 

 

🔧 실제 구현에서 중요한 부분들

1. DataBuffer 해제 (메모리 누수 방지)

// ⚠️ 위험: DataBuffer를 해제하지 않으면 메모리 누수!
List<DataBuffer> buffers = ...;
// 사용 후 반드시 해제해야 함!

// ✅ 안전: 반드시 해제하기
try {
    // 데이터 처리...
} finally {
    buffers.forEach(DataBufferUtils::release); // 필수!
}

 

 

 

2. SequenceInputStream 사용

// 여러 청크를 하나의 스트림으로 연결
List<InputStream> 개별스트림들 = buffers.stream()
    .map(buffer -> new ByteArrayInputStream(buffer에서_바이트_추출()))
    .collect(toList());

// 마법! 여러 스트림을 하나로 연결
InputStream 하나로_연결된_스트림 = new SequenceInputStream(
    Collections.enumeration(개별스트림들)
);

// Jackson이 하나의 연속된 JSON으로 인식!
AJAX_RES result = objectMapper.readValue(하나로_연결된_스트림, AJAX_RES.class);

 

 

3. Jackson 스트리밍 파서

 

// 일반 파서: String 전체를 메모리에 로드 후 파싱
AJAX_RES result = objectMapper.readValue(거대한_JSON_문자열, AJAX_RES.class);

// 스트리밍 파서: 스트림에서 조금씩 읽어서 파싱
JsonFactory factory = new JsonFactory();
JsonParser parser = factory.createParser(inputStream);
AJAX_RES result = objectMapper.readValue(parser, AJAX_RES.class);
// JSON 문자열을 메모리에 저장하지 않음!

 

 

🎭 스트리밍 vs Non-Streaming 비교

측면                                     Non-Streaming                                    Streaming

메모리 사용	📈 많음 (600MB)	📉 적음 (400MB)
처리 방식	🪣 한 번에 모두	🚰 조금씩 계속
코드 복잡도	😊 간단	😅 복잡
에러 처리	🎯 명확	🌀 복잡
디버깅	🔍 쉬움	🕵️ 어려움
성능	⚡ 빠름 (메모리 충분 시)	🐢 적당

🎯 언제 스트리밍을 써야 할까?

✅ 스트리밍을 써야 하는 경우

 

if (데이터_크기 > 사용가능_메모리 * 0.5) {
    return "스트리밍 사용하세요!";
}

if (OutOfMemoryError가_자주_발생) {
    return "스트리밍이 답입니다!";
}

 

 

❌ 스트리밍을 피해야 하는 경우

 

if (데이터_크기 < 10MB) {
    return "굳이 복잡하게 하지 마세요";
}

if (개발_속도가_중요) {
    return "일단 간단하게 하고 나중에 최적화";
}

🚀 마무리: 스트리밍의 본질

 

스트리밍 = "큰 것을 작게 나누어 순차 처리"

🎬 영화 스트리밍 (Netflix)
- 2시간 영화를 통째로 다운로드 ❌
- 10초씩 받아서 바로 재생 ✅

🌊 데이터 스트리밍 (우리 코드)  
- 200MB JSON을 통째로 로드 ❌
- 8KB씩 받아서 바로 파싱 ✅

핵심은 "메모리를 적게 쓰면서도 같은 결과를 얻기"입니다!복잡해 보이지만, 결국은 "조금씩 받아서 바로 처리하고 버리기"라는 단순한 아이디어예요! 

 

 

 

 

---

Spring WebFlux 스트리밍 처리 완전 가이드

대용량 데이터 처리 시 메모리 최적화 전략

작성일: 2025년 9월 26일
작성자: Backend Developer
주제: Spring WebFlux, 메모리 최적화, 스트리밍 처리

---

🚀 들어가며

최근 프로젝트에서 50만건의 출입 이벤트 로그를 Excel로 다운로드하는 기능을 구현하면서, 심각한 메모리 문제에 직면했습니다. 기존 방식으로는 1.2GB의 메모리를 사용하며, OutOfMemoryError가 빈번하게 발생했습니다.

이 글에서는 Spring WebFlux의 스트리밍 처리를 통해 메모리 사용량을 최적화하는 방법과, 그 한계점에 대해 실무 경험을 바탕으로 정리해보겠습니다.

---

📊 문제 상황 분석

기존 코드의 메모리 사용 패턴

// 기존 방식: 전체 데이터를 메모리에 로드
@Service
public class AccessEventLogService {

    public byte[] excelDownload(ExternalAccessEventLogTableReqDTO reqDTO) throws Exception {
        // 1단계: API 호출로 JSON 데이터 수신 (200MB)
        String raw = webClient
            .post()
            .uri("/api/access-events")
            .bodyValue(reqDTO)
            .retrieve()
            .bodyToMono(String.class)  // ← 전체 JSON을 String으로 메모리 로드
            .block(Duration.ofSeconds(30));

        // 2단계: JSON → Java 객체 변환 (400MB 추가)
        AJAX_RES result = objectMapper.readValue(raw, AJAX_RES.class);

        // 3단계: Excel 파일 생성 (추가 메모리 사용)
        return createExcelFile(result.getData());
    }
}

메모리 사용량 분석

구성 요소	메모리 사용량	설명
JSON 원본 문자열	200MB	String raw 변수
파싱된 Java 객체	400MB	50만개 AccessEventLogDTO
JVM 오버헤드	600MB	String 오버헤드, 객체 헤더, Collection 등
총 메모리 사용량	1.2GB	피크 메모리 사용량

---

🧠 JVM 메모리 오버헤드 이해하기

Java String의 실제 메모리 사용량

// 단순해 보이는 String 하나
String eventDate = "2025-09-26 10:30:00"; // 19 characters

// 실제 JVM 메모리에서는:
// 1. String 객체 헤더: 16 bytes
// 2. char[] 배열 헤더: 16 bytes  
// 3. char[] 데이터: 19 × 2 = 38 bytes (UTF-16 인코딩)
// 4. 메모리 정렬 패딩: 2 bytes
// 총: 72 bytes (원본 데이터의 3.8배!)

객체 오버헤드 계산

// 50만개의 AccessEventLogDTO 객체
public class AccessEventLogDTO {
    private String eventDate;    // 8 bytes (참조) + String 오버헤드
    private String deviceId;     // 8 bytes (참조) + String 오버헤드  
    private String deviceName;   // 8 bytes (참조) + String 오버헤드
    // ... 총 12개 필드

    // 각 객체당 오버헤드:
    // - Object 헤더: 16 bytes
    // - 필드 참조: 12 × 8 = 96 bytes  
    // - 메모리 정렬: 16 bytes
    // 총: 128 bytes per object
}

// 500,000 객체 × 128 bytes = 64MB (객체 헤더만)
// + String 오버헤드: 300MB
// + Collection 오버헤드: 50MB
// = 총 414MB의 순수 오버헤드!

---

🌊 Spring WebFlux 스트리밍 처리 도입

1단계: 기본 스트리밍 (가짜 스트리밍)

// ❌ 잘못된 접근: 결국 전체 문자열을 메모리에 로드
public String fetchDataWithFakeStreaming(DiApiReqDTO reqDTO) {
    return webClient
        .post()
        .uri("/api/access-events")
        .bodyValue(reqDTO)
        .retrieve()
        .bodyToFlux(DataBuffer.class)  // 청크로 받지만...
        .map(dataBuffer -> {
            byte[] bytes = new byte[dataBuffer.readableByteCount()];
            dataBuffer.read(bytes);
            DataBufferUtils.release(dataBuffer);
            return new String(bytes, StandardCharsets.UTF_8);
        })
        .collect(Collectors.joining())  // ← 결국 여기서 전체 합치기!
        .block();
}

문제점: collect(Collectors.joining())에서 결국 전체 문자열을 메모리에 로드하므로 기존과 동일한 메모리 사용량

2단계: 진짜 스트리밍 처리

// ✅ 올바른 접근: JSON 스트리밍 파서 사용
public AJAX_RES fetchDataWithRealStreaming(DiApiReqDTO reqDTO) {
    return webClient
        .post()
        .uri("/api/access-events")
        .bodyValue(reqDTO)
        .retrieve()
        .bodyToFlux(DataBuffer.class)
        .collectList()  // DataBuffer 청크들만 수집
        .map(dataBuffers -> {
            try {
                // 청크들을 InputStream으로 변환
                List<InputStream> inputStreams = dataBuffers.stream()
                    .map(db -> {
                        byte[] bytes = new byte[db.readableByteCount()];
                        db.read(bytes);
                        return new ByteArrayInputStream(bytes);
                    })
                    .collect(Collectors.toList());

                InputStream combinedStream = new SequenceInputStream(
                    Collections.enumeration(inputStreams)
                );

                // Jackson 스트리밍 파서로 직접 파싱
                JsonFactory factory = new JsonFactory();
                JsonParser parser = factory.createParser(combinedStream);
                AJAX_RES result = objectMapper.readValue(parser, AJAX_RES.class);

                // 즉시 버퍼 해제
                dataBuffers.forEach(DataBufferUtils::release);

                return result;

            } catch (Exception e) {
                throw new RuntimeException("JSON 스트리밍 파싱 실패", e);
            }
        })
        .block(Duration.ofSeconds(30));
}

3단계: 메모리 해제 최적화

// ✅ 즉시 메모리 해제 패턴
public AJAX_RES optimizedDataFetch(DiApiReqDTO reqDTO) {
    log.info("메모리 사용량 (시작): {:.2f} GB", getUsedMemoryGB());

    AJAX_RES result = fetchDataWithRealStreaming(reqDTO);
    log.info("메모리 사용량 (파싱 후): {:.2f} GB", getUsedMemoryGB());

    // 강제 가비지 컬렉션 (대용량 처리 시에만 권장)
    System.gc();
    Thread.sleep(100); // GC 완료 대기
    log.info("메모리 사용량 (GC 후): {:.2f} GB", getUsedMemoryGB());

    return result;
}

private double getUsedMemoryGB() {
    Runtime runtime = Runtime.getRuntime();
    long usedMemory = runtime.totalMemory() - runtime.freeMemory();
    return usedMemory / (1024.0 * 1024.0 * 1024.0);
}

---

📈 성능 비교 및 측정 결과

메모리 사용량 비교

처리 방식	JSON 문자열	파싱된 객체	JVM 오버헤드	총 메모리
기존 방식	200MB	400MB	600MB	1.2GB
가짜 스트리밍	200MB	400MB	600MB	1.2GB
진짜 스트리밍	0MB	400MB	300MB	700MB
페이징 처리	0MB	8MB	42MB	50MB

실제 측정 로그

2025-09-26 10:30:00 INFO  메모리 사용량 (시작): 0.15 GB
2025-09-26 10:30:05 INFO  메모리 사용량 (파싱 후): 0.68 GB  
2025-09-26 10:30:06 INFO  메모리 사용량 (GC 후): 0.65 GB

---

⚠️ 스트리밍 처리의 한계점

1. 근본적 한계: 객체 생성은 불가피

// 50만개의 AccessEventLogDTO 객체는 어떤 방식을 써도 생성해야 함
List<AccessEventLogDTO> eventLogs = new ArrayList<>(); // 50만개 객체 + 오버헤드

// 각 객체의 String 필드들도 동일하게 생성
eventLog.setEventDate("2025-09-26 10:30:00"); // 여전히 72 bytes 오버헤드

2. 복잡성 증가

• 코드 복잡도: Jackson 스트리밍 API 학습 필요
• 디버깅 어려움: 스트림 처리 중 오류 추적 복잡
• 유지보수 비용: 일반적인 Spring Boot 패턴과 다름

3. 제한적 효과

스트리밍으로 절약되는 메모리: JSON 원본 문자열 200MB
여전히 사용되는 메모리: 파싱된 객체 + 오버헤드 500MB
총 절약 효과: 1.2GB → 700GB (약 42% 절약)

---

🎯 실무에서의 선택 기준

스트리밍을 도입해야 하는 경우

// ✅ 스트리밍이 효과적인 경우
if (expectedDataSize > availableMemory * 0.7) {
    // 메모리 부족이 예상되는 경우
    return useStreamingApproach();
}

if (isFrequentLargeDataProcessing()) {
    // 대용량 데이터 처리가 빈번한 경우  
    return useStreamingApproach();
}

스트리밍을 피해야 하는 경우

// ❌ 스트리밍이 과도한 경우
if (dataSize < maxHeapSize * 0.3) {
    // 메모리 여유가 충분한 경우
    return useSimpleApproach();
}

if (isDevelopmentPhase()) {
    // 개발 단계에서는 단순함이 우선
    return useSimpleApproach(); 
}

---

💡 대안적 해결책들

1. JVM 힙 메모리 증설

# 기존: 4GB
java -Xmx4g -jar application.jar

# 증설: 8GB  
java -Xmx8g -jar application.jar

장점: 코드 변경 없음, 즉시 적용 가능
단점: 서버 리소스 비용 증가

2. 데이터 제한 정책

// 사용자에게 명확한 제한 안내
@GetMapping("/excel-download")
public ResponseEntity<?> downloadExcel(@RequestParam int maxRecords) {
    if (maxRecords > 100000) {
        return ResponseEntity.badRequest()
            .body("최대 10만건까지만 다운로드 가능합니다.");
    }

    // 처리 로직...
}

3. 페이징 + 다중 파일 생성

// 10만건씩 나누어 여러 Excel 파일 생성
public List<String> createMultipleExcelFiles(RequestDTO reqDTO) {
    List<String> fileUrls = new ArrayList<>();
    int pageSize = 100000;

    for (int page = 0; page < getTotalPages(reqDTO, pageSize); page++) {
        String fileUrl = createExcelForPage(reqDTO, page, pageSize);
        fileUrls.add(fileUrl);
    }

    return fileUrls; // 다운로드 링크 목록 반환
}

---

🔧 실제 구현 코드

완성된 스트리밍 서비스

@Service
@Slf4j
public class StreamingApiService {

    private final WebClient webClient;
    private final ObjectMapper objectMapper;

    public StreamingApiService(WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder
            .codecs(configurer -> configurer
                .defaultCodecs()
                .maxInMemorySize(50 * 1024 * 1024)) // 50MB로 제한
            .build();
        this.objectMapper = new ObjectMapper();
    }

    public AJAX_RES fetchLargeDataWithStreaming(DiApiReqDTO reqDTO) {
        log.info("대용량 데이터 스트리밍 처리 시작 - URL: {}", reqDTO.getUrl());

        Instant startTime = Instant.now();
        double initialMemory = getUsedMemoryGB();

        try {
            AJAX_RES result = webClient
                .post()
                .uri(reqDTO.getUrl())
                .headers(h -> setAuthHeaders(h, reqDTO))
                .bodyValue(reqDTO.getRequest())
                .retrieve()
                .bodyToFlux(DataBuffer.class)
                .collectList()
                .map(this::parseJsonStream)
                .doOnSuccess(res -> forceGarbageCollection())
                .block(Duration.ofSeconds(60));

            // 성능 메트릭 로깅
            logPerformanceMetrics(startTime, initialMemory, reqDTO.getUrl());

            return result;

        } catch (Exception e) {
            log.error("스트리밍 처리 중 오류 발생: {}", e.getMessage(), e);
            throw new RuntimeException("대용량 데이터 처리 실패", e);
        }
    }

    private AJAX_RES parseJsonStream(List<DataBuffer> dataBuffers) {
        try (InputStream combinedStream = createCombinedInputStream(dataBuffers)) {

            JsonFactory factory = new JsonFactory();
            JsonParser parser = factory.createParser(combinedStream);

            return objectMapper.readValue(parser, AJAX_RES.class);

        } catch (IOException e) {
            throw new RuntimeException("JSON 스트리밍 파싱 실패", e);
        } finally {
            // DataBuffer 해제
            dataBuffers.forEach(DataBufferUtils::release);
        }
    }

    private InputStream createCombinedInputStream(List<DataBuffer> dataBuffers) {
        List<InputStream> inputStreams = dataBuffers.stream()
            .map(db -> {
                byte[] bytes = new byte[db.readableByteCount()];
                db.read(bytes);
                return new ByteArrayInputStream(bytes);
            })
            .collect(Collectors.toList());

        return new SequenceInputStream(Collections.enumeration(inputStreams));
    }

    private void forceGarbageCollection() {
        System.gc();
        try {
            Thread.sleep(100); // GC 완료 대기
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    private void logPerformanceMetrics(Instant startTime, double initialMemory, String url) {
        Duration processingTime = Duration.between(startTime, Instant.now());
        double finalMemory = getUsedMemoryGB();
        double memoryIncrease = finalMemory - initialMemory;

        log.info("스트리밍 처리 완료 - URL: {}, 처리시간: {}ms, 메모리 증가: {:.2f}GB", 
            url, processingTime.toMillis(), memoryIncrease);
    }

    private double getUsedMemoryGB() {
        Runtime runtime = Runtime.getRuntime();
        long usedMemory = runtime.totalMemory() - runtime.freeMemory();
        return usedMemory / (1024.0 * 1024.0 * 1024.0);
    }
}

---

📚 결론 및 권장사항

핵심 인사이트

1. 스트리밍은 은총알이 아니다: JSON 원본 문자열만 절약될 뿐, 파싱된 객체의 메모리 사용량은 동일
2. JVM 오버헤드는 예상보다 크다: 실제 데이터의 2-3배 메모리 사용
3. 복잡성 vs 효과 트레이드오프: 500MB 절약을 위해 복잡한 코드 작성이 가치 있는가?

실무 적용 가이드라인

graph TD
    A[대용량 데이터 처리 필요] --> B{데이터 크기 예측}
    B -->|< 100MB| C[기존 방식 유지]
    B -->|100MB - 500MB| D{메모리 여유도 확인}
    B -->|> 500MB| E[페이징 처리 필수]

    D -->|여유 있음| F[JVM 힙 증설]
    D -->|여유 없음| G[스트리밍 도입]

    C --> H[단순함 우선]
    F --> I[비용 vs 개발시간]
    G --> J[복잡성 감수]
    E --> K[근본적 해결]

최종 권장사항

1. 10만건 이하: 기존 방식 유지
2. 10-50만건: JVM 힙 메모리 증설 (4GB → 8GB)
3. 50만건 이상: 페이징 처리 + 다중 파일 다운로드
4. 스트리밍 도입: 메모리가 절대적으로 부족하고, 복잡성을 감수할 수 있는 경우만

💬 피드백: 이 글에 대한 의견이나 질문이 있으시면 언제든 댓글로 남겨주세요!