[JAVA] @Entity, @Id, @GeneratedValue 완벽 가이드 – JPA 기본부터 실무 팁까지

Spring Data JPA를 사용하기 위해서는 도메인 객체를 엔티티(Entity)로 선언하고, 그에 맞는 기본 키(PK)를 설정하는 것이 필수입니다. @Entity, @Id, @GeneratedValue의 역할과 활용 방법을 구체적으로 설명합니다.

 

1. @Entity – 자바 클래스를 테이블로 매핑

@Entity는 해당 클래스가 JPA에서 관리하는 엔티티 객체임을 선언하는 어노테이션입니다. Spring Boot 프로젝트에서는 이 어노테이션만 붙이면 DB 테이블과 자동 매핑이 가능합니다.

예시:

@Entity
public class User {
    @Id
    private Long id;
    private String name;
}

주의사항:

• 기본 생성자(public User() {})가 반드시 있어야 합니다.
• 기본 키는 @Id로 반드시 설정해야 합니다.
• 클래스는 final이 아니어야 하며, 추상 클래스도 안 됩니다.

 

2. @Id – 기본 키(PK) 지정

@Id는 해당 필드를 DB의 기본 키로 지정합니다. 하나의 엔티티에 반드시 하나는 존재해야 하며, 보통 Long 또는 UUID를 많이 사용합니다.

예시:

@Entity
public class Product {
    @Id
    private Long productId;

    private String name;
}

만약 @Id만 선언하고 값을 직접 지정하지 않으면, insert 시 에러가 발생합니다. 따라서 자동 생성이 필요한 경우엔 @GeneratedValue를 함께 사용해야 합니다.

 

3. @GeneratedValue – 기본 키 자동 생성

@GeneratedValue는 @Id 필드에 대해 자동 생성 전략을 설정하는 어노테이션입니다. 대표적으로 다음 전략을 사용할 수 있습니다.

전략 종류:

• GenerationType.IDENTITY: DB의 Auto Increment 기능을 사용 (MySQL에 주로 사용)
• GenerationType.SEQUENCE: DB 시퀀스를 사용 (PostgreSQL, Oracle 등)
• GenerationType.TABLE: 키 생성용 별도 테이블을 사용 (비추천)
• GenerationType.AUTO: DB에 맞게 자동 선택 (권장되지 않음)

예시 (MySQL 기준):

@Entity
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String orderNumber;
}

주의: IDENTITY 전략은 영속성 컨텍스트의 지연 쓰기를 방해할 수 있으므로, 대량 INSERT 시에는 성능에 영향을 줄 수 있음을 고려해야 합니다.

 

4. 실무 팁

• 기본 키 타입은 Long을 가장 많이 사용하며, 실무에서는 UUID 전략을 사용하는 경우도 많습니다.
• 도메인 클래스에는 되도록 toString(), equals(), hashCode() 구현을 주의해서 작성해야 합니다 (무한 순환 주의).
• 복합 키가 필요한 경우엔 @EmbeddedId 또는 @IdClass를 사용할 수 있습니다.

 

5. 마무리

JPA의 기본은 엔티티 매핑이고, 그 중심에는 @Entity, @Id, @GeneratedValue가 있습니다. 이 세 가지를 정확히 이해하고 사용하는 것이 JPA 설계의 첫 단추입니다.

잘못된 매핑은 런타임 시점에 문제가 발생하기 때문에, 항상 정적 분석 + 테스트를 함께 병행하며 작성하는 습관이 중요합니다.