템플릿팩 만들기

팀이나 프로젝트의 코딩 컨벤션에 맞는 코드를 생성하려면 템플릿팩을 직접 만들 수 있습니다. 이 문서에서는 템플릿팩 생성부터 템플릿 작성, 배포와 공유까지 제작 과정을 순서대로 설명합니다.

팩의 구성 요소

템플릿팩은 아래 요소로 구성되며, 다음과 같이 '만들기 → 저장(초안) → 배포(버전 게시) → 공개·초대(공유)' 순서로 진행됩니다.

구성 요소	설명
템플릿 (Template)	파일 하나를 만들어 내는 단위 — Velocity 본문과 설치(Installation) 규칙을 가집니다.
그룹 (Group)	템플릿을 정리하는 트리 폴더. 코드 생성 모달에도 같은 구조로 보입니다.
언어 프로필 (Language Profile)	대상 언어 선언 — 타입 매핑과 전역/엔티티/필드 변수 정의를 담습니다.
초안 (Draft)	내 워크스페이스의 편집본. 저장해도 다른 사람에게는 보이지 않습니다.
버전 (Version)	배포(게시)로 만들어지는 불변 스냅샷. 다른 사용자·프로젝트가 사용하는 단위입니다.

팩 만들기

좌측 메뉴에서 템플릿 팩 화면을 엽니다.

[신규] 클릭

왼쪽 팩 목록 상단의 [신규] 버튼을 누르면 생성 모달이 열립니다.

이름과 언어 선택

Java, TypeScript 를 선택하면 타입 매핑과 변수 정의가 검증된 프리셋으로 채워집니다. 목록에 없는 언어는 "Custom… (직접 작성)" 을 선택하고 언어 이름(go, python 등)을 입력합니다.

저장

하단의 저장 버튼을 클릭하여 템플릿팩을 생성합니다.

Tip

기존 팩이 폴더나 ZIP 으로 있다면 [가져오기...] 로 불러올 수 있습니다. 같은 이름의 팩이 이미 있으면 기존 팩에 반영할지, 새 팩으로 추가할지 선택합니다.

템플릿 작성

기본 정보 입력

상단 카드에서 템플릿팩의 이름, 작성자, 설명을 입력합니다.

팩 상세 구성

"팩 상세 구성" 탭에서 왼쪽은 그룹/템플릿 트리, 오른쪽은 선택한 항목의 편집기입니다.

그룹 트리

[최상위 그룹 추가], [새 템플릿 추가] 버튼 또는 우클릭 메뉴를 사용하여 그룹과 템플릿을 추가할 수 있습니다. 생성한 항목은 드래그 앤 드롭으로 원하는 위치로 이동하거나 그룹을 구성할 수 있습니다.

템플릿 속성과 본문

이름·타입·설명·태그를 정하고 Velocity 본문을 작성합니다. 본문 에디터는 찾기/바꾸기를 지원합니다. 템플릿에 태그를 추가하면, 템플릿팩을 사용하는 사용자가 코드 생성 화면에서 태그를 기준으로 템플릿을 빠르게 찾고 필터링할 수 있습니다.

Installation — 설치 규칙

생성된 소스 코드가 어느 경로에 어떻게 저장될지에 대해 정의합니다.

옵션	의미
설치 유형	"파일 생성·교체" 는 대상 경로에 새 파일을 만들고, "스니펫 주입" 은 기존 파일의 플레이스홀더 위치에 코드 조각을 끼워 넣습니다.
설치 경로 · 파일명	모듈 경로, 패키지, 엔티티 이름을 조합해 파일 위치를 작성합니다. 작성 시 변수 사용 가능합니다.
덮어쓰기	기존 파일이 있는 경우에는 해당 파일을 덮어씁니다. 토글을 끄면 기존 파일은 유지되고, 생성된 파일은 "대체 경로"에 저장됩니다.
읽기 전용	생성한 파일을 OS 읽기 전용으로 만듭니다 — 재생성으로 관리되는 파일의 수동 수정을 방지합니다.
Git Add	파일 생성 직후 git add 를 실행합니다.

템플릿 문법 (Velocity)

본문은 Apache Velocity 문법으로 작성합니다. 코드 생성 시점에 테이블 정보와 사용자가 입력한 설정 값이 템플릿의 변수에 자동으로 적용되어 소스 코드가 생성됩니다. (Velocity User Guide)

변수	내용
`$entity`	테이블을 가리킵니다. 테이블 이름(name), 다양한 이름 변환 형식(카멜, 스네이크, 케밥 등), 컬럼 목록($entity.fields), Soft Delete 설정, 엔티티 변수 값을 사용할 수 있습니다.
`$field`	테이블의 컬럼 하나를 가리킵니다. 보통 $entity.fields 를 반복하며 각 컬럼을 가리킬 때 사용합니다. 컬럼 이름·설명(코멘트)·매핑된 타입, 이 팩에서 정의한 필드 변수 값을 담습니다.
`$env`	사용자가 프로젝트 설정의 Templates Variables에서 입력한 전역 변수입니다. 예를 들어 기본 패키지명과 같은 공통 설정 값으로 사용할 수 있으며, 점(.)으로 중첩 값에 접근합니다 (예: $env.package.core).
`$types`	타입을 다루는 헬퍼입니다(언어 공통). 컬럼의 언어별 타입명 조회, import 경로 조회($types.importOf), 날짜·숫자 타입 여부 등을 확인($types.isDate, $types.isNumber)할 수 있습니다.
`$codegen`	코드 생성에 공통으로 사용하는 헬퍼입니다. 이름 표기법 변환(카멜·스네이크 등), DBMS 종류 판별($codegen.isOracle·isMySQL 등), 기본키(PK) 정보 조회 등을 제공합니다.
`$java · $ts · $py`	언어별 전용 헬퍼입니다(선택). 해당 언어에서 자주 사용하는 기능을 제공하며, 필요에 따라 사용할 수 있습니다.

예시 — Java 엔티티 클래스

필드를 순회하며 타입과 이름을 출력하는 전형적인 패턴입니다.

package ${env.package.core};

public class ${entity.name} {
#foreach($field in $entity.fields)
    private $types.typeOf($field) $field.name;
#end
}

사용할 수 있는 객체 속성과 도구 함수의 전체 목록은 Velocity 레퍼런스 문서에 정리되어 있습니다.

참고: 렌더링 결과는 프로젝트에서 소스코드 생성 화면을 열어 실제 테이블 기준으로 확인하는 것이 가장 정확합니다. 템플릿팩에 편집 권한이 있는 경우에는 미리보기 화면에서 원본 수정 모드로 전환하여 템플릿을 바로 수정하고 저장할 수 있습니다.

언어 프로필 (Settings 탭)

변수 선언 — 전역 / 엔티티 / 필드

여기서 변수를 선언하면 해당 템플릿팩을 사용하는 사람의 템플릿팩 설정 화면에 해당 변수 값을 입력하는 폼이 노출됩니다. 각 변수마다 key(템플릿에서 사용할 이름), 화면에 표시할 라벨, 입력 방식(입력 유형), 기본값, 필수 여부, 그리고 select 인 경우 선택 옵션을 지정합니다. 변수는 적용 범위에 따라 다음 세 가지로 나뉩니다.

종류	사용자가 입력하는 곳	템플릿에서 접근
전역 변수	프로젝트 설정 → Code Generator 탭의 Templates Variables	`$env.<key>`
엔티티 변수	테이블 상세 → Code Generator 탭 → Per-pack Settings → Entity	`$entity.<key>`
필드 변수	테이블 상세 → Code Generator 탭 → Per-pack Settings → Fields	`$field.<key>`

Tip

key 에 점(.)을 넣으면 계층(네임스페이스)이 됩니다. 예를 들어 package.core 로 선언하면 템플릿에서 $env.package.core 로 접근합니다. 값을 잘못 변경한 경우 "기본값으로 리셋" 버튼을 클릭하면 언어 프리셋의 기본값으로 언제든지 되돌릴 수 있습니다.

타입 매핑

DBMS 컬럼 타입을 템플릿의 생성 대상 언어에서 사용할 타입으로 변환할지 지정합니다. 예를 들어 BIGDECIMAL을 Java 의 java.math.BigDecimal 으로 매핑할 수 있습니다.

타입 매핑 표의 각 컬럼은 다음과 같습니다.

컬럼	설명
`Category`	타입을 숫자·문자·날짜 등 성격별로 묶어 보여주는 그룹입니다.
`Intermediate type`	NeoSQL 이 여러 DB 의 컬럼 타입을 정규화한 표준 타입입니다.
`Target type`	Intermediate type 을 템플릿에 설정한 언어에서 어떤 타입으로 변환할지 작성하는 칸으로, 입력한 값이 생성 코드에 그대로 들어갑니다. (예: 정수 타입 → Java 는 Long, TypeScript 는 number). 비우면 Fallback target 을 사용합니다.

매핑을 지정하지 않은 타입은 Fallback 설정을 따릅니다.

필드	설정 내용
`Fallback target`	매핑되지 않은 타입에 사용할 기본 대상 타입입니다. 예: Java 는 java.lang.Object, TypeScript 는 any. 실제 생성 코드에 반영됩니다.
`Fallback import`	그 fallback 타입에 필요한 기본 import 경로입니다. 예: java.lang.Object.
`Fallback category`	fallback 타입의 분류값입니다. 보통 Fallback target 만 지정하면 되므로 그대로 두어도 됩니다.

저장과 배포

[팩 저장] 버튼 클릭하여 저장한 템플릿팩은 작성자 본인에게만 노출되며, 다른 유저에게는 공개되지 않습니다.
다른 유저에게 탬플릿팩을 공개하려면 [배포]를 통해 공개하면 됩니다.
템플릿팩을 수정한 경우에도 '저장'만으로는 변경 사항이 작성자에게만 적용됩니다.
해당 템플릿팩을 사용하는 다른 유저에게 변경 사항을 반영하려면 '배포'를 클릭하여 새로운 버전을 게시하거나 현재 버전을 재배포해야 합니다.

[배포] 클릭

배포 다이얼로그에서 "새 버전으로 배포" 또는 "현재 버전 덮어쓰기" 를 선택합니다.

새 버전으로 배포

버전 번호가 올라간 불변 스냅샷이 만들어집니다. 이 팩을 쓰는 프로젝트들에는 업그레이드 안내가 표시되고, 각자 원하는 시점에 업그레이드합니다.

현재 버전 덮어쓰기

마지막 버전을 그대로 교체합니다. 오타 수정처럼 버전을 올릴 필요가 없는 변경에 사용하세요.

버전 탭

게시된 버전 목록을 확인하고, 특정 버전을 [초안으로 복원] 해 그 시점부터 다시 작업하거나, [최신으로 재게시] 해 이전 버전으로 롤백할 수 있습니다.

참고: git 에 비유하면 초안은 워킹 카피, 배포는 push 입니다. 게시된 버전은 불변이므로, 사용자 프로젝트를 깨뜨릴 걱정 없이 초안을 계속 고칠 수 있습니다.

공개와 멤버 관리

생성한 템플릿팩은 Store 에 공개하거나, 특정 사용자를 멤버로 초대해 비공개로 협업할 수 있습니다.

공개 / 비공개

[공개] 를 누르면 템플릿팩이 Store 에 공개되어 누구나 추가(Add)·복제(Clone)·즐겨찾기(Favorite)할 수 있습니다. [공개 해제] 로 되돌리면 멤버만 접근할 수 있는 비공개 팩이 됩니다.

멤버 초대

멤버 탭에서 이메일(쉼표로 여러 명)을 입력하고 역할을 정해 초대를 보냅니다. 수락 전 초대는 "대기 중인 초대" 목록에서 취소할 수 있습니다.

역할	할 수 있는 일
`ROLE_OWNER`	모든 권한 — 멤버·역할 관리, 공개 전환, 팩 삭제
`ROLE_MAINTAINER`	템플릿 편집과 배포, CONTRIBUTOR/VIEWER 초대
`ROLE_CONTRIBUTOR`	템플릿 편집 (초안 작업)
`ROLE_VIEWER`	보기와 사용

참고: 멤버는 "템플릿팩 나가기" 버튼을 통해 스스로 해당 템플릿팩의 멤버에서 나갈 수 있습니다. 소유자가 "팩 삭제" 를 실행하면 모든 버전·멤버·각 멤버의 편집 초안이 제거되며 복구할 수 없습니다.

내보내기 · 가져오기

팩은 폴더 또는 ZIP 파일로 내보내고 가져올 수 있습니다.

형식	용도
폴더로 (외부 편집용)	템플릿 파일을 IDE 등 외부 편집기로 직접 고치고 싶을 때. 수정 후 [가져오기...] 로 다시 반영합니다.
ZIP 파일로	백업하거나 Store 를 거치지 않고 파일로 전달할 때.