템플릿팩 만들기

팀의 코딩 컨벤션에 맞는 코드를 뽑아내고 싶다면 템플릿팩을 직접 만들 수 있습니다. 팩을 만들고, 템플릿을 작성하고, 배포·공유하는 제작자 관점의 흐름을 안내합니다.

팩의 구성 요소

템플릿팩 하나는 아래 요소로 구성됩니다. 만들기 → 저장(초안) → 배포(버전 게시) → 공개·초대(공유) 순서로 진행됩니다.

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

팩 만들기

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

[신규] 클릭

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

이름과 언어 선택

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

기본 정보 입력

상단 카드에서 이름·작성자·설명을 다듬습니다. 언어 프로필의 세부 내용은 생성 후 Settings 탭에서 관리합니다.

Tip

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

템플릿 작성

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

그룹 트리

[최상위 그룹 추가] · [새 템플릿 추가] 버튼이나 우클릭 메뉴로 항목을 만들고, 드래그 앤 드롭으로 옮깁니다. 이 트리 구조가 코드 생성 모달에 그대로 보이므로, 사용하는 사람이 고르기 쉽게 정리하세요.

템플릿 속성과 본문

이름·타입·설명·태그를 정하고 Velocity 본문을 작성합니다. 본문 에디터는 찾기/바꾸기를 지원합니다. 태그를 달아두면 생성 모달의 태그 필터로 활용됩니다.

Installation — 설치 규칙

생성 결과물이 디스크 어디에 어떻게 쓰일지 정의합니다. 데스크탑 앱의 "선택 템플릿 설치" 가 이 규칙을 따릅니다.

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

템플릿 문법 (Velocity)

본문은 Apache Velocity 문법으로 작성합니다. 생성 시점에 테이블 정보와 사용자가 입력한 설정 값이 변수로 주입됩니다. (Velocity User Guide)

변수	내용
`$entity`	현재 테이블(엔티티) — 이름(name)과 이름 변형(var·snakeLower·kebabLower 등), 필드 목록(fields), Soft Delete 설정, 그리고 팩이 선언한 엔티티 변수 값
`$field`	필드(컬럼) — 필드 목록 순회에 사용. 이름, 코멘트, 타입 매핑 결과(mappedType), 팩이 선언한 필드 변수 값
`$env`	프로젝트 전역 변수 — 사용자가 프로젝트 설정의 Templates Variables 에 입력한 값. 점(.) 키는 중첩으로 접근합니다 (예: $env.package.core)
`$types`	타입 헬퍼 (모든 언어 공통) — 필드의 확정 타입에서 simple name($types.typeOf), import 용 full name($types.importOf), 분류 판별($types.isDate, $types.isNumber 등)을 제공
`$codegen`	공통 생성 헬퍼 — 네이밍 변환(toUpperCamel·toLowerCamel·toUpperUnderscore), DBMS 판별(isOracle·isMySQL 등), PK 정보 조회 등
`$java · $ts · $py`	언어별 보조 헬퍼 (선택) — 쓰면 편리하지만, $types 만으로도 기본 동작이 가능합니다

예시 — Java 엔티티 클래스

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

package ${env.package.core};

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

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

참고: 렌더 결과는 프로젝트에서 "소스코드 생성..." 모달을 열어 실제 테이블로 확인하는 것이 가장 정확합니다. 편집 권한이 있는 팩이라면 미리보기 화면에서 곧바로 원본 수정 모드로 전환해 고치고 저장할 수도 있습니다.

언어 프로필 (Settings 탭)

Settings 탭은 팩이 "나는 이 언어로 생성하고, 이런 입력이 필요하다" 를 선언하는 곳입니다. 여기서 선언한 내용이 사용하는 쪽 화면의 입력 폼과 타입 기본값을 만들어 냅니다.

타입 매핑

DB 컬럼 타입 → 중간 타입 변환은 NeoSQL 이 자동 처리합니다. 제작자는 중간 타입별로 이 언어의 대상 타입(target)·import·분류(category)만 정하면 됩니다. 비워둔 타입은 Fallback 설정으로 처리됩니다.

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

변수를 선언하면 사용하는 쪽 화면에 입력 폼이 자동으로 생깁니다. key, 라벨, 입력 유형, 기본값, 필수 여부, (select 의) 옵션을 정의하세요.

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

Tip

key 에 점(.)을 넣으면 네임스페이스가 됩니다 — package.core 로 선언하면 템플릿에서 $env.package.core 로 접근합니다. "기본값으로 리셋" 버튼으로 언제든 언어 프리셋 기본값으로 되돌릴 수 있습니다.

저장과 배포

[팩 저장] 은 내 초안(워크스페이스)에 저장합니다. 초안은 내 프로젝트에는 곧바로 반영되지만 다른 사람에게는 보이지 않습니다. 다른 사람·다른 프로젝트가 쓰게 하려면 [배포] 로 버전을 게시해야 합니다.

[배포] 클릭

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

새 버전으로 배포

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

현재 버전 덮어쓰기

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

버전 탭

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

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

공개와 멤버 관리

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

공개 / 비공개

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

멤버 초대

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

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

참고: 멤버는 "템플릿팩 나가기" 로 스스로 빠질 수 있습니다 (팩 자체는 유지). 소유자의 "팩 삭제" 는 모든 버전·멤버·워크스페이스를 제거하며 되돌릴 수 없습니다.

내보내기 · 가져오기

팩은 폴더 또는 ZIP 파일로 내보내고 가져올 수 있습니다. 두 형식은 같은 구조입니다.

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