최근 웹 애플리케이션 내에서 Excel 환경을 그대로 구현하기 위해 SpreadJS를 도입하는 프로젝트가 늘고 있습니다. 제가 맡은 시스템에서도 SpreadJS를 사용하고 있습니다. SpreadJS를 사용하면서 발생한 문제 중 하나가 “특정 파일이 화면에서 전혀 열리지 않는 문제”였습니다.
초기 개발에서는 구버전을 사용하다 신버전으로 업데이트되었고, 사용자들이 다양한 파일을 업로드하면서 원인 모를 파싱 에러와 런타임 오류를 마주해야 했습니다. 이 원인은 파일 오픈 방식이 구버전에서는 “open()”만 사용하고 있었는데 신버전에서 “import()“와 ”fromJSON()“이 도입되면서 혼용되어 발생한 것입니다.
이 경험을 바탕으로 다시는 같은 실수를 반복하지 않도록 세 가지 포맷(.xlsx, .ssjson, .sjs)에 따른 정확한 API 매칭법과 올바른 예제 코드를 정리하였습니다.
에러 원인: 파일 성격과 method의 불일치
SpreadJS에서 파일을 열지 못하는 본질적인 이유는 "내가 가진 파일 데이터의 물리적 형태(바이너리인가, JSON 객체인가)"와 "이를 읽어들이는 API 엔진"을 잘못 짝지었기 때문입니다. 저희가 겪었던 대표적인 실패 케이스는 다음과 같았습니다.
* 실패 사례 1: 사용자가 브라우저에서 선택한 원본 .xlsx 바이너리 파일을 문자열 데이터인 줄 알고 구버전 방식의 fromJSON()에 그대로 밀어 넣었던 경우 -> SpreadJS 엔진이 내부 구조를 파싱하지 못해 화면이 먹통이 됨.
* 실패 사례 2: 서버 API 통신으로 다운로드한 .ssjson 텍스트 데이터를 파일 객체 그대로 import() method에 넘겨버린 경우 -> binary stream format header가 존재하지 않아 로드 에러 발생.
* 실패 사례 3: 최신 대용량 압축 포맷인 .sjs 파일을 과거 구형 모듈 방식인 ExcelIO.open()으로 열려고 시도했던 경우 -> 새로운 압축 구조를 구형 IO 라이브러리가 디코딩하지 못해 에러 반환.
이러한 시행착오 끝에 깨달은 핵심은 파일 확장자별로 정확하게 지정된 method와 옵션을 매칭해야만 브라우저 crash 없이 안전하게 파일을 오픈할 수 있다는 점이었습니다.
세 가지 포맷 매칭 매트릭스
파일을 열 때 에러가 발생한다면 가장 먼저 아래의 매트릭스 규칙을 지켰는지 확인해야 합니다.
-
확장자가 .xlsx인 경우
* 데이터의 실제 형태 : 표준 Microsoft Excel 바이너리 파일
* 올바른 처리 method : workbook.import()
* 필수 확장 플러그인 : gc.spread.sheets.io
-
확장자가 .ssjson인 경우
* 데이터의 실제 형태 : 텍스트 기반 JavaScript JSON 객체
* 올바른 처리 method : workbook.fromJSON()
* 필수 확장 플러그인 : 기본 Core 모듈 내장
-
확장자가 .sjs인 경우
* 데이터의 실제 형태 : SpreadJS 전용 대용량 압축 바이너리 (Zip)
* 올바른 처리 method : workbook.import()
* 필수 확장 플러그인 : gc.spread.sheets.io
구형 문서나 오래된 블로그 글에서는 GC.Spread.Excel.IO 인스턴스를 생성한 뒤 excelIo.open()을 호출하라고 안내하지만, 최신 SpreadJS 아키텍처에서는 워크북 객체에 통합된 workbook.import()를 사용하는 것이 공식 표준이자 가장 안전한 방법입니다.
포맷별 올바른 파일 오픈 구현 가이드
포맷별 표준 구현 소스 코드입니다. 각 파일의 특성에 맞게 브라우저의 File/Blob 객체를 다루는 방식이 다릅니다.
-
표준 Excel (.xlsx) 파일 오픈하기
.xlsx 파일은 전형적인 바이너리 파일입니다. 따라서 브라우저 input 태그로부터 얻은 파일 객체 형태 그대로 workbook.import()에 전달하며, 반드시 옵션에 FileType.excel을 명시해야 합니다.
-
구형 JSON (.ssjson) 파일 오픈하기
.ssjson은 형식이 파일처럼 보일 뿐, 실제로는 SpreadJS의 상태를 텍스트로 내보낸 javaScript 객체입니다. 이를 파일 객체 그대로 method에 던지면 무조건 에러가 납니다. 반드시 FileReader를 통해 텍스트로 읽은 뒤 JSON.parse()로 순수 객체화하여 fromJSON()으로 로드해야 합니다.
-
최신 전용 압축 포맷 (.sjs) 파일 오픈하기
.sjs는 대용량 엑셀의 느린 로딩 속도와 파일 크기 문제를 해결하기 위해 도입된 전용 압축 포맷입니다. 구조적으로는 .xlsx와 같은 바이너리 압축 파일이므로 import() method를 공유하지만, 파싱 엔진 내부 처리를 다르게 해야 하므로 fileType 옵션을 FileType.sjs로 명확히 해주어야 합니다.
결론
각 포맷에 따른 올바른 파일 오픈 방식을 규칙화하고 명확하게 구분하게 된 이후, 놀랍게도 파일 로드 시 형식 불일치로 인해 발생하던 런타임 에러와 파싱 실패 빈도가 이전에 비해 눈에 띄게 줄어들었습니다. 에러 빈도가 획기적으로 낮아지면서 관련 디버깅에 소모되던 리소스를 줄이고 개발 시간을 대폭 아낄 수 있었고, 최종적으로는 시스템 안정성을 크게 끌어올리는 값진 성과를 거두었습니다.
kina.j