TBEG 빠른 시작 - 5분 만에 첫 보고서 만들기

황용호·2026년 3월 9일
@dataProviderExcelGeneratorExcel보고서JVMJavaQUICK STARTSXSSFSpring bootTBEGapache poidownloadexcelkotlinlibraryrepeatreport대용량데이터바인딩보고서빠른시작엑셀 다운로드오픈소스템플릿튜토리얼

TBEG - 템플릿 기반 Excel 보고서 생성

목록 보기
2/6

🇺🇸 English version

1편에서 TBEG이 무엇인지 알아봤습니다. 이번 편에서는 직접 코드를 작성하면서 TBEG의 핵심 기능을 체험해 봅니다.

Step 1. 의존성 추가

// build.gradle.kts
dependencies {
    implementation("io.github.jogakdal:tbeg:1.2.3")
}
Groovy / Maven 
// build.gradle
dependencies {
    implementation 'io.github.jogakdal:tbeg:1.2.3'
}
<!-- pom.xml -->
<dependency>
    <groupId>io.github.jogakdal</groupId>
    <artifactId>tbeg</artifactId>
    <version>1.2.3</version>
</dependency>

위 버전은 이 글의 작성 시점 기준입니다. 최신 버전은 Maven Central에서 확인하세요.

Step 2. 가장 간단한 예제 - 변수 치환

템플릿 만들기

Excel을 열어서 아래처럼 입력합니다:

${...}가 TBEG의 변수 마커입니다. 이 자리에 코드에서 전달한 값이 채워집니다.

코드 작성

import io.github.jogakdal.tbeg.ExcelGenerator
import java.io.File
import java.time.LocalDate

fun main() {
    val data = mapOf(
        "title" to "월간 보고서",
        "date" to LocalDate.now().toString(),
        "author" to "황용호"
    )

    ExcelGenerator().use { generator ->
        val template = File("template.xlsx").inputStream()
        val bytes = generator.generate(template, data)
        File("output.xlsx").writeBytes(bytes)
    }
}

결과

끝입니다. output.xlsx를 열어보면 ${title} 자리에 "월간 보고서"가, ${date} 자리에 오늘 날짜가 들어가 있습니다.

핵심 패턴: ExcelGenerator().use { ... } → 템플릿 읽기 → 데이터 전달 → 바이트 배열 받기. 이 패턴은 이후 모든 예제에서 동일합니다.

Java 코드 
import io.github.jogakdal.tbeg.ExcelGenerator;
import java.io.*;
import java.time.LocalDate;
import java.util.*;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        Map<String, Object> data = new HashMap<>();
        data.put("title", "월간 보고서");
        data.put("date", LocalDate.now().toString());
        data.put("author", "황용호");

        try (ExcelGenerator generator = new ExcelGenerator();
             InputStream template = new FileInputStream("template.xlsx")) {
            byte[] bytes = generator.generate(template, data);
            try (FileOutputStream output = new FileOutputStream("output.xlsx")) {
                output.write(bytes);
            }
        }
    }
}

Step 3. 리스트 데이터 반복 - repeat

실무에서 가장 많이 쓰이는 기능입니다. 직원 목록, 주문 내역, 매출 데이터 등 리스트를 행으로 펼쳐야 할 때 사용합니다.

템플릿

  • 1행: ${repeat(employees, A3:C3, emp)} - "employees 컬렉션의 각 항목을 emp라는 이름으로, A3:C3 범위를 반복해라"
  • 2행: 헤더 (반복 범위 밖이므로 그대로 유지)
  • 3행: 반복 범위 - emp의 필드가 각 행에 채워짐

코드

data class Employee(val name: String, val position: String, val salary: Int)

fun main() {
    val data = mapOf(
        "employees" to listOf(
            Employee("황용호", "부장", 8000),
            Employee("한용호", "과장", 6500),
            Employee("홍용호", "대리", 4500),
            Employee("김용호", "사원", 3500)
        )
    )

    ExcelGenerator().use { generator ->
        val bytes = generator.generate(File("template.xlsx").inputStream(), data)
        File("output.xlsx").writeBytes(bytes)
    }
}

결과

4명의 데이터가 4행으로 펼쳐졌습니다. 수식(=SUM() 등)이 있었다면 범위가 자동으로 조정됩니다.

Step 4. DataProvider - 더 체계적인 데이터 전달

Map은 간단하지만, 이미지나 지연 로딩 등 고급 기능을 쓰려면 DataProvider를 사용합니다.

Kotlin DSL

import io.github.jogakdal.tbeg.simpleDataProvider

val provider = simpleDataProvider {
    // 단순 변수
    value("title", "직원 현황")
    value("date", LocalDate.now().toString())

    // 컬렉션 (즉시 로딩)
    items("employees", employeeList)

    // 컬렉션 (지연 로딩) - 데이터가 필요할 때 호출됨
    items("bigData") {
        repository.streamAll().iterator()
    }

    // 이미지
    image("logo", logoBytes)
    imageUrl("banner", "https://example.com/banner.png")
}

ExcelGenerator().use { generator ->
    val bytes = generator.generate(template, provider)
}

Java Builder

import io.github.jogakdal.tbeg.SimpleDataProvider;

SimpleDataProvider provider = SimpleDataProvider.builder()
    .value("title", "직원 현황")
    .value("date", LocalDate.now().toString())
    .items("employees", employeeList)
    .itemsFromSupplier("bigData", () -> repository.streamAll().iterator())
    .image("logo", logoBytes)
    .build();
방식장점적합한 상황
Map간단함, 코드량 적음소량 데이터, 단순 보고서
DataProvider지연 로딩, 이미지, 메타데이터대용량 데이터, 이미지 삽입, 실무

실무에서는 대부분 DataProvider를 사용하게 됩니다.

Step 5. 이미지 삽입

템플릿에 ${image(logo)} 마커를 넣으면 해당 셀 위치에 이미지가 삽입됩니다.

val provider = simpleDataProvider {
    value("company", "TBEG Inc.")
    
    // 파일에서 읽기
    image("logo", File("logo.png").readBytes())
    
    // URL로 지정 (렌더링 시 자동 다운로드)
    imageUrl("banner", "https://example.com/banner.png")
}

이미지는 바이트 배열 또는 URL 두 가지 방식으로 제공할 수 있습니다. URL 방식은 별도 다운로드 코드 없이 렌더링 시 자동으로 처리됩니다.

Step 6. 파일 저장 옵션

바이트 배열 대신 파일로 직접 저장할 수도 있습니다.

ExcelGenerator().use { generator ->
    val path = generator.generateToFile(
        template = template,
        dataProvider = SimpleDataProvider.of(data),
        outputDir = Path.of("./output"),
        baseFileName = "report"
    )
    // 결과: ./output/report_20260115_143052.xlsx
}

타임스탬프가 자동으로 붙어서 파일명 충돌을 방지합니다.

전체 흐름 정리

1. Excel에서 템플릿 디자인 (서식, 차트, 수식 등 자유롭게)
2. 데이터 들어갈 자리에 ${변수명} 마커 배치
3. 리스트 데이터는 ${repeat(컬렉션, 범위, 변수)} 사용
4. 코드에서 데이터만 전달
5. TBEG이 결합 → 최종 Excel 생성

서식, 차트, 조건부 서식, 수식은 전부 템플릿에서 관리합니다.
코드는 데이터 바인딩에만 집중합니다.

다음 편 예고

다음 편에서는 TBEG의 템플릿 문법을 완전히 정복합니다. repeat의 다양한 옵션(DOWN/RIGHT 방향, 중첩 반복), 자동 셀 병합(merge), 요소 묶음(bundle), 빈 컬렉션 처리 등을 다룹니다.

링크

📖 상세 문서

profile
황용호
이전 포스트

TBEG 소개 - 템플릿 기반 Excel 보고서 생성 라이브러리 (Kotlin/Java)

다음 포스트

TBEG 템플릿 문법 완전 정복

0개의 댓글