Java/Kotlin 엑셀 보고서 생성 방식 비교 - Apache POI, JXLS, TBEG

황용호·2026년 10월 21일

🇺🇸 English version

기획서에 "엑셀 다운로드" 한 줄이 추가되면, 개발자가 감당할 작업량은 그 한 줄보다 훨씬 큽니다.

데이터를 표 형태로 출력하는 것이 전부라면 CSV로 충분합니다. 그런데 실제 요구사항은 대개 그렇지 않습니다. 회사 로고가 삽입된 머리글, 병합된 제목 셀, 항목별로 다른 배경색, 합계 행의 수식, 하단의 차트. 그리고 그 양식은 이미 기획자나 디자이너가 엑셀로 작성해 전달한 상태입니다.

JVM 환경에서 이 요구를 처리하는 세 가지 방법을 비교하고, 각 방법이 적합한 조건과 그렇지 않은 조건을 함께 정리합니다.

이해관계 고지 - 필자는 비교 대상 중 TBEG의 개발자입니다. 기능 비교는 JXLS 3.1.0을 직접 구동해 산출물을 확인한 실측에 근거하고, 성능은 동일 장비, 동일 워크로드에서 측정한 수치를 그대로 게재합니다. 측정 원본과 재현 조건은 글 끝에 링크로 제시합니다.

접근 방식의 두 유형

코드로 생성하는 방식과 템플릿에 데이터를 바인딩하는 방식입니다.

전자는 Apache POI로 셀을 하나씩 생성하고 스타일을 지정합니다. 후자는 완성된 엑셀 파일을 템플릿으로 사용하고, 그 안에 표시한 자리에 데이터를 바인딩합니다. 템플릿 방식 중에서는 JXLS가 가장 오래되었고, TBEG은 최근에 등장한 선택지입니다.

Apache POI 직접 구현

가장 근본적인 방법입니다. 다른 두 라이브러리도 내부적으로는 모두 POI를 사용합니다.

Workbook wb = new XSSFWorkbook();
Sheet sheet = wb.createSheet("직원목록");

CellStyle header = wb.createCellStyle();
Font bold = wb.createFont();
bold.setBold(true);
header.setFont(bold);
header.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex());
header.setFillPattern(FillPatternType.SOLID_FOREGROUND);
header.setBorderBottom(BorderStyle.THIN);

Row r0 = sheet.createRow(0);
String[] titles = {"부서", "이름", "직급"};
for (int i = 0; i < titles.length; i++) {
    Cell c = r0.createCell(i);
    c.setCellValue(titles[i]);
    c.setCellStyle(header);
}

머리글에 배경색을 지정하는 데만 여섯 줄이 필요합니다. 여기에 병합, 테두리, 숫자 서식, 열 너비, 이미지, 차트가 더해지면 코드는 수백 줄 규모로 증가합니다. 그리고 디자이너가 색상을 변경하면 코드를 수정해야 합니다.

POI가 적합한 조건은 분명히 존재합니다. 양식이 단순하고 변경 가능성이 낮을 때, 서식보다 데이터 자체가 중요할 때, 의존성을 최소로 유지해야 할 때입니다. 의존성을 추가하는 것보다 30줄을 직접 작성하는 편이 나은 경우는 실제로 많습니다.

대용량은 SXSSFWorkbook으로 대응합니다. 메모리에 유지할 행 수를 지정하고 나머지는 디스크로 배출하는 방식이라 수십만 행도 처리됩니다. 다만 이미 기록된 행은 수정할 수 없습니다.

JXLS - 셀 메모 기반 명령 지정

JXLS는 이 분야에서 가장 오래되고 널리 사용되는 라이브러리입니다. 현재 3.1.0, Apache 2.0 라이선스입니다.

템플릿 셀에는 ${e.name} 처럼 표현식을 기재합니다. 반복 같은 명령은 엑셀의 셀 메모(주석)에 배치합니다.

셀 A1 텍스트: ${e.department}
셀 A1 메모:   jx:each(items="employees" var="e" lastCell="C2")

호출 코드는 다음과 같습니다.

Map<String, Object> data = new HashMap<>();
data.put("employees", employees);

JxlsPoiTemplateFillerBuilder.newInstance()
    .withTemplate("template.xlsx")
    .build()
    .fill(data, new File("report.xlsx"));

JXLS의 강점은 두 가지입니다.

하나는 성숙도입니다. 10년 넘게 사용되었고, 적용 사례와 트러블슈팅 자료가 축적되어 있습니다. 문제가 발생하였을 때 참조할 선례가 있습니다. 팀 규모가 크거나 장기 유지보수가 중요한 프로젝트라면 이 조건의 가치는 큽니다.

다른 하나는 데이터 변환 문법의 표현력입니다. 조건에 따라 영역 단위로 표시하거나 은닉하는 jx:if, 데이터를 그룹으로 묶어 반복하는 groupBy, 템플릿에 없던 표를 런타임에 생성하는 jx:grid, 반복으로 시트 자체를 생성하는 기능, 마스터-디테일 형태의 중첩 반복까지 선언적으로 지원합니다. 수식 영역에도 서로 떨어진 범위를 결합하는 jointed 참조(U_())나 변수를 삽입하는 파라미터화 수식($[...]) 같은 고유 문법이 있습니다.

약점은 명령의 비가시성입니다. 셀 메모는 포인터를 올려야 표시됩니다. 템플릿을 열어도 어디에 어떤 명령이 지정되어 있는지 일괄 확인되지 않고, lastCell 범위가 어긋나면 원인 추적에 시간이 소요됩니다. 디자이너가 작성한 양식에 개발자가 메모를 기재해야 하는데, 이후 디자이너가 파일을 다시 편집하면 메모가 소실되는 사례도 발생합니다.

TBEG - 셀 텍스트 기반 마커 지정

TBEG는 Kotlin으로 작성된 최근 라이브러리입니다. 현재 1.2.5, Maven Central에 io.github.jogakdal:tbeg로 배포되어 있습니다.

접근이 다릅니다. 명령을 메모가 아니라 셀 텍스트에 직접 기재합니다.

셀 A3: ${emp.department}
셀 B3: ${emp.name}
셀 C3: ${emp.position}
셀 A5: ${repeat(employees, A3:C3, emp)}
ExcelGenerator().use { generator ->
    val bytes = generator.generate(template, data)
}

Spring Boot에서는 ExcelGenerator가 Bean으로 자동 등록됩니다.

강점은 템플릿의 가독성입니다. 파일을 열면 어느 자리에 무엇이 배치되는지 그대로 확인됩니다. 디자이너에게 "이 셀에 이렇게 써 주세요"라고 설명하기도 쉽고, 파일을 다시 편집해도 마커가 텍스트라 소실되지 않습니다. 이미지 삽입(${image(...)}), 반복 시 셀 자동 병합(${merge(...)}), 조건부 필드 은닉, 차트/피벗의 범위 자동 반영 같은 기능이 있습니다.

약점은 명확합니다. 새 라이브러리입니다. 실무 적용 사례가 거의 공개되지 않았고, 문제 발생 시 참조할 선례가 없습니다. 장기 유지보수가 최우선인 프로젝트라면 이 조건을 중요하게 평가해야 합니다. 반대로 신규 프로젝트에서 템플릿 유지보수 비용의 절감이 중요하다면 검토할 수 있습니다.

세 방식의 분기점 - 명령의 배치 위치

세 방식의 차이는 다음 한 가지로 요약됩니다.

서식을 정의하는 곳반복/조건을 정의하는 곳
Apache POI코드코드
JXLS템플릿 파일템플릿 파일의 셀 메모
TBEG템플릿 파일템플릿 파일의 셀 텍스트

사소해 보이지만 운영 단계에서는 차이가 큽니다. 양식이 자주 변경되는 프로젝트에서 템플릿을 열었을 때 구조가 즉시 파악되는지 여부가 유지보수 비용을 결정합니다.

기능 비교 - 공통 지원과 분기 항목

두 라이브러리를 동일한 템플릿으로 구동하면 지원 항목과 미지원 항목이 명확히 분기합니다.

양쪽 모두 지원하는 항목을 먼저 정리합니다. 세로/가로 반복 확장, 열 폭과 행 높이를 포함한 레이아웃 보존, 확장량만큼 하단 요소를 이동시키는 시프트, 수식 범위 자동 조정(=SUM(C3)이 =SUM(C3:C5)로), 수식 내 변수 삽입, 다른 시트를 참조하는 수식의 조정, 조건부 서식과 데이터 유효성 범위 확장, 이미지 삽입, 병합 셀, SXSSF 스트리밍. 여기까지는 양쪽 모두 지원합니다.

분기 항목은 다음과 같습니다. 판정은 모두 실측입니다.

항목JXLS 3.1.0TBEG 1.2.5
선언적 조건 분기 (jx:if)지원코드에서 데이터를 필터링하여 대응
그룹 반복 (groupBy)지원선언적 문법 없음
중첩(마스터-디테일) 반복지원미지원
동적 그리드 / 동적 시트 생성지원미지원 (의도적)
가변 필드 테이블 (컬럼 은닉)헤더만 처리되어 열 정합 불일치헤더/합계까지 함께 제거
연속 동일값 자동 병합미지원지원
빈 컬렉션의 대체 콘텐츠미지원 (행만 삭제)지원
차트 범위 자동 조정수동 (동적 이름 범위 설정)자동
피벗 테이블파일 열기 시 새로고침캐시 재생성
스트리밍 중 전방 참조 수식미지원지원
비동기 생성없음코루틴/Future
Spring Boot 자동 설정없음있음
문서 메타데이터 / 열기 암호없음있음

요약하면 지향점이 다릅니다. JXLS는 데이터 변환 문법에, TBEG는 차트/피벗 등 엑셀 네이티브 요소의 자동 조정과 대용량/통합에 강점이 있습니다.

동적 그리드와 동적 시트 생성에 "의도적"이라고 부기한 이유는 해당 기능이 템플릿 기반이라는 전제와 상충하기 때문입니다. 디자이너가 작성한 고정 양식에 데이터를 바인딩하는 것이 목적이라면 템플릿에 없던 표를 런타임에 생성할 필요가 없습니다. 반대로 그 기능이 요구사항에 포함된다면 JXLS가 적합합니다.

대용량과 스트리밍

행 수가 수만 건을 초과하면 메모리가 제약이 됩니다. 세 가지 모두 Apache POI의 SXSSF로 대응하지만 적용 방식이 다릅니다.

POI는 SXSSFWorkbook을 직접 제어합니다. 제어 범위가 가장 넓지만 이미 기록된 행은 수정할 수 없습니다.

JXLS에서 스트리밍은 선택 사항이고 기본값은 비활성입니다. 공식 문서는 제약을 명시합니다. 1행의 수식이 2행의 데이터를 참조할 수 없다는 것으로, 2행이 아직 생성되지 않았기 때문입니다. 따라서 스트리밍은 전방 참조 수식이 없는 단순 데이터 리스트에만 적용할 수 있고, 템플릿마다 스트리밍 가능 여부를 검증해야 한다고 안내합니다. 데이터 하단에 합계 행을 두는 일반적인 양식이 이 제약에 해당합니다.

TBEG는 항상 스트리밍으로 동작하고, 수식 조정을 렌더링 이후 단계에서 수행합니다. 셀을 기록하기 전에 최종 위치를 산출하므로 아직 기록되지 않은 하단 행을 참조하는 수식도 정상 동작합니다. 피벗이 없으면 100만 행까지 처리합니다.

이 차이는 성능이 아니라 구조의 차이입니다. 수식이 포함된 대용량 양식이라면 JXLS에서는 스트리밍을 활성화할 수 없는 경우가 발생하고, 그 경우 전체 메모리 모드로 전환해야 합니다.

동일 조건 성능 측정

성능 비교는 조건을 통일하지 않으면 성립하지 않습니다. 하드웨어/JDK/데이터 형태가 다른 수치를 병렬 배치하면 비교가 되지 않습니다. 동일 장비, 동일 POI 버전, 동일 템플릿, 동일 워크로드로 측정한 결과만 게재합니다.

측정 조건은 Apple Silicon 12코어, OpenJDK 21, 최대 힙 8GB, Apache POI 5.5.1, JMH(fork 1 / warmup 1 / measurement 3)이고 워크로드는 3개 컬럼 반복 + SUM 수식입니다. TBEG는 항상 스트리밍이므로 출력 조건이 동일한 JXLS STREAMING_ON이 직접 비교 대상이고, 전체 메모리 모드인 STREAMING_OFF는 참고로 함께 게재합니다. 아래 수치는 모두 실측입니다.

데이터구성소요 시간힙 할당량
10,000행TBEG47ms31MB
10,000행JXLS STREAMING_ON78ms67MB
10,000행(참고) JXLS STREAMING_OFF393ms457MB
50,000행TBEG187ms134MB
50,000행JXLS STREAMING_ON378ms328MB
50,000행(참고) JXLS STREAMING_OFF1,306ms2,244MB
100,000행TBEG354ms256MB
100,000행JXLS STREAMING_ON728ms641MB
100,000행(참고) JXLS STREAMING_OFF2,626ms4,490MB

출력 조건이 동일한 구성에서 TBEG가 약 2배 빠릅니다. 다만 해석에 주의가 필요한 지점이 있어 함께 명시합니다.

힙 할당량은 메모리 점유량이 아닙니다. 표의 힙 할당량은 처리 중 생성 후 폐기한 임시 객체의 총량입니다. 특정 시점의 사용량을 나타내는 피크 힙은 10만 행 기준 TBEG 353MB, JXLS STREAMING_ON 383MB로 거의 동일합니다. 양쪽 모두 스트리밍이라 데이터가 증가하여도 피크가 억제됩니다. JXLS가 메모리를 더 점유하는 것이 아니라, 임시 객체를 더 많이 생성하여 GC가 자주 수행되는 것입니다.

차이의 원인은 할당 프로파일에서 확인됩니다. JXLS의 임시 객체는 대부분 셀 단위로 수행되는 표현식 평가 엔진(Apache Commons JEXL)과 자체 셀 참조 객체에서 발생합니다. 범용 표현식 엔진을 채택한 설계의 비용입니다. TBEG는 마커 전용 파서로 한 번 분석한 뒤 POI에 직접 기록하므로 이 중간 객체가 거의 발생하지 않습니다. 대신 JXLS는 그 엔진을 통해 앞서 정리한 jx:if나 groupBy 같은 표현력을 확보합니다. 성능 차이는 비용 없이 발생한 것이 아니라 표현력과 교환된 결과에 가깝습니다.

피크가 실제 제약이 되는 구성은 STREAMING_OFF입니다. 전체 데이터를 워크북에 적재하는 모드라 10만 행에서 피크가 1,621MB까지 상승합니다. 앞 절에서 정리한 대로 수식이 포함된 양식에서는 이 모드로 전환해야 하는 경우가 발생하므로, 대용량 처리에서는 이 항목을 먼저 확인해야 합니다.

한계를 하나 부기합니다. 이 수치는 특정 워크로드 하나에 대한 자체 측정치입니다. 컬럼 수, 수식 복잡도, 차트/피벗 유무에 따라 결과는 달라집니다. 성능이 선택 기준이라면 실제 사용할 템플릿과 데이터로 직접 측정하는 편이 확실합니다.

선택 기준

조건선택
양식이 단순하고 변경 가능성이 낮음Apache POI
의존성을 최소로 유지해야 함Apache POI
수십만 행 이상, 서식은 최소Apache POI (SXSSF) 또는 CSV
성숙도/자료/사례가 중요JXLS
조건 분기/그룹핑/중첩 반복이 필요JXLS
템플릿에 없던 표나 시트를 런타임에 생성JXLS
이미 JXLS로 정상 운영 중현행 유지
디자이너가 작성한 양식을 자주 갱신TBEG
차트/피벗이 포함된 양식TBEG
권한에 따라 노출 컬럼이 달라지는 표TBEG
수식이 포함된 대용량을 스트리밍으로 처리TBEG
비동기 생성이나 Spring Boot 통합이 필요TBEG

정상 운영 중인 구현을 교체할 이유는 없습니다. JXLS로 작성한 리포트가 문제없이 운영되고 있다면 현행을 유지하는 편이 적절합니다. 위 비교는 신규 구축 시점이나 현행 방식에 실제 제약이 발생하였을 때 참조할 내용입니다.

참고


TBEG는 오픈소스로 공개되어 있습니다.

2개의 댓글

comment-user-thumbnail
2026년 10월 29일

안녕하세요, 엑셀 다운로드 한 줄의 무게를 정확히 짚어 주셔서 공감하면서 읽었어요. 세 방식의 차이를 명령을 어디에 두느냐로 나눠 보신 관점이 정리하기 좋았고, 이해관계를 먼저 밝혀 주신 점도 좋았어요. TBEG에서도 수십만 행을 만들 때 내부적으로 SXSSFWorkbook처럼 스트리밍으로 처리하는지 궁금해요. 저도 백엔드를 공부하면서 Velog에 실험·트러블슈팅 기록을 올리고 있어요. 좋은 글 잘 읽고 팔로우하고 가요. 시간 되실 때 제 글도 한번 봐 주세요. 감사합니다!

1개의 답글