Java Entity Table Spec Generator

Java JPA Entity 클래스를 자동으로 분석하여 데이터베이스 테이블 명세서와 DDL 스크립트를 생성하는 Python 도구

📋 목차

소개
주요 기능
설치
사용법
출력 파일
지원 어노테이션
주의사항
라이센스
기여

🎯 소개

Spring Boot/JPA 프로젝트에서 Entity 클래스를 작성한 후, 별도로 테이블 명세서를 작성하는 것은 번거롭고 실수하기 쉬운 작업입니다. 이 도구는 Java Entity 클래스를 자동으로 분석하여 다음을 생성합니다:

📊 Excel 테이블 명세서 (테이블별 시트)
📝 Markdown 문서 (가독성 좋은 문서)
🔧 MySQL DDL 스크립트 (COMMENT 추가용, 안전한 ALTER TABLE 구문)

Entity 코드가 곧 문서가 되어, 코드와 문서의 불일치를 방지하고 생산성을 높일 수 있습니다.

✨ 주요 기능

🔍 자동 파싱

JPA Entity 어노테이션 자동 인식 (@Entity, @Table, @Column 등)
패키지 구조 및 클래스 정보 추출
필드 타입, 제약조건, 설명 자동 수집

🎨 다양한 출력 형식

Excel (.xlsx): 테이블별 시트로 구성, 필터링 및 정렬 가능
Markdown (.md): GitHub 등에서 바로 볼 수 있는 문서
SQL (.sql): 실제 DB에 COMMENT를 추가하는 안전한 DDL

🔐 안전한 DDL 생성

DB 연결 모드: 실제 DB 스키마 기반으로 DDL 생성 (타입, Nullable 등 보존)
Entity 모드: Entity 정보만으로 DDL 생성 (검토 후 실행 권장)

🎯 고급 기능

Enum 타입 지원: @Enumerated(EnumType.STRING/ORDINAL) 자동 인식
관계 매핑 지원: @ManyToOne, @OneToOne, @OneToMany, @ManyToMany
외래키 정보 자동 추출: FK 관계를 COMMENT에 자동 추가
커스텀 설명: @Description 어노테이션 지원
상세 로그: 파싱 과정을 .log 파일로 기록

📦 설치

요구사항

Python 3.7 이상
pip

필수 패키지 설치

pip install pandas openpyxl mysql-connector-python

또는 requirements.txt 사용:

pip install -r requirements.txt

requirements.txt:

pandas>=1.3.0
openpyxl>=3.0.0
mysql-connector-python>=8.0.0

🚀 사용법

기본 사용 (Entity만 분석)

python3 entity_spec_generator.py /path/to/your/spring-project

DB 연결하여 안전한 DDL 생성 (권장)

python3 entity_spec_generator.py /path/to/your/spring-project \
  --db-host localhost \
  --db-port 3306 \
  --db-user root \
  --db-password yourpassword \
  --db-name yourdatabase

출력 디렉토리 지정

python3 entity_spec_generator.py /path/to/your/spring-project \
  -o ./output \
  --db-host localhost \
  --db-user root \
  --db-password password \
  --db-name mydb

로그 파일 경로 지정

python3 entity_spec_generator.py /path/to/your/spring-project \
  --log ./debug.log

명령어 옵션

옵션	설명	필수	기본값
`project_path`	Spring 프로젝트 루트 경로	✅	-
`-o, --output`	출력 파일 저장 경로	❌	`.` (현재 디렉토리)
`--log`	로그 파일 경로	❌	자동 생성
`--db-host`	MySQL 호스트	❌	-
`--db-port`	MySQL 포트	❌	`3306`
`--db-user`	MySQL 사용자명	❌	-
`--db-password`	MySQL 비밀번호	❌	-
`--db-name`	데이터베이스명	❌	-

📂 출력 파일

실행 후 다음 파일들이 생성됩니다:

1. 테이블명세서.xlsx

"테이블 목록" 시트: 전체 테이블 개요
개별 테이블 시트: 각 테이블의 상세 컬럼 정보
- 컬럼명, 필드명, Java/DB 타입
- PK, FK, AUTO_INCREMENT, Nullable, Unique
- Enum 정보, 설명

2. 테이블명세서.md

GitHub/GitLab 등에서 바로 볼 수 있는 Markdown 문서
테이블 목록 + 개별 테이블 상세 정보

3. add_comments.sql

실제 DB에 COMMENT를 추가하는 DDL 스크립트
DB 연결 시: 실제 DB 컬럼 정의를 유지하며 안전하게 생성
Entity만 사용 시: 반드시 검토 후 실행

-- 예시
ALTER TABLE `user` COMMENT '사용자';
ALTER TABLE `user` MODIFY COLUMN `user_id` bigint NOT NULL auto_increment COMMENT '사용자ID';
ALTER TABLE `user` MODIFY COLUMN `email` varchar(100) NOT NULL COMMENT '이메일 주소';
ALTER TABLE `user` MODIFY COLUMN `status` varchar(20) NOT NULL COMMENT '상태 [Enum:STRING]';

4. entity_parser_YYYYMMDD_HHMMSS.log

파싱 과정의 상세 로그
어노테이션 추출 과정, 오류 발생 시 디버깅에 유용

🏷️ 지원 어노테이션

JPA 기본 어노테이션

@Entity: 엔티티 클래스 인식
@Table(name="..."): 테이블명 지정
@Id: Primary Key
@GeneratedValue: AUTO_INCREMENT
@Column: 컬럼 속성 (name, nullable, length, unique 등)

관계 매핑

@ManyToOne + @JoinColumn: FK 컬럼 생성 (N:1)
@OneToOne + @JoinColumn: FK 컬럼 생성 (1:1)
@OneToMany: 상대 테이블에 FK (현재 테이블에는 컬럼 없음)
@ManyToMany: 중간 테이블 사용 (현재 테이블에는 컬럼 없음)

컬렉션 매핑

@ElementCollection + @CollectionTable: 별도 테이블 (스킵)
@JoinTable: ManyToMany 중간 테이블 (스킵)

Enum 타입

@Enumerated(EnumType.STRING): VARCHAR로 매핑
@Enumerated(EnumType.ORDINAL): INT로 매핑

커스텀 어노테이션

@Description("설명"): 테이블/컬럼 설명 (커스텀 어노테이션)

📝 Entity 예제

@Getter
@NoArgsConstructor
@Entity
@Table(name="user")
@Description("사용자")
public class User {

    @Id
    @GeneratedValue(strategy=GenerationType.IDENTITY)
    @Description("사용자ID")
    @Column(nullable=false)
    private Long id;

    @Description("이메일 주소")
    @Column(nullable=false, length=100, unique=true)
    private String email;

    @Description("사용자명")
    @Column(nullable=false, length=50)
    private String userName;

    @Description("상태")
    @Enumerated(EnumType.STRING)
    @Column(nullable=false, length=20)
    private UserStatus status;

    @Description("소속 팀")
    @ManyToOne(fetch=FetchType.LAZY)
    @JoinColumn(name="team_id", nullable=false)
    private Team team;
    
    // 생략...
}

⚠️ 주의사항

🚨 면책 조항

본 도구는 "있는 그대로(AS-IS)" 제공되며, 사용으로 인해 발생하는 모든 결과에 대한 책임은 사용자에게 있습니다.

생성된 DDL 스크립트는 반드시 검토 후 실행하세요
- 특히 프로덕션 환경에서는 더욱 신중해야 합니다
- 백업을 먼저 수행하세요
파싱 오류 가능성
- 복잡한 Entity 구조나 특수한 어노테이션 조합에서 오류가 발생할 수 있습니다
- 로그 파일(.log)을 확인하여 파싱 결과를 검증하세요
DB 연결 사용 권장
- --db-host 등의 옵션을 사용하여 실제 DB와 연결하면 더 안전한 DDL이 생성됩니다
- Entity 정보만으로 생성된 DDL은 실제 DB와 차이가 있을 수 있습니다
지원하지 않는 기능
- @Inheritance, @MappedSuperclass 등의 상속 관계
- 복잡한 @AttributeConverter
- DB별 특화 기능 (현재는 MySQL만 지원)
보안
- 비밀번호를 명령줄에 직접 입력하지 말고, 환경변수나 설정 파일을 사용하세요
- 생성된 로그 파일에 민감한 정보가 포함될 수 있습니다

🛠️ 트러블슈팅

문제: Entity가 인식되지 않습니다

@Entity 어노테이션이 있는지 확인하세요
프로젝트 경로가 올바른지 확인하세요
로그 파일을 확인하여 파싱 오류를 확인하세요

문제: 특정 필드가 누락됩니다

@ElementCollection, @CollectionTable 등은 의도적으로 스킵됩니다
로그 파일에서 "SKIP" 메시지를 확인하세요

문제: DDL 실행 시 오류가 발생합니다

DB 연결 모드(--db-host)를 사용하세요
생성된 SQL을 수동으로 검토하고 수정하세요

📄 라이센스

본 프로젝트는 MIT 라이센스 하에 배포됩니다.

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🤝 기여

기여를 환영합니다! 다음과 같은 방법으로 참여할 수 있습니다:

이슈 등록: 버그 리포트, 기능 제안
Pull Request: 코드 개선, 새 기능 추가, 문서 수정
테스트: 다양한 환경에서 테스트 후 피드백 제공

개발 환경 설정

# 저장소 클론
git clone https://github.com/yourusername/java-entity-spec-generator.git
cd java-entity-spec-generator

# 가상환경 생성 (선택사항)
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

# 테스트 실행
python3 entity_spec_generator.py ./test-project

📧 문의

Issues: GitHub Issues
Email: imdevbada@gmail.com

🙏 감사의 말

이 프로젝트는 Spring Boot/JPA 프로젝트에서 Entity와 문서의 일관성을 유지하기 위해 시작되었습니다. 사용해주시고 피드백을 주시는 모든 분들께 감사드립니다.

Happy Coding! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.gitignore		.gitignore
README.md		README.md
java-entity-table-spec-generator.py		java-entity-table-spec-generator.py
license.txt		license.txt
requirements_txt.txt		requirements_txt.txt

License

devbada/java-entity-table-spec-generator

Folders and files

Latest commit

History

Repository files navigation