Introduction — Getting Started

Kosmos DSL을 처음 접하는 분들을 위한 실전 온보딩 가이드입니다. 왜 Kosmos인가에서 출발해, 설치/환경 구성/첫 화면/검증까지 5분 내로 경험할 수 있도록 안내합니다.

왜 Kosmos인가?

정확성

타입 안정 DSL + 컴포넌트화로 리팩터링 안전성 확보

El.a().css("btn btn-primary")
   .attr("href","/docs/kosmos/foundation")
   .text("Foundation");

성능

내부 StringBuilder 최적화로 메모리/CPU 효율 극대화

대량 리스트에서도 안정적인 SSR 렌더 성능

빠른 시작 4단계

 

1. 의존성 추가

Gradle/Maven에 kosmos-dsl 등록

 

2. 환경 설정

JDK 17+ & Spring Boot 3.x

 

3. 첫 컴포넌트

Hello Kosmos! 렌더링

 

4. 실행 & 확인

브라우저에서 로컬 결과 확인

의존성 설치

Gradle

repositories { mavenCentral() }
dependencies {
  implementation 'net.uneedsoft:kosmos-dsl:0.0.1'
  implementation 'net.uneedsoft:kosmos-spring:0.0.1'
}
버전은 실제 배포 버전에 맞게 업데이트하세요.

Maven

<dependency>
  <groupId>net.uneedsoft</groupId>
  <artifactId>kosmos-dsl</artifactId>
  <version>0.0.1</version>
</dependency>

필수 환경

항목 권장 버전 비고
Java 17 이상 LTS 안정 버전 권장
Gradle 8.5+ Groovy DSL 유지 가능
Spring Boot 3.2+ Servlet 기반 SSR
IDE IntelliJ / VS Code Annotation Processor 활성화

첫 페이지: Hello Kosmos

의존성을 추가했다면, 아래처럼 HelloKosmosPage를 작성하여 첫 화면을 띄워볼 수 있습니다.

public class HelloKosmosPage implements HtmlComponent {
    @Override
    public String render(RenderContext ctx) {
        return El.div().css("container py-5").children(
            El.h1().text("Hello, Kosmos!"),
            El.p().text("타입 안정 DSL로 작성된 첫 페이지입니다."),
            El.a().css("btn btn-primary mt-3")
                 .href("/docs/kosmos/foundation")
                 .text("Foundation 문서 보기")
        ).render(ctx);
    }
}

컨트롤러 연결

@Controller
@RequestMapping("/hello")
public class HelloController {
  @GetMapping
  public ResponseEntity<String> hello(RenderContext ctx) {
    var page = new HelloKosmosPage();
    return ResponseEntity.ok(page.render(ctx));
  }
}

설치 & 실행 흐름

Gradle/Maven Spring Boot Kosmos DSL HelloKosmosPage 브라우저 확인

베스트 프랙티스

주제 권장 지양
컴포넌트화 반복되는 카드/폼/테이블을 Comp*로 추출 페이지마다 유사 HTML을 복붙
성능 StringBuilder 기반 렌더, 불필요 객체 생성 억제 빈번한 문자열 결합(+)로 GC 압박
접근성 의미 있는 태그, 라벨/aria 속성, 키보드 포커스 모양만 맞춘 <div> 남용
국제화(i18n) 문자열은 메시지 번들/리소스 키 사용 하드코딩 텍스트
보안 사용자 입력은 적절히 이스케이프/검증 raw HTML을 무검증으로 삽입

주의사항

Gradle Sync: kosmos-dsl 인식 실패 시 repositories { mavenCentral() } 및 버전 재확인
보안: 사용자 입력 포함 텍스트는 반드시 이스케이프/화이트리스트 정제를 거치세요.
구조 분리: 재사용 블록은 Comp*, 페이지 조합은 Frag*, 레이아웃은 Template.
버전 호환: JDK 21도 동작하지만 플러그인 호환성은 JDK 17 기준 검증됨.

다음으로