File Structure

Kosmos DSL 프로젝트의 권장 폴더 구조와 각 디렉터리/클래스의 역할을 정의합니다. 초기에 구조를 명확히 하면 장기 유지보수가 쉬워집니다.

권장 패키지 트리

com.example.app
 ├─ config
 ├─ controller
 ├─ service
 ├─ repository
 ├─ domain
 │   ├─ docs (DocsNode / DocsContent / DocsChangelog)
 │   └─ ... (엔티티/DTO)
 ├─ dsl
 │   ├─ template   (DocsPageTemplate)
 │   ├─ fragment   (FragDocsNodeTree, FragDocsContent, FragRightTOC)
 │   └─ component  (CompSaveForm, CompInputText, UnsTable, ...)
 ├─ web (static, assets, i18n)
 └─ Application.java

디렉터리별 역할

디렉터리 역할 예시
config 보안/국제화/웹 설정 WebMvcConfig, MessageSourceConfig
controller 라우팅/권한/응답 DocsController, HelloController
service 도메인 로직, 트랜잭션 DocsService
repository DB 접근 DocsRepository
domain 엔티티/DTO DocsNode, DocsContent, DocsChangelog
dsl/template 페이지 레이아웃/슬롯 DocsPageTemplate
dsl/fragment 페이지 조각(Organism) FragDocsNodeTree, FragDocsContent
dsl/component 재사용 단위(Molecule/Atom) CompSaveForm, UnsTable
web 정적 자원/번역 static/css, messages_ko.properties

필수 클래스 스켈레톤

// DocsPageTemplate (Layout)
public class DocsPageTemplate implements HtmlComponent {
  private final HtmlComponent left;
  private final HtmlComponent content;
  private final HtmlComponent rightTOC;
  public DocsPageTemplate(HtmlComponent left, HtmlComponent content, HtmlComponent rightTOC) {
    this.left = left; this.content = content; this.rightTOC = rightTOC;
  }
  @Override public String render(RenderContext ctx) {
    return El.div().css("container").children(
      El.div().css("row").children(
        El.div().css("col-3 d-none d-lg-block").child(left),
        El.div().css("col-9").children(content, rightTOC)
      )
    ).render(ctx);
  }
}
// FragDocsNodeTree (Organism)
public class FragDocsNodeTree implements HtmlComponent {
  private final List<DocsNodeTreeDto> tree; private final String currentPath;
  public FragDocsNodeTree(List<DocsNodeTreeDto> tree, String currentPath) {
    this.tree = tree; this.currentPath = currentPath;
  }
  @Override public String render(RenderContext ctx) {
    // 트리 순회 & currentPath 활성화 렌더
    return new StringBuilder()
      .append("<nav class='docs-sidenav'>...</nav>")
      .toString();
  }
}

네이밍 & 규칙

  • Template: 페이지 레이아웃(슬롯 제공) → *PageTemplate
  • Fragment: 페이지 조합(Organism) → Frag*
  • Component: 재사용 단위(Molecule/Atom) → Comp*
  • 공통 CSS 클래스는 web/static/css로 모으고, 인라인 스타일 지양

구성 도식

DocsPageTemplate Frag* Comp* El.*

Template → Fragment(Organism) → Component(Molecule/Atom) → El.*

주의사항

혼재 금지: Template/Fragment/Component 책임이 겹치지 않도록 분리하세요.
거대 클래스: 하나의 컴포넌트에 과도한 렌더 로직을 넣지 말고, 작게 쪼개 재사용성을 높이세요.
정적 자원: 공통 CSS/JS는 web/static에 모아 배포 파이프라인에서 캐시/버전 관리하세요.