[Web] JSP에서 데이터를 엑셀 파일로 내보내는 방법 가이드

JSP에서 데이터를 엑셀 파일로 내보내는 방법 완벽 가이드

개요

웹 개발을 하다 보면 사용자가 데이터를 엑셀 파일로 다운로드할 수 있게 해야 하는 경우가 많습니다. 특히 JSP 환경에서 작업하는 개발자라면 이 기능을 어떻게 구현해야 할지 고민하실 텐데요.

이 글에서는 JSP에서 데이터베이스의 정보를 엑셀 파일로 변환하고 다운로드하는 방법을 단계별로 자세히 알아보겠습니다. Apache POI 라이브러리를 활용하여 기본적인 엑셀 파일 생성부터 데이터베이스 연동, 스타일 적용, 다운로드 기능 구현까지 실무에서 바로 적용할 수 있는 완벽한 가이드를 제공합니다.

엑셀 다운로드 기능은 사용자 편의성과 효율적인 데이터 관리를 위해 웹 애플리케이션에서 매우 중요한 기능입니다. 이 글을 통해 JSP 개발자들이 엑셀 내보내기 기능을 쉽게 구현할 수 있도록 실제 코드 예제와 함께 자세히 설명하겠습니다.

목차

1. 필요한 라이브러리 준비하기

2. 기본 엑셀 파일 생성 방법

3. 데이터베이스 연동하기

4. 스타일과 셀 서식 적용하기

5. 자주 발생하는 문제와 해결 방법

---

#1. 필요한 라이브러리 준비하기

JSP에서 엑셀 파일을 생성하려면 Apache POI 라이브러리를 사용하는 것이 가장 일반적입니다. 이 라이브러리는 Microsoft Office 형식의 문서를 생성하고 수정할 수 있는 Java API를 제공하며, 전 세계 개발자들이 가장 많이 사용하는 검증된 도구입니다.

1) Maven 설정

Maven 프로젝트를 사용하는 경우 pom.xml 파일에 다음 의존성을 추가합니다. poi는 기본 라이브러리이고, poi-ooxml은 xlsx 형식을 지원하기 위한 라이브러리입니다.

<!-- pom.xml에 추가 -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>5.2.3</version>
</dependency>
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.2.3</version>
</dependency>

. . . . .

2) Gradle 설정

Gradle을 사용하는 프로젝트라면 build.gradle 파일에 다음과 같이 의존성을 추가합니다.

// build.gradle에 추가
dependencies {
    implementation 'org.apache.poi:poi:5.2.3'
    implementation 'org.apache.poi:poi-ooxml:5.2.3'
}

. . . . .

3) 버전 선택 시 주의사항

Apache POI 라이브러리는 지속적으로 업데이트되고 있습니다. 최신 버전을 사용하는 것이 보안과 성능 면에서 유리하지만, 기존 프로젝트와의 호환성을 고려하여 버전을 선택해야 합니다.

주요 버전별 특징

버전	특징
POI 3.x	오래된 버전으로 레거시 시스템에서 사용
POI 4.x	Java 8 이상 필요, 안정적인 버전
POI 5.x	Java 8 이상 필요, 최신 기능 및 성능 개선

---

#2. 기본 엑셀 파일 생성 방법

이제 본격적으로 JSP에서 엑셀 파일을 생성하는 방법을 알아보겠습니다. 가장 기본적인 형태의 엑셀 파일을 만드는 것부터 시작합니다.

1) 기본 엑셀 생성 코드

다음은 JSP에서 간단한 엑셀 파일을 생성하는 기본 예제입니다. 헤더와 데이터 행을 포함한 완전한 엑셀 파일을 만들 수 있습니다.

<%@ page language="java" contentType="application/vnd.ms-excel;charset=UTF-8"
    pageEncoding="UTF-8"%>
<%@ page import="org.apache.poi.ss.usermodel.*"%>
<%@ page import="org.apache.poi.xssf.usermodel.*"%>
<%@ page import="java.io.*"%>
<%
    // 응답 헤더 설정
    response.setHeader("Content-Disposition",
        "attachment;filename=example.xlsx");

    // 워크북 생성
    XSSFWorkbook workbook = new XSSFWorkbook();

    // 워크시트 생성
    XSSFSheet sheet = workbook.createSheet("데이터 시트");

    // 헤더 행 생성
    Row headerRow = sheet.createRow(0);
    headerRow.createCell(0).setCellValue("이름");
    headerRow.createCell(1).setCellValue("나이");
    headerRow.createCell(2).setCellValue("이메일");

    // 데이터 행 생성
    Row dataRow1 = sheet.createRow(1);
    dataRow1.createCell(0).setCellValue("홍길동");
    dataRow1.createCell(1).setCellValue(30);
    dataRow1.createCell(2).setCellValue("hong@example.com");

    // 워크북을 출력 스트림에 쓰기
    OutputStream out2 = response.getOutputStream();
    workbook.write(out2);

    // 자원 정리
    out2.close();
    workbook.close();

    // JSP의 기본 out 객체를 무효화하여 경고 방지
    out.clear();
    out = pageContext.pushBody();
%>

. . . . .

2) 코드 동작 원리

(1) ContentType 설정

① application/vnd.ms-excel: 브라우저에게 이 응답이 엑셀 파일임을 알려줍니다.
② charset=UTF-8: 한글 등 유니코드 문자가 깨지지 않도록 인코딩을 설정합니다.
③ Content-Disposition: 파일을 다운로드하도록 하며 파일명을 지정합니다.

(2) 워크북 및 시트 생성

① XSSFWorkbook: xlsx 형식의 엑셀 파일을 다루는 클래스입니다.
② createSheet(): 워크북 내에 새로운 시트를 생성합니다.
③ 시트 이름은 한글로 지정 가능하며, 특수문자 사용 시 주의가 필요합니다.

(3) 행과 셀 생성

① createRow(index): 지정한 인덱스 위치에 행을 생성합니다.
② createCell(index): 행 내에서 지정한 인덱스 위치에 셀을 생성합니다.
③ setCellValue(): 셀에 값을 입력합니다. 문자열, 숫자, 날짜 등 다양한 타입을 지원합니다.

---

#3. 데이터베이스 연동하기

실제 웹 애플리케이션에서는 데이터베이스에서 가져온 데이터를 엑셀 파일로 변환해야 하는 경우가 많습니다. 동적으로 데이터를 조회하여 엑셀로 내보내는 기능은 실무에서 가장 많이 사용되는 패턴입니다.

1) DB 연동 엑셀 생성 전체 코드

다음은 데이터베이스에서 사용자 정보를 조회하여 엑셀 파일로 내보내는 완전한 예제입니다.

<%@ page language="java" contentType="application/vnd.ms-excel;charset=UTF-8"
    pageEncoding="UTF-8"%>
<%@ page import="org.apache.poi.ss.usermodel.*"%>
<%@ page import="org.apache.poi.xssf.usermodel.*"%>
<%@ page import="java.io.*"%>
<%@ page import="java.sql.*"%>
<%
    // 데이터베이스 연결 정보
    String jdbcUrl = "jdbc:mysql://localhost:3306/mydb";
    String dbUser = "username";
    String dbPassword = "password";

    Connection conn = null;
    PreparedStatement pstmt = null;
    ResultSet rs = null;

    try {
        // JDBC 드라이버 로드
        Class.forName("com.mysql.cj.jdbc.Driver");

        // 데이터베이스 연결
        conn = DriverManager.getConnection(jdbcUrl, dbUser, dbPassword);

        // SQL 쿼리 준비
        String sql = "SELECT name, age, email FROM users";
        pstmt = conn.prepareStatement(sql);

        // 쿼리 실행
        rs = pstmt.executeQuery();

        // 엑셀 파일 이름 설정
        String fileName = "users_data.xlsx";
        response.setHeader("Content-Disposition",
            "attachment;filename=" + fileName);

        // 워크북 생성
        XSSFWorkbook workbook = new XSSFWorkbook();
        XSSFSheet sheet = workbook.createSheet("사용자 데이터");

        // 헤더 행 생성
        Row headerRow = sheet.createRow(0);
        headerRow.createCell(0).setCellValue("이름");
        headerRow.createCell(1).setCellValue("나이");
        headerRow.createCell(2).setCellValue("이메일");

        // 데이터 행 추가
        int rowNum = 1;
        while(rs.next()) {
            Row dataRow = sheet.createRow(rowNum++);
            dataRow.createCell(0).setCellValue(rs.getString("name"));
            dataRow.createCell(1).setCellValue(rs.getInt("age"));
            dataRow.createCell(2).setCellValue(rs.getString("email"));
        }

        // 열 너비 자동 조정
        for(int i = 0; i < 3; i++) {
            sheet.autoSizeColumn(i);
        }

        // 엑셀 파일 생성
        OutputStream outStream = response.getOutputStream();
        workbook.write(outStream);

        // 자원 정리
        workbook.close();
        outStream.close();

        // JSP의 기본 out 객체 무효화
        out.clear();
        out = pageContext.pushBody();

    } catch(Exception e) {
        e.printStackTrace();
    } finally {
        // 자원 해제
        if(rs != null) try { rs.close(); } catch(SQLException e) {}
        if(pstmt != null) try { pstmt.close(); } catch(SQLException e) {}
        if(conn != null) try { conn.close(); } catch(SQLException e) {}
    }
%>

. . . . .

2) 주요 포인트

(1) 데이터베이스 연결

① JDBC 드라이버는 프로젝트의 클래스패스에 포함되어 있어야 합니다.
② MySQL, Oracle, PostgreSQL 등 사용하는 데이터베이스에 맞는 드라이버를 설정합니다.
③ 연결 정보는 보안을 위해 설정 파일로 분리하는 것이 좋습니다.

(2) 동적 데이터 처리

① while(rs.next()) 반복문을 통해 모든 레코드를 순회합니다.
② rowNum 변수로 행 번호를 관리하며, 데이터를 추가할 때마다 증가시킵니다.
③ ResultSet에서 데이터를 가져올 때 적절한 타입으로 변환합니다.

(3) 자원 관리

① finally 블록에서 반드시 자원을 해제해야 메모리 누수를 방지할 수 있습니다.
② Connection, Statement, ResultSet 순서의 역순으로 닫습니다.
③ 각 close() 호출 시 null 체크와 예외 처리를 합니다.

. . . . .

3) 다운로드 버튼 구현

사용자가 버튼을 클릭하여 엑셀 파일을 다운로드할 수 있도록 하는 HTML 페이지 예제입니다.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>엑셀 다운로드 예제</title>
    <script>
        function downloadExcel() {
            window.location.href = 'exportExcel.jsp';
        }
    </script>
</head>
<body>
    <h2>사용자 데이터</h2>
    <table border="1">
        <tr>
            <th>이름</th>
            <th>나이</th>
            <th>이메일</th>
        </tr>
        <tr>
            <td>홍길동</td>
            <td>30</td>
            <td>hong@example.com</td>
        </tr>
    </table>
    <br>
    <button onclick="downloadExcel()">엑셀 파일 다운로드</button>
</body>
</html>

---

#4. 스타일과 셀 서식 적용하기

단순한 데이터만 있는 엑셀보다는 스타일이 적용된 깔끔한 엑셀 파일이 훨씬 보기 좋습니다. Apache POI는 다양한 스타일 옵션을 제공합니다.

1) 헤더 스타일 적용

헤더 행에 배경색, 폰트, 테두리 등의 스타일을 적용하여 데이터와 구분되도록 합니다.

<%
    // 헤더 스타일 생성
    XSSFCellStyle headerStyle = workbook.createCellStyle();

    // 배경색 설정
    headerStyle.setFillForegroundColor(
        IndexedColors.GREY_25_PERCENT.getIndex());
    headerStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND);

    // 테두리 설정
    headerStyle.setBorderTop(BorderStyle.THIN);
    headerStyle.setBorderBottom(BorderStyle.THIN);
    headerStyle.setBorderLeft(BorderStyle.THIN);
    headerStyle.setBorderRight(BorderStyle.THIN);

    // 폰트 설정
    XSSFFont headerFont = workbook.createFont();
    headerFont.setBold(true);
    headerStyle.setFont(headerFont);

    // 헤더 셀에 스타일 적용
    for(int i = 0; i < headerRow.getLastCellNum(); i++) {
        headerRow.getCell(i).setCellStyle(headerStyle);
    }
%>

. . . . .

2) 데이터 셀 스타일

데이터 셀에도 테두리를 추가하여 가독성을 높입니다.

<%
    // 데이터 셀 스타일
    XSSFCellStyle dataStyle = workbook.createCellStyle();
    dataStyle.setBorderTop(BorderStyle.THIN);
    dataStyle.setBorderBottom(BorderStyle.THIN);
    dataStyle.setBorderLeft(BorderStyle.THIN);
    dataStyle.setBorderRight(BorderStyle.THIN);

    // 데이터 행에 스타일 적용
    for(int i = 1; i <= sheet.getLastRowNum(); i++) {
        Row row = sheet.getRow(i);
        for(int j = 0; j < row.getLastCellNum(); j++) {
            row.getCell(j).setCellStyle(dataStyle);
        }
    }
%>

. . . . .

3) 날짜 및 숫자 형식

날짜와 숫자 데이터에 대해 특정 형식을 지정할 수 있습니다.

<%
    // 날짜 형식 스타일
    XSSFCellStyle dateStyle = workbook.createCellStyle();
    CreationHelper createHelper = workbook.getCreationHelper();
    dateStyle.setDataFormat(
        createHelper.createDataFormat().getFormat("yyyy-mm-dd"));

    // 숫자 형식 스타일 (천단위 콤마)
    XSSFCellStyle numberStyle = workbook.createCellStyle();
    numberStyle.setDataFormat(
        createHelper.createDataFormat().getFormat("#,##0"));
%>

주요 데이터 형식

형식	패턴	예시
날짜	yyyy-mm-dd	2025-11-03
시간	hh:mm:ss	14:30:25
정수	#,##0	1,234,567
소수	#,##0.00	1,234.56
통화	₩#,##0	₩1,234,567
퍼센트	0.00%	95.50%

---

#5. 자주 발생하는 문제와 해결 방법

JSP에서 엑셀 파일을 생성할 때 자주 마주치는 문제들과 해결 방법을 알아보겠습니다.

1) 한글 깨짐 문제

엑셀 파일을 다운로드할 때 한글 파일명이나 내용이 깨지는 경우가 있습니다. 인코딩 설정이 가장 중요합니다.

(1) 파일명 인코딩

<%
    // 한글 파일명을 위한 인코딩 처리
    String fileName = "사용자_데이터.xlsx";
    String encodedFileName = new String(
        fileName.getBytes("UTF-8"), "8859_1");
    response.setHeader("Content-Disposition",
        "attachment;filename=" + encodedFileName);
%>

(2) JSP 페이지 인코딩

① JSP 파일 상단에 pageEncoding="UTF-8" 설정이 필수입니다.
② ContentType에도 charset=UTF-8을 명시해야 합니다.
③ 데이터베이스 연결 URL에도 인코딩 파라미터를 추가합니다.

String jdbcUrl = "jdbc:mysql://localhost:3306/mydb
    ?useUnicode=true&characterEncoding=utf8";

. . . . .

2) 대용량 데이터 처리

많은 양의 데이터를 엑셀로 내보낼 때는 메모리 문제가 발생할 수 있습니다. SXSSF API를 사용하여 해결합니다.

<%@ page import="org.apache.poi.xssf.streaming.SXSSFWorkbook"%>
<%
    // 메모리 효율적인 워크북 생성 (메모리에 100개 행만 유지)
    SXSSFWorkbook workbook = new SXSSFWorkbook(100);

    // 이후 코드는 기존과 동일
    Sheet sheet = workbook.createSheet("데이터");
    // ...

    // 사용 후 임시 파일 정리
    workbook.dispose();
%>

SXSSF 사용 시 주의사항

① 메모리에 유지할 행 수를 적절히 설정해야 합니다.
② 이전 행으로 돌아가서 수정하는 것이 불가능합니다.
③ 임시 파일이 생성되므로 dispose() 호출이 필수입니다.
④ 10만 건 이상의 대용량 데이터 처리에 적합합니다.

. . . . .

3) 컨트롤러에서 처리하기

실제 프로젝트에서는 JSP에서 직접 처리하기보다 컨트롤러에서 처리하는 것이 더 좋은 방법입니다. Spring MVC를 사용한 예제입니다.

@Controller
public class ExcelController {

    @GetMapping("/download/excel")
    public void downloadExcel(HttpServletResponse response)
        throws IOException {
        
        response.setContentType(
            "application/vnd.openxmlformats-officedocument
            .spreadsheetml.sheet");
        response.setHeader("Content-Disposition",
            "attachment;filename=data.xlsx");

        XSSFWorkbook workbook = new XSSFWorkbook();
        XSSFSheet sheet = workbook.createSheet("데이터");

        // 데이터 추가 로직
        // ...

        // 파일 출력
        workbook.write(response.getOutputStream());
        workbook.close();
    }
}

컨트롤러 방식의 장점

① 비즈니스 로직과 뷰의 분리로 유지보수가 용이합니다.
② 서비스 계층을 활용한 깔끔한 코드 구조를 만들 수 있습니다.
③ 예외 처리와 로깅이 체계적으로 가능합니다.
④ 테스트 코드 작성이 수월합니다.

. . . . .

4) 성능 최적화 팁

(1) 열 너비 설정

① autoSizeColumn()은 편리하지만 성능이 느립니다.
② 대용량 데이터의 경우 수동으로 열 너비를 설정하는 것이 좋습니다.
③ 256 단위로 설정하며, 예를 들어 20자는 약 5120입니다.

// 자동 조정 대신 수동 설정
sheet.setColumnWidth(0, 5120); // 약 20자
sheet.setColumnWidth(1, 2560); // 약 10자

(2) 스타일 재사용

① 셀마다 새로운 스타일을 생성하면 메모리 낭비가 심합니다.
② 동일한 스타일을 재사용하도록 미리 생성해 놓습니다.
③ 워크북당 최대 4000개까지 스타일을 생성할 수 있습니다.

(3) 데이터베이스 쿼리 최적화

① 필요한 컬럼만 SELECT하여 네트워크 비용을 줄입니다.
② 적절한 인덱스를 활용하여 쿼리 속도를 높입니다.
③ 페이징 처리를 고려하여 한 번에 너무 많은 데이터를 조회하지 않습니다.

---

마무리

JSP에서 데이터를 엑셀 파일로 내보내는 방법에 대해 알아보았습니다. Apache POI 라이브러리를 사용하면 다양한 형식과 스타일의 엑셀 파일을 쉽게 생성할 수 있습니다.

핵심 요약

① Apache POI 라이브러리를 프로젝트에 추가하여 엑셀 파일 생성 기능을 구현할 수 있습니다.
② 데이터베이스와 연동하여 동적으로 데이터를 조회하고 엑셀로 내보낼 수 있습니다.
③ 스타일과 서식을 적용하여 보기 좋고 전문적인 엑셀 파일을 만들 수 있습니다.
④ 대용량 데이터 처리 시에는 SXSSF API를 사용하여 메모리 문제를 해결할 수 있습니다.
⑤ 실무에서는 컨트롤러 계층에서 처리하는 것이 유지보수에 유리합니다.

효율적인 데이터 관리와 사용자 편의성을 위해 엑셀 다운로드 기능을 제공하는 것은 웹 애플리케이션에서 매우 중요한 기능입니다. 이 글에서 소개한 방법들을 활용하여 실무에서 바로 적용할 수 있는 완성도 높은 엑셀 내보내기 기능을 구현해 보시기 바랍니다.

추가로 필요한 기능이 있다면 Apache POI 공식 문서를 참고하여 확장할 수 있습니다. 차트, 이미지 삽입, 피벗 테이블 등 더욱 고급 기능도 지원하므로 프로젝트 요구사항에 맞게 활용하시면 됩니다.

긴 글 읽어주셔서 감사합니다.

끝.