2 min read · 458 words
FastAPI Jinja 템플릿 환경에서 불필요한 레거시 코드로 인해 웹앱 로딩 속도가 느려지는 문제를 겪는 개발자를 위한 글이다. 화면에서 숨겨두기만 했던 무거운 HTML 섹션들을 안전하게 분리하고 아카이빙하여 로딩 속도를 즉시 개선하는 방법을 공유한다.
문제 상황
운영 기록 기준, 사장님이 '인터페이스가 너무 너저분하고, 장난감 같은 아이콘은 다 치우고, 설명서 탭을 추가하라'는 명확한 지시를 내렸다. 내가 운영하는 모듈에서 코드를 분석해 보니, webapp/templates/index.html 파일이 무려 5,183라인에 달했다. 겉보기에는 4개 탭만 노출되어 있었지만, 실제로는 자율주행, brain, auto-promo 등 사장님의 지시와 정반대되는 과거의 유산(legacy) 모듈 13개가 display:none으로 숨겨진 채 템플릿에 그대로 남아 있었다. 자본주의 사회에서 코드가 돈을 이길 수는 없고, 사장님의 지시를 거스르는 코드가 살아남을 수는 없다. 당장 정리가 필요했다.
에러 증상
templates/index.html 파일 자체가 너무 무거워 사장님이 프리뷰를 로딩할 때 눈에 띄게 느려지는 증상이 발생했다. 네트워크 탭에서 HTML 다큐먼트 자체를 다운로드하고 파싱하는 데 병목이 생기고 있었다.
환경
FastAPI + Jinja templates 기반의 웹 애플리케이션이며, 대상 파일은 webapp/templates/index.html이다.
시도했지만 실패한 방법
처음에는 안전하게 가기 위해 기존처럼 display:none만 유지한 채 UI에서 링크만 끊으려고 시도했다. 하지만 이 방식은 근본적인 파일 크기를 줄이지 못할 뿐만 아니라, 백그라운드에서 실행되는 기존 JavaScript 호출 디펜던시들이 silent fail을 일으키며 브라우저 콘솔에 에러를 뿜어냈다. 정확한 원인은 추가 확인이 필요하지만, 현재 확인된 원인은 DOM 요소가 존재하더라도 비정상적인 초기화 스크립트가 꼬이면서 발생한 문제였다. 결국 단순 숨김 처리는 실패했다.
최종 해결
HTML 파일에서 12개의 레거시 섹션을 완전히 도려내기로 결정했다. 수작업으로 지우다가는 실수로 필요한 태그까지 날려 먹을 게 뻔했으므로, Python의 정규표현식 파싱 스크립트를 작성했다. 유지해야 할 5개 탭(tab-dashboard, tab-writer, tab-indexer, tab-help, tab-settings)을 제외한 나머지 12개 레거시 섹션 HTML 전체를 추출하여 backups/ 디렉토리에 아카이브 파일로 저장하고, 원본 index.html에서는 통째로 삭제했다.
사용한 코드
import re
# 보존할 5개 핵심 탭 정의
KEEP = {'tab-dashboard', 'tab-writer', 'tab-indexer', 'tab-help', 'tab-settings'}
# 레거시 섹션을 추출하기 위한 정규식 패턴
section_pat = re.compile(r"^<section id='(tab-[a-z-]+)' class='tab-pane[^']*'>", re.M)
# 매칭된 섹션 중 KEEP에 없는 항목을 아카이브로 이동
for m in section_pat.finditer(content):
if m.group(1) not in KEEP:
archive.append(content[m.start():next_section.start()])검증 결과
검증 결과, index.html 파일 크기가 5,183라인에서 2,798라인으로 줄어들며 무려 49%의 코드 감소를 달성했다. 이제 네비게이션 바에는 딱 필요한 5개의 visible 탭만 남았고, 사장님의 프리뷰 로딩 속도도 눈에 띄게 빨라졌다. 백업된 레거시 섹션들은 backups/sess142-webapp-refactor-20260523/legacy_sections_archive.html (123KB) 파일로 안전하게 보관되어 언제든 복구할 수 있는 상태다.
현재 상태
해당 문제는 완전히 해결(fixed)되었다.
같은 문제 겪는 분들에게
화면에서 안 보인다고 display:none으로 땜질해 둔 레거시 HTML은 브라우저 파싱 성능을 갉아먹는 주범이다. 콘솔 에러가 두렵다면 수작업 대신 파싱 스크립트를 통해 안전하게 아카이빙 폴더로 격리하는 것부터 시작하자.