FAQ & Troubleshooting

Kosmos DSL 사용 중 자주 묻는 질문과 해결책을 정리했습니다.
DSL 렌더링, 빌드, 배포, i18n, 성능 문제까지 카테고리별로 확인할 수 있습니다.

Tip: 이 문서는 실제 프로젝트 이슈 기록을 바탕으로 지속적으로 업데이트됩니다.

1. 렌더링 관련

Q1. VoidTag에 자식 요소를 추가했더니 예외가 발생합니다.

VoidTag는 자식을 가질 수 없는 태그입니다. 예를 들어 img나 input은 닫는 태그가 없으므로 addChild() 호출 시 경고가 발생합니다.

// 잘못된 예
El.img().child(El.span().text("text"));

// 올바른 예
El.img().attr("src", "/assets/img/logo.png").attr("alt", "logo");
해결: VoidTag에는 텍스트나 자식 노드를 추가하지 마세요.
Q2. 일부 HTML 태그가 브라우저에서 깨져 보입니다.

HTML Escape가 적용되지 않았거나 RenderContext가 누락된 경우입니다. 항상 HtmlEscape.escapeHtml()을 통해 안전하게 렌더링됩니다.

El.p().text("<Hello> World!"); // 안전 출력

2. 다국어(i18n) 관련

Q3. 메시지 번역이 적용되지 않습니다.

RenderContext가 Locale을 가지고 있지 않거나 messages.properties 파일이 올바른 위치에 없을 수 있습니다.

// 올바른 초기화
RenderContext ctx = new RenderContext(Locale.KOREAN, false);
El.p().text(ctx.getMessage("page.estimation.title", "기본값"));
해결: messages_ko.properties, messages_en.properties 파일 경로를 확인하세요. (src/main/resources/i18n/ 권장)
Q4. 다국어 파일이 변경돼도 서버에서 즉시 반영되지 않습니다.

Spring Boot의 기본 MessageSource는 캐싱을 사용합니다. 개발 환경에서는 cacheSeconds=0으로 설정하세요.

@Bean
public MessageSource messageSource() {
    ReloadableResourceBundleMessageSource source = new ReloadableResourceBundleMessageSource();
    source.setBasename("classpath:i18n/messages");
    source.setDefaultEncoding("UTF-8");
    source.setCacheSeconds(0); // 즉시 반영
    return source;
}

3. 성능 관련

Q5. 대용량 테이블 렌더링 시 CPU 점유율이 높습니다.

Kosmos DSL은 내부적으로 StringBuilder 기반 버퍼링으로 최적화되어 있지만, 복잡한 중첩 렌더링에서는 String.concat()이 아닌 append()를 사용하는지 확인해야 합니다.

// 비효율
sb.append(child.render(ctx)); // ✅ 효율적
html += child.render(ctx);    // ❌ 비효율
Q6. DSL 렌더링 속도를 더 높일 수 있나요?
  • 정적 DSL 요소를 캐싱 (e.g., Header, Footer)
  • 조건부 렌더링 최소화 (if() 분기 중복 제거)
  • 반복문 내 RenderContext 재사용

4. 빌드 및 배포

Q7. DSL 수정 후 서버 반영이 안됩니다.

DSL 라이브러리를 로컬 Maven에 퍼블리시하지 않았을 가능성이 높습니다.

./gradlew :kosmos-dsl:publishToMavenLocal
./gradlew :kosmos-spring:publishToMavenLocal
Tip: 각 모듈의 버전이 build.gradle에 맞게 일치하는지 확인하세요.
Q8. GitHub Actions에서 빌드 실패가 발생합니다.

JDK version 또는 Gradle cache 문제일 수 있습니다. Actions에서 다음 스텝을 추가하세요.

- name: Clean Gradle Cache
  run: rm -rf ~/.gradle/caches

5. 구조 및 네이밍

Q9. 왜 모든 클래스가 ‘Comp’, ‘Frag’, ‘Page’ 접두사를 사용하나요?

Kosmos DSL은 Atomic Design System을 따르기 때문입니다. - Atom → Comp* - Molecule → Frag* - Organism → Template* - Page → Page*

이 구조는 재사용성과 일관성을 높여 유지보수를 단순화합니다.
Q10. 컴포넌트 내 중복 클래스명이 발생합니다.

.css() 체이닝 시 동일 클래스가 여러 번 추가될 수 있습니다. 중복 제거 로직을 추가하세요:

public AbstractHtmlTag addClass(String cls) {
    if (!classes.contains(cls)) classes.add(cls);
    return this;
}

6. 관련 문서