Telosys JPA Starter (config-driven entity & repository generator)
DB 스키마 → JPA 엔티티 + 레포지토리 자동 생성기.
- 컬럼명 기반
@Convert/enum 매핑은 설정 파일 한 개(converters.csv) 로 관리 - DB 컬럼 코멘트는 필드 Javadoc 으로 자동 삽입
- 모든 출력 경로는
telosys-tools.cfg의 4개 변수로 통제
새 프로젝트에 이 폴더를 풀고 3개 파일 + cfg 의 4개 경로 변수 만 채우면 됩니다.
TelosysTools/
├── telosys-tools.cfg ← ① 4개 패키지 경로 수정
├── databases.yaml ← ② DB 접속정보 수정 (커밋 금지)
├── lib/ ← ③ JDBC 드라이버 jar 넣기
├── models/ (자동 생성됨)
└── templates/
├── jpa-entities/ Base/Concrete 엔티티 생성 bundle
│ ├── templates.cfg (출력 경로 규칙)
│ ├── converters.csv ← ④ 컨버터 매핑 키 입력 (핵심)
│ ├── include/ (수정 불필요)
│ └── main-java/
│ ├── XxxBase_java.vm @MappedSuperclass 부모 생성
│ └── XxxConcrete_java.vm @Entity 자식 생성
└── jpa-repositories/ Base/Concrete 레포지토리 생성 bundle
├── templates.cfg
├── include/
└── main-java/
├── XxxRepositoryBase_java.vm @NoRepositoryBean 부모 인터페이스 생성
└── XxxRepositoryConcrete_java.vm @Repository 자식 인터페이스 생성
생성 구조 (Base / Concrete 상속)
엔티티 — jpa-entities bundle
각 테이블마다 2개 클래스 생성:
<Entity>Base.java—@MappedSuperclass, DB와 항상 1:1 (매번 재생성, 절대 수정 금지). 모든 컬럼·@Convert매핑·DB 컬럼 코멘트(Javadoc)가 여기.<Entity>.java—@Entity extends <Entity>Base, 커스텀 영역 (없을 때만 1회 생성 → 재생성해도 보존). 비즈니스 로직·예외 매핑(@Convert(attributeName=...),@AttributeOverride) 은 여기.
${ENTITY_BASE_PKG}/<Entity>Base.java (재생성됨, 손대지 마세요)
${ENTITY_CONCRETE_PKG}/<Entity>.java (커스텀, 보존됨)
레포지토리 — jpa-repositories bundle
각 테이블마다 2개 인터페이스 생성:
<Entity>JpaRepositoryBase.java—@NoRepositoryBean,JpaRepository<E,PK> + JpaSpecificationExecutor<E>상속 (매번 재생성, 수정 금지). 주요 컬럼 코멘트 Javadoc 포함.<Entity>JpaRepository.java—@Repository extends <Entity>JpaRepositoryBase, 커스텀 쿼리 영역 (없을 때만 1회 생성 → 재생성해도 보존). 모든 커스텀 메소드 /@Query는 여기.
${REPO_BASE_PKG}/<Entity>JpaRepositoryBase.java (재생성됨, 손대지 마세요)
${REPO_CONCRETE_PKG}/<Entity>JpaRepository.java (커스텀 쿼리, 보존됨)
0. Telosys CLI 설치 (PC당 1회)
mkdir -p ~/tools/telosys && cd ~/tools/telosys
curl -sL -o t.zip https://github.com/telosys-tools-bricks/telosys-cli/releases/download/4.3.0-001/telosys-cli-4.3.0-001.zip
unzip -o t.zip && chmod +x tt
# 실행 별칭: alias tt='~/tools/telosys/tt'
1. 새 프로젝트에 풀기
이 zip 을 프로젝트 루트에서 풀면 TelosysTools/ 가 생깁니다.
2. 파일 채우기
telosys-tools.cfg: 4개 경로 변수 수정ProjectVariable.ENTITY_BASE_PKG(예:com.daewoong.platform.file.infrastructure.entity)ProjectVariable.ENTITY_CONCRETE_PKG(예:com.daewoong.platform.file.infrastructure.entity.concrete)ProjectVariable.REPO_BASE_PKG(예:com.daewoong.platform.file.infrastructure.persistence)ProjectVariable.REPO_CONCRETE_PKG(예:com.daewoong.platform.file.infrastructure.persistence.concrete)
databases.yaml:HOST/DBNAME/USER/PASSWORD수정lib/: DB용 JDBC 드라이버 jar 넣기templates/jpa-entities/converters.csv:컬럼명 ; enumFQN ; 컨버터FQN입력
3. 생성
cd <project-root>
~/tools/telosys/tt
telosys> h . # home = 프로젝트 루트
telosys> cdb db # DB 연결 확인
telosys> nm mymodel db # DB에서 모델 추출 (한 번만 — .entity 는 손으로 관리)
telosys> m mymodel
telosys> b jpa-entities # 엔티티 bundle 선택
telosys> gen * * # → y (전 엔티티 Base/Concrete 생성)
telosys> b jpa-repositories # 레포지토리 bundle 선택
telosys> gen * * # → y (전 레포지토리 Base/Concrete 생성)
동작 원리
- 컬럼 매핑 :
converters.csv의 컬럼명과 일치하는 Base 필드는@Convert(converter=...) private <enum> ...로 생성. 매핑 없는 컬럼은 표준 타입. - 컬럼 코멘트 : DB 의 column comment 가 있으면 자동으로
/** comment */Javadoc 으로 Base 필드에 삽입. 레포지토리 Base 의 클래스 Javadoc 에도 컬럼별 요약이 들어감. - 개별 예외 : 특정 테이블만 다르게 → 그
.entity컬럼에#javaType(...) #converter(...)태그로 override. - 새 컨버터 추가 =
converters.csv한 줄. 템플릿·엔티티 무수정. - PK 타입 : Base 의 키 attribute 에서 자동 추출 (
@Id컬럼의 Java 타입). 단일 키 가정. - DB 스키마 변경 시 재생성 → Base 만 갱신 (새 컬럼·코멘트 반영), Concrete 의 커스텀은 보존.
주의
.entity모델 파일은 한 번 추출 후 손으로 관리하는 소스 입니다 (DB 재추출이 덮어쓰지 않음). git 에 커밋해 관리하세요.databases.yaml은 비밀번호 때문에.gitignore에 추가 권장.ENTITY_CONCRETE_PKG/REPO_CONCRETE_PKG는ENTITY_BASE_PKG/REPO_BASE_PKG의 서브패키지가 아니어도 됩니다 — 프로젝트 구조에 맞게 자유롭게 지정 가능.- 이전 버전에서 마이그레이션 : 자식 엔티티 위치가
template→concrete로 변경됐습니다. 기존*.template/폴더는 다음 재생성 시 orphan 되므로 직접 삭제 또는 이동 필요.