Java로 JSON 데이터를 Excel 파일로 변환하기 (JSON to XLSX)

JSON은 웹 API, 설정 파일, 데이터 교환 등 다양한 분야에서 널리 사용되는 경량 데이터 형식입니다. 반면 Excel은 데이터 분석, 보고, 추가 가공에 매우 유용한 도구입니다. 따라서 JSON 데이터를 Excel 파일로 변환해야 하는 요구는 실무에서 자주 발생합니다. 이 글에서는 Java용 Spire.XLS for Java 라이브러리와 Jackson 라이브러리를 함께 사용하여 JSON 데이터를 Excel(XLSX) 파일로 변환하는 방법을 단계별로 설명합니다.

1. 라이브러리 설치 및 설정

프로젝트에서 사용할 라이브러리들을 의존성에 추가합니다. Maven을 사용하는 경우 pom.xml 파일에 다음 내용을 포함시킵니다.

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>
<dependencies>
    <!-- Excel 처리 라이브러리 -->
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.xls</artifactId>
        <version>16.6.5</version>
    </dependency>
    <!-- JSON 파싱을 위한 Jackson 라이브러리 -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.17.2</version>
    </dependency>
</dependencies>

Maven을 사용하지 않는다면, 각 JAR 파일을 직접 내려받아 프로젝트의 클래스패스에 추가할 수도 있습니다.

2. 기본 JSON 배열을 Excel로 변환하기

가장 일반적인 사용 사례는 JSON 배열 형태의 데이터를 Excel 워크시트로 변환하는 것입니다. 배열의 첫 번째 객체 키를 헤더로 사용하고, 각 객체를 하나의 데이터 행으로 매핑합니다 .

주요 단계:
1. ObjectMapper로 JSON 문자열을 파싱하여 JsonNode 트리를 생성합니다.
2. 루트 노드가 배열인지 확인합니다.
3. 배열의 첫 번째 객체에서 키를 추출하여 Excel 첫 번째 행(헤더)에 씁니다.
4. 각 객체를 순회하며 값을 해당 열에 쓰고, 숫자와 불리언은 타입을 보존합니다 .

예제 코드:

import com.spire.xls.*;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import java.io.File;
import java.util.Iterator;
import java.util.Map;

public class JsonToExcelConverter {
    public static void main(String[] args) {
        // 샘플 JSON 데이터 (직원 정보 배열)
        String jsonString = "["
                + "{\"EmployeeID\":1,\"Name\":\"Alice\",\"Department\":\"Sales\",\"Salary\":75000},"
                + "{\"EmployeeID\":2,\"Name\":\"Bob\",\"Department\":\"Marketing\",\"Salary\":68000},"
                + "{\"EmployeeID\":3,\"Name\":\"Carol\",\"Department\":\"Engineering\",\"Salary\":92000}"
                + "]";

        try {
            // JSON 파싱
            ObjectMapper mapper = new ObjectMapper();
            JsonNode rootNode = mapper.readTree(jsonString);

            // 루트가 배열인지 확인
            if (!rootNode.isArray()) {
                throw new IllegalArgumentException("JSON 루트는 배열이어야 합니다.");
            }
            ArrayNode jsonArray = (ArrayNode) rootNode;

            // Excel 워크북 및 워크시트 생성
            Workbook workbook = new Workbook();
            Worksheet sheet = workbook.getWorksheets().get(0);
            sheet.setName("JSON Data");

            // 첫 번째 객체에서 헤더(열 이름) 추출
            JsonNode firstObject = jsonArray.get(0);
            int col = 1;
            for (Iterator<Map.Entry<String, JsonNode>> it = firstObject.fields(); it.hasNext(); ) {
                Map.Entry<String, JsonNode> entry = it.next();
                sheet.get(1, col).setValue(entry.getKey()); // 헤더 쓰기
                col++;
            }

            // 데이터 행 쓰기
            for (int i = 0; i < jsonArray.size(); i++) {
                JsonNode record = jsonArray.get(i);
                int dataRow = i + 2; // 데이터는 2행부터 시작
                int dataCol = 1;

                for (Iterator<Map.Entry<String, JsonNode>> it = record.fields(); it.hasNext(); ) {
                    Map.Entry<String, JsonNode> entry = it.next();
                    JsonNode value = entry.getValue();

                    // 데이터 타입에 따라 적절한 메서드로 값 설정
                    if (value.isNumber()) {
                        sheet.get(dataRow, dataCol).setNumberValue(value.doubleValue());
                    } else if (value.isBoolean()) {
                        sheet.get(dataRow, dataCol).setBooleanValue(value.booleanValue());
                    } else {
                        sheet.get(dataRow, dataCol).setValue(value.asText());
                    }
                    dataCol++;
                }
            }

            // 열 너비 자동 조정
            sheet.getAllocatedRange().autoFitColumns();

            // Excel 파일 저장
            workbook.saveToFile("JsonToExcel.xlsx", ExcelVersion.Version2016);
            System.out.println("JSON 데이터가 Excel 파일로 변환되었습니다.");

        } catch (Exception e) {
            System.err.println("오류 발생: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

3. 중첩 JSON 구조를 Excel로 변환하기 (평면화)

실제 JSON 데이터는 객체 내부에 또 다른 객체가 중첩된 경우가 많습니다. Excel은 2차원 표 구조이므로, 이러한 중첩 구조를 표현하기 위해 키를 평면화(flatten)하는 방법을 사용합니다 . 예를 들어 {"Contact": {"Email": "...", "Phone": "..."}}와 같은 구조는 Contact.Email, Contact.Phone과 같은 컬럼명으로 변환할 수 있습니다.

핵심 로직 (재귀적 평면화):

// JSON 객체를 재귀적으로 순회하며 점(.) 표기법으로 키를 평면화하는 메서드
private static LinkedHashMap<String, String> flattenJson(JsonNode node, String prefix) {
    LinkedHashMap<String, String> flat = new LinkedHashMap<>();
    if (node.isObject()) {
        for (Iterator<Map.Entry<String, JsonNode>> it = node.fields(); it.hasNext(); ) {
            Map.Entry<String, JsonNode> entry = it.next();
            String newPrefix = prefix.isEmpty() ? entry.getKey() : prefix + "." + entry.getKey();
            flat.putAll(flattenJson(entry.getValue(), newPrefix));
        }
    } else {
        // 리프 노드(값)에 도달하면 전체 경로를 키로 저장
        flat.put(prefix, node.asText());
    }
    return flat;
}

이 메서드를 사용하면 모든 중첩 필드가 고유한 컬럼으로 표현되어 데이터 손실 없이 Excel로 변환할 수 있습니다 .

4. JSON 파일에서 직접 읽어오기

위 예제는 문자열 형태의 JSON을 다루었지만, 실제로는 파일에서 읽어오는 경우가 많습니다. ObjectMapper는 파일 입력도 직접 지원합니다 .

// JSON 파일에서 직접 읽어오기
JsonNode rootNode = mapper.readTree(new File("input.json"));

이후의 변환 로직은 동일합니다. 파일이 배열 형식이 아닌 단일 객체라면, 배열로 감싸거나 별도의 처리 로직을 추가해야 할 수 있습니다.

5. 고려 사항 및 대안

• 라이선스: 이 글에서 사용한 Spire.XLS for Java는 상용 제품입니다. 무료 버전(Free Spire.XLS for Java)도 제공되지만, 기능 사용에 일부 제한(예: 시트 수, 행 수)이 있을 수 있습니다. 프로젝트의 요구사항과 예산에 맞는 버전을 선택해야 합니다.
• 데이터 타입 처리: JSON의 숫자, 불리언, 문자열 타입을 적절히 구분하여 Excel에 저장하는 것이 중요합니다. 위 예제처럼 isNumber(), isBoolean() 등을 사용하여 타입을 보존하면, 이후 Excel에서 숫자 정렬이나 수식 사용이 가능해집니다 .
• Apache POI 등의 대안: 오픈소스 라이선스가 필요하다면 Apache POI를 고려할 수 있습니다. POI를 사용하려면 JSON 파싱(Jackson 등)과 Excel 생성 로직을 별도로 구현해야 하며, 이 글에서 소개한 방식보다 더 많은 코드가 필요할 수 있습니다.
• Aspose.Cells: 또 다른 상용 라이브러리인 Aspose.Cells는 Workbook 생성자에 JSON 파일 경로를 바로 전달하거나 JsonUtility.importData() 메서드를 통해 더 간결한 변환 API를 제공하기도 합니다 .

결론

이 글에서는 Java용 Spire.XLS for Java와 Jackson 라이브러리를 활용하여 JSON 데이터를 Excel 파일로 변환하는 기본적인 방법과 중첩 JSON을 처리하는 전략을 코드 예제와 함께 살펴보았습니다. JSON 배열을 파싱하여 헤더와 데이터를 추출하고, 숫자 및 불리언과 같은 데이터 타입을 보존하며 Excel 파일을 생성하는 과정을 다루었습니다. 이를 통해 API 응답이나 설정 파일 등의 JSON 데이터를 데이터 분석 및 보고에 용이한 Excel 형식으로 변환할 수 있습니다. 다만 상용 라이선스 정책을 확인하고, 프로젝트의 규모와 요구사항에 따라 Apache POI와 같은 오픈소스 대안과의 비교를 통해 가장 적합한 도구를 선택할 것을 권장합니다.