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

• 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

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

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

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

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

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

• 실제 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]';

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

• @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 중간 테이블 (스킵)

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

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

@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)" 제공되며, 사용으로 인해 발생하는 모든 결과에 대한 책임은 사용자에게 있습니다.

1. 생성된 DDL 스크립트는 반드시 검토 후 실행하세요

   • 특히 프로덕션 환경에서는 더욱 신중해야 합니다
   • 백업을 먼저 수행하세요

2. 파싱 오류 가능성

   • 복잡한 Entity 구조나 특수한 어노테이션 조합에서 오류가 발생할 수 있습니다
   • 로그 파일(.log)을 확인하여 파싱 결과를 검증하세요

3. DB 연결 사용 권장

   • --db-host 등의 옵션을 사용하여 실제 DB와 연결하면 더 안전한 DDL이 생성됩니다
   • Entity 정보만으로 생성된 DDL은 실제 DB와 차이가 있을 수 있습니다

4. 지원하지 않는 기능

   • @Inheritance, @MappedSuperclass 등의 상속 관계
   • 복잡한 @AttributeConverter
   • DB별 특화 기능 (현재는 MySQL만 지원)

5. 보안

   • 비밀번호를 명령줄에 직접 입력하지 말고, 환경변수나 설정 파일을 사용하세요
   • 생성된 로그 파일에 민감한 정보가 포함될 수 있습니다

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

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

• 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.

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

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

# 저장소 클론
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! 🚀