빠른 시작

사전 요구 사항

항목	버전
Java	17 이상
Node.js	20 이상
pnpm	최신 버전

방법 1: create-q로 프로젝트 생성

새 프로젝트를 처음 시작할 때 권장하는 방법입니다.

1단계: 프로젝트 생성

npm create @softminds/q@1.0.0-SNAPSHOT

2단계: 대화형 프롬프트 응답

Q-Framework Project Generator v1.0.0-SNAPSHOT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

? Project name: my-app
? Group ID: com.example
? Artifact ID: my-app
? Description: My Q-Framework Application
? Client App Key: app
? Package name: com.example.myapp

── Advanced settings ──────────────────────────────
? Java version: 17
? Spring Boot version: 3.3.0
? Database: H2 (for development)
? Include sample entity: Yes

Generating project...
✓ Backend project created
✓ Frontend project created
✓ Sample entity created

Project created: ./my-app

기본값 저장

자주 사용하는 설정은 ~/.qframework/default-values/create-q 파일에 저장하면 다음 프로젝트 생성 시 자동으로 적용됩니다.

# ~/.qframework/default-values/create-q
groupId: com.example
javaVersion: 17
database: postgresql
clientAppKey: app

3단계: 프로젝트 실행

cd my-app
./start.sh

백엔드(http://localhost:8080)와 프론트엔드(http://localhost:3000)가 동시에 시작됩니다.

---

방법 2: 라이브러리 임포트 (기존 프로젝트)

기존 Spring Boot 프로젝트에 Q-Framework 기능을 추가하는 방법입니다.

1단계: 의존성 추가

build.gradle:

dependencies {
    implementation platform('net.softminds.qframework:q-spring-boot-bom:1.0.0-SNAPSHOT')
    implementation 'net.softminds.qframework:q-spring-boot-starter:1.0.0-SNAPSHOT'
    implementation 'net.softminds.qframework:q-spring-boot-jpa:1.0.0-SNAPSHOT'
    annotationProcessor 'net.softminds.qframework:q-apt:1.0.0-SNAPSHOT'

    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
}

Maven (pom.xml):

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>net.softminds.qframework</groupId>
            <artifactId>q-spring-boot-bom</artifactId>
            <version>1.0.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>net.softminds.qframework</groupId>
        <artifactId>q-spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>net.softminds.qframework</groupId>
        <artifactId>q-spring-boot-jpa</artifactId>
    </dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>net.softminds.qframework</groupId>
                        <artifactId>q-apt</artifactId>
                        <version>1.0.0-SNAPSHOT</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

2단계: 백엔드 추가 설정 없음

라이브러리 추가만으로 자동 설정이 완료됩니다. application.yml에 별도 설정이 필요하지 않습니다.

자동 설정

q-spring-boot 모듈이 Spring Boot Auto-configuration을 제공합니다. 엔티티와 컴포넌트 선언만으로 즉시 사용 가능합니다.

3단계: 프론트엔드 모듈 추가

Nuxt 3 프로젝트에 @softminds/q-nuxt를 추가합니다:

pnpm

pnpm add @softminds/q-nuxt

npm

npm install @softminds/q-nuxt

nuxt.config.ts에서 extend합니다:

export default defineNuxtConfig({
  extends: ['@softminds/q-nuxt'],
})

추가 설정 없이 바로 사용 가능합니다. 모듈이 로드되면 Q-Framework UI 컴포넌트가 전역으로 등록됩니다.

---

첫 번째 엔티티 만들기

엔티티 클래스 작성

package com.example.myapp.domain;

import net.softminds.qframework.context.annotations.entity.QfEntity;
import net.softminds.qframework.context.annotations.attribute.*;
import net.softminds.qframework.context.annotations.attribute.elements.QfRequiredOn;
import net.softminds.qframework.context.annotations.elements.QfI18n;
import net.softminds.qframework.context.annotations.elements.QfI18nText;

@QfEntity(
    appKey = "app",
    name = @QfI18n(
        defaultMessage = "Product",
        texts = { @QfI18nText(locale = "ko", message = "상품") }
    ),
    capabilityKey = "product-management",
    deletePolicy = @QfCrudPolicy(enabled = true)
)
public class ProductEntity {

    @QfListAttribute(sortable = true)
    @QfDetailAttribute
    @QfCreateAttribute(requiredOn = @QfRequiredOn(always = true))
    @QfUpdateAttribute(requiredOn = @QfRequiredOn(always = true))
    @QfDisplayLabel(text = "Product Name")
    private String name;

    @QfListAttribute
    @QfDetailAttribute
    @QfCreateAttribute
    @QfUpdateAttribute
    @QfDisplayLabel(text = "Price")
    private Integer price;

    @QfDetailAttribute
    @QfCreateAttribute
    @QfUpdateAttribute
    @QfControlType(QfControlType.Type.textarea)
    @QfDisplayLabel(text = "Description")
    private String description;
}

빌드 및 실행

./gradlew build
./gradlew bootRun

생성된 API 확인

빌드가 완료되면 다음 API가 자동으로 활성화됩니다:

GET    /api/app/products          # 목록 조회 (페이지네이션 포함)
GET    /api/app/products/{id}     # 상세 조회
POST   /api/app/products          # 등록
PUT    /api/app/products/{id}     # 수정
DELETE /api/app/products/{id}     # 삭제
GET    /api/app/products/excel/download  # Excel 다운로드
POST   /api/app/products/excel/upload    # Excel 업로드

Swagger UI: http://localhost:8080/swagger-ui.html

프론트엔드 연동

Vue/Nuxt 프론트엔드에서 자동 생성된 UI 컴포넌트를 사용합니다:

<template>
  <!-- Q-Framework UI 컴포넌트: 목록/상세/등록/수정 자동 렌더링 -->
  <QfEntityView
    client-app="app"
    entity="product"
  />
</template>

<script setup>
import { QfEntityView } from '@softminds/q-vue'
</script>

---

다음 단계

• 엔티티 정의 — 더 복잡한 엔티티 구성하기
• 검증 — 검증 규칙 상세 설정
• Capability / 권한 — 접근 제어 설정
• 핵심 개념 — 동작 원리 이해하기