Apache POI 를 통해 Placeholder 기반 문서 치환 방식 정리
실무에서 Word / Excel 문서를 자동 생성해야 하는 경우가 자주 있다. 특히 다음과 같은 요구사항이 있을 때 Apache POI는 좋은 선택지입니다.
- 기존 Word / Excel 양식을 그대로 유지해야 할 때
- 특정 위치에 값을 동적으로 치환해야 할 때
- 파일을 새로 만드는 게 아니라 템플릿을 기반으로 수정해야 할 때
이 글에서는
Apache POI의 기본 사용법과
Placeholder({{KEY}}) 방식으로 기존 문서를 치환하는 방법을 정리해보겠습니다.
1. Apache POI란?
Apache POI는 Microsoft Office 문서 형식을 Java에서 다룰 수 있게 해주는 라이브러리다. 주로 사용하는 모듈은 다음과 같습니다.
문서클래스
| Word (.docx) | XWPFDocument |
| Excel (.xlsx) | XSSFWorkbook |
2. 의존성 설정
Gradle
implementation 'org.apache.poi:poi:5.2.5'
implementation 'org.apache.poi:poi-ooxml:5.2.5'
3. 기본 개념 – 템플릿 + Placeholder 방식
템플릿 문서 예시 (Word / Excel 동일)
- Placeholder 문자열은 기존 문서에서 복사/붙여넣기 방식으로 작성하면 인식되지 않을 수 있으며, 반드시 직접 타이핑하여 입력해야 정상적으로 치환됩니다.
- 문서에는 실제 값이 아닌 placeholder만 작성
- Java 코드에서 placeholder를 실제 값으로 치환
- 템플릿을 수정해도 코드 변경이 거의 없음
이 방식이 유지보수 측면에서 가장 안정적입니다.
4. Word 문서 기본 사용법 (XWPFDocument)
템플릿 로드
InputStream is = new ClassPathResource("templates/sample.docx").getInputStream();
XWPFDocument document = new XWPFDocument(is);
5. Word Placeholder 치환 방식
핵심 아이디어
- Paragraph(문단) 안의 모든 Run을 순회
- Run의 텍스트에 placeholder가 포함되어 있으면 replace
치환 메서드 예시
for (XWPFParagraph paragraph : document.getParagraphs()) {
replaceTextInParagraph(paragraph, replaceMap);
}
private static void replaceTextInParagraph(
XWPFParagraph paragraph,
Map<String, String> replaceMap
) {
for (XWPFRun run : paragraph.getRuns()) {
String text = run.getText(0);
if (text == null) continue;
for (Map.Entry<String, String> entry : replaceMap.entrySet()) {
if (text.contains(entry.getKey())) {
text = text.replace(entry.getKey(), entry.getValue());
}
}
run.setText(text, 0);
}
}
6. Word 테이블 내부 Placeholder 치환
Word 문서에서 대부분의 템플릿은 테이블(표) 안에 들어있습니다. Paragraph만 처리하면 테이블 안 텍스트는 치환되지 않습니다.
for (XWPFTable table : document.getTables()) {
for (XWPFTableRow row : table.getRows()) {
for (XWPFTableCell cell : row.getTableCells()) {
for (XWPFParagraph paragraph : cell.getParagraphs()) {
replaceTextInParagraph(paragraph, replaceMap);
}
}
}
}Paragraph + Table 둘 다 처리해야 완전한 치환
7. Excel 기본 사용법 (XSSFWorkbook)
템플릿 로드
InputStream is = new ClassPathResource("templates/sample.xlsx").getInputStream();
XSSFWorkbook workbook = new XSSFWorkbook(is);
XSSFSheet sheet = workbook.getSheetAt(0);
8. Excel Placeholder 치환 방식
Excel 셀 타입이 문자열일 때 처리
for (Row row : sheet) {
for (Cell cell : row) {
if (cell.getCellType() == CellType.STRING) {
String value = cell.getStringCellValue();
for (Map.Entry<String, String> entry : replaceMap.entrySet()) {
if (value.contains(entry.getKey())) {
value = value.replace(entry.getKey(), entry.getValue());
}
}
cell.setCellValue(value);
}
}
}- 수식 셀(CellType.FORMULA)을 문자열로 덮어쓰면 수식이 깨질 수 있음
- 필요한 경우 문자열 / 수식 분기 처리 필수
마무리
Apache POI는 단순히 엑셀 파일을 읽고 쓰는 라이브러리를 넘어 기존 문서 템플릿을 기반으로 한 문서 자동화에 매우 강력한 도구입니다.
특히 기존 템플릿 유지 + Placeholder 기반 치환 + Word / Excel 공통 처리 이 조합은 실무에서 활용도가 매우 높습니다.
저는 Apache POI를 활용해 회사에서 사용 중인 휴가결재, 비용처리 등 각종 양식 문서를 자동화했으며 서명 이미지 삽입까지 포함한 방식으로 구현해보았습니다.
이번 포스팅이 문서 자동화를 고민하시는 분들께 조금이나마 실무에 도움이 되었으면 좋겠습니다 🙂