1. 들어가며
프로젝트를 진행하던 중 사용자가 견적서 및 문서 데이터를 PDF 형태로 다운로드할 수 있는 기능이 필요하게 되었습니다.
처음에는 단순히 PDF 파일을 생성하면 될 것이라 생각했지만 실제 검토 과정에서는 여러 고려 사항이 존재했습니다.
-
한글 출력 지원
-
레이아웃 수정 편의성
-
라이센스 이슈
-
개발 생산성
-
유지보수성
특히 문서 양식 변경 요청이 자주 발생하는 업무 특성상 PDF 생성 자체보다 레이아웃을 얼마나 쉽게 수정할 수 있는가가 중요한 요구사항이었습니다.
이에 따라 여러 PDF 라이브러리를 검토하고 프로젝트에 적합한 기술을 선정하는 과정을 진행하였습니다.
2. 라이브러리 검토
iText
iText는 Java 진영에서 가장 널리 알려진 PDF 라이브러리입니다.
기능이 풍부하고 레퍼런스가 많아 구현 난이도는 낮은 편이었습니다.
그러나 상업적 사용 시 라이선스 제약이 존재하여 프로젝트 적용 시 별도의 검토가 필요했습니다.
OpenPDF
OpenPDF는 iText 기반 오픈소스 라이브러리로 무료 사용이 가능했습니다.
하지만 스타일을 객체 단위로 직접 작성해야 했습니다.
문서 구조가 복잡해질수록 코드량이 증가하고 유지보수 부담이 커질 것으로 판단했습니다.
Apache PDFBox
PDFBox는 성능과 안정성이 우수했습니다.
다만 대부분의 레이아웃을 좌표 기반으로 작성해야 했기 때문에 개발 공수가 높았습니다.
간단한 위치 변경도 좌표 수정이 필요하여 화면 디자인 변경에 유연하게 대응하기 어렵다고 판단했습니다.
OpenHTMLtoPDF
OpenHTMLtoPDF는 HTML을 PDF로 변환하는 방식의 라이브러리입니다.
HTML과 CSS를 그대로 활용할 수 있다는 점이 가장 큰 장점이었습니다.
특히 기존 퍼블리싱 자산을 재활용할 수 있고, 레이아웃 수정이 HTML 수준에서 가능하여 유지보수성이 높다고 판단했습니다.
다만 브라우저 수준의 CSS를 모두 지원하는 것은 아니므로 일부 고급 레이아웃은 제약이 존재합니다.
3. 최종 선정
최종적으로 OpenPDF와 OpenHTMLtoPDF를 중심으로 비교하였습니다.
|
항목 |
OpenPDF |
OpenHTMLtoPDF |
|---|---|---|
|
학습 난이도 |
보통 |
낮음 |
|
레이아웃 수정 |
어려움 |
쉬움 |
|
HTML 활용 |
불가능 |
가능 |
|
무료 사용 |
가능 |
가능 |
|
유지보수성 |
보통 |
높음 |
프로젝트 특성상 PDF 양식이 자주 변경될 가능성이 있었기 때문에 개발 생산성과 유지보수성을 중요하게 고려하였습니다.
이에 따라 OpenHTMLtoPDF를 최종 채택하였습니다.
4. 구현 과정
구현은 크게 세 단계로 구성하였습니다.
-
비즈니스 데이터를 조회한다.
-
데이터를 기반으로 HTML 템플릿을 생성한다.
-
OpenHTMLtoPDF를 통해 PDF 파일로 변환한다.
이 구조를 적용하면서 PDF 생성 로직과 화면 표현 로직을 분리할 수 있었고, 향후 새로운 양식이 추가되더라도 HTML 템플릿만 추가하면 동일한 생성 로직을 재사용할 수 있도록 구성하였습니다.
5. 이슈 및 보안 고려 사항
OpenHTMLtoPDF는 기본 폰트가 한글을 지원하지 않습니다.
따라서 한글이 깨지는 현상이 발생할 수 있으며, 이를 해결하기 위해 한글을 지원하는 폰트를 리소스에 추가하고, builder.useFont() 메소드를 통해 빌더 생성 시점에 폰트를 명시적으로 매핑하여 해당 문제를 해결할 수 있습니다.
또한 OpenHTMLtoPDF는 HTML을 렌더링하여 PDF를 생성하는 라이브러리입니다.
따라서 사용자 입력값을 HTML에 그대로 삽입할 경우 의도하지 않은 HTML 태그가 포함되어 문서 구조가 변경될 수 있습니다.
이를 방지하기 위해 HTML 생성 시 모든 사용자 입력값에 대해 HtmlUtils.htmlEscape()를 적용하였으며, HTML 태그가 문자열로 변환되어 사용자 입력이 HTML 구조에 영향을 주지 못하도록 하였습니다.
또한 HTML 템플릿은 서버에서 관리하고, 사용자 입력은 템플릿 내부의 지정된 위치에만 삽입하도록 설계하였습니다.
특히 이미지(img), 스타일(style), 외부 리소스 URL 등 HTML 렌더링 과정에서 외부 리소스를 참조할 수 있는 영역에는 사용자 입력값이 반영되지 않도록 하여, 의도하지 않은 리소스 접근이 발생하지 않도록 구성하였습니다.
이를 통해 사용자 입력으로 인한 HTML 구조 변경 가능성을 최소화하고, PDF 생성 과정에서의 보안 위험 요소를 줄일 수 있었습니다.
6. 적용 결과
OpenHTMLtoPDF 도입 이후 다음과 같은 효과를 얻을 수 있었습니다.
-
HTML/CSS 기반으로 빠른 개발 가능
-
레이아웃 수정 비용 감소
-
퍼블리싱 자산 재활용 가능
-
무료 오픈소스 사용으로 라이선스 부담 감소
특히 양식 변경 요청 발생 시 Java 코드 수정 없이 HTML 템플릿만 수정하면 되는 점이 유지보수 측면에서 가장 큰 장점이었습니다.
7. 마치며
PDF 생성 기능 자체는 비교적 단순한 요구사항처럼 보일 수 있습니다.
그러나 실제로는 라이선스, 유지보수성, 보안, 한글 지원 등 다양한 요소를 함께 고려해야 했습니다.
이번 작업을 통해 기술 선정 시 단순히 기능만 보는 것이 아니라 장기적인 유지보수 비용과 운영 편의성까지 함께 고려하는 것이 중요하다는 점을 다시 한번 경험할 수 있었습니다.
참고
1. https://github.com/danfickle/openhtmltopdf
Novin