1. 엔티티 클래스 관련 애너테이션
| 애너테이션 |
설명 |
주요 속성 |
예시 |
| @Entity |
클래스를 JPA 엔티티로 선언. |
없음 |
@Entity public class User { } |
| @Table |
엔티티와 데이터베이스 테이블을 매핑. |
name(테이블 이름), schema, uniqueConstraints |
@Table(name = "users", schema = "public") |
1.1. @Entity
- 클래스가 JPA 엔티티임을 나타냅니다.
- 반드시 기본 생성자(파라미터 없는 생성자)가 있어야 합니다.
@Entity
public class User {
// 엔티티 클래스
}
1.2. @Table
- 엔티티와 데이터베이스 테이블 이름을 매핑합니다.
- 생략하면 엔티티 클래스 이름이 테이블 이름으로 사용됩니다.
- 추가 속성:
- name: 테이블 이름
- schema: 스키마 이름
- catalog: 카탈로그 이름
- uniqueConstraints: 테이블에 대한 유니크 제약 조건 설정
@Entity
@Table(name = "users", schema = "public")
public class User {
// 테이블 users에 매핑
}
2. 필드 매핑 관련 애너테이션
| 애너테이션 |
설명 |
주요 속성 |
예시 |
| @Id |
기본 키(Primary Key)를 지정. |
없음 |
@Id private Long id; |
| @GeneratedValue |
기본 키 생성 전략 지정. |
strategy(키 생성 방식) |
@GeneratedValue(strategy = GenerationType.IDENTITY) |
| @Column |
필드와 테이블 컬럼 매핑. |
name, nullable, unique, length |
@Column(name = "user_name", nullable = false, length = 100) |
| @Lob |
대용량 데이터(BLOB, CLOB) 매핑. |
없음 |
@Lob private String description; |
| @Temporal |
날짜/시간 데이터 매핑. |
TemporalType(DATE, TIME, TIMESTAMP) |
@Temporal(TemporalType.TIMESTAMP) private Date createdAt; |
| @Enumerated |
Enum 타입 매핑. |
EnumType(ORDINAL, STRING) |
@Enumerated(EnumType.STRING) private UserRole role; |
| @Transient |
필드를 데이터베이스에 매핑하지 않음. |
없음 |
@Transient private String tempData; |
2.1. @Id
- 해당 필드가 엔티티의 **기본 키(Primary Key)**임을 나타냅니다.
@Id
private Long id;
2.2. @GeneratedValue
JPA의 @GeneratedValue 전략
- 기본 키 값의 생성 전략을 지정합니다.
- 주요 옵션:
- GenerationType.IDENTITY: 데이터베이스에 기본 키 생성을 위임.
- GenerationType.SEQUENCE: 데이터베이스의 시퀀스를 사용.
- GenerationType.TABLE: 별도의 키 생성용 테이블을 사용.
- GenerationType.AUTO: 데이터베이스 방언에 맞는 전략을 자동으로 선택.
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
2.3. @Column
JPA - @Column 데이터베이스 컬럼 매핑
- 엔티티 필드와 테이블 컬럼 간 매핑을 정의합니다.
- 추가 속성:
- name: 컬럼 이름
- nullable: null 허용 여부
- unique: 유니크 제약 조건
- length: 문자열 길이
- precision, scale: 숫자 데이터 타입의 소수점 자릿수 정의
@Column(name = "user_name", nullable = false, length = 100)
private String name;
2.4. @Lob
- 필드를 BLOB 또는 CLOB 데이터 타입으로 매핑합니다.
- 대용량 데이터(텍스트, 바이너리)를 처리할 때 사용합니다.
@Lob
private String description;
2.5. @Temporal
- 날짜/시간 데이터 매핑에 사용.
- 옵션:
- TemporalType.DATE: 날짜만 저장 (yyyy-MM-dd).
- TemporalType.TIME: 시간만 저장 (HH:mm:ss).
- TemporalType.TIMESTAMP: 날짜와 시간 저장 (yyyy-MM-dd HH:mm:ss).
@Temporal(TemporalType.TIMESTAMP)
private Date createdAt;
2.6. @Enumerated
- Enum 타입을 데이터베이스에 저장할 때 사용.
- 옵션:
- EnumType.ORDINAL: Enum의 순서값 저장.
- EnumType.STRING: Enum 이름을 문자열로 저장(권장).
@Enumerated(EnumType.STRING)
private UserRole role;
2.7. @Transient
- 해당 필드는 데이터베이스에 저장되지 않습니다.
- JPA가 관리하지 않는 필드를 정의할 때 사용.
@Transient
private String tempData;
3. 관계 매핑 관련 애너테이션
| 애너테이션 |
설명 |
주요 속성 |
예시 |
| @OneToOne |
엔티티 간 1:1 관계 매핑. |
mappedBy, cascade, fetch |
@OneToOne @JoinColumn(name = "profile_id") private UserProfile profile; |
| @OneToMany |
엔티티 간 1:N 관계 매핑. |
mappedBy, cascade, fetch |
@OneToMany(mappedBy = "department", cascade = CascadeType.ALL) private List<Employee> employees; |
| @ManyToOne |
엔티티 간 N:1 관계 매핑. |
cascade, fetch |
@ManyToOne @JoinColumn(name = "department_id") private Department department; |
| @ManyToMany |
엔티티 간 N:M 관계 매핑. |
mappedBy, cascade, fetch |
@ManyToMany @JoinTable(name = "student_course") private List<Course> courses; |
| @JoinColumn |
외래 키를 매핑. |
name, referencedColumnName |
@JoinColumn(name = "department_id") |
| @JoinTable |
중간 테이블을 정의. |
name, joinColumns, inverseJoinColumns |
@JoinTable(name = "student_course") |
3.1. @OneToOne
- 엔티티 간 1:1 관계를 매핑합니다.
- @JoinColumn으로 외래 키를 지정합니다.
@OneToOne
@JoinColumn(name = "profile_id")
private UserProfile profile;
3.2. @OneToMany
- 엔티티 간 1:N 관계를 매핑합니다.
- 기본적으로 **지연 로딩(Lazy Loading)**이 설정됩니다.
@OneToMany(mappedBy = "department", cascade = CascadeType.ALL)
private List<Employee> employees;
3.3. @ManyToOne
- 엔티티 간 N:1 관계를 매핑합니다.
- 외래 키를 사용하는 다대일 관계를 정의합니다.
@ManyToOne
@JoinColumn(name = "department_id")
private Department department;
3.4. @ManyToMany
- 엔티티 간 N:M 관계를 매핑합니다.
- 중간 테이블(@JoinTable)을 통해 매핑합니다.
@ManyToMany
@JoinTable(
name = "student_course",
joinColumns = @JoinColumn(name = "student_id"),
inverseJoinColumns = @JoinColumn(name = "course_id")
)
private List<Course> courses;
4. 고급 매핑 애너테이션
| 애너테이션 |
설명 |
주요 속성 |
예시 |
| @MappedSuperclass |
공통 엔티티 속성을 상속받도록 정의. |
없음 |
@MappedSuperclass public abstract class BaseEntity { } |
| @Embeddable |
값 타입 클래스를 정의. |
없음 |
@Embeddable public class Address { } |
| @Embedded |
값 타입 필드를 엔티티에 포함. |
없음 |
@Embedded private Address address; |
| @Inheritance |
상속 매핑 전략 정의. |
strategy(SINGLE_TABLE, JOINED, TABLE_PER_CLASS) |
@Inheritance(strategy = InheritanceType.JOINED) |
4.1. @MappedSuperclass
- 공통적으로 사용되는 엔티티 속성을 상속받을 수 있도록 정의.
- 데이터베이스에는 별도의 테이블이 생성되지 않음.
@MappedSuperclass
public abstract class BaseEntity {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Temporal(TemporalType.TIMESTAMP)
private Date createdAt;
}
4.2. @Embeddable / @Embedded
- 값 타입을 객체로 매핑할 때 사용.
- @Embeddable: 내장될 클래스에 사용.
- @Embedded: 내장 필드에 사용.
@Embeddable
public class Address {
private String city;
private String street;
}
@Entity
public class User {
@Embedded
private Address address;
}
4.3. @Inheritance
- 상속 구조를 매핑.
- 옵션:
- InheritanceType.SINGLE_TABLE: 단일 테이블 전략(기본값).
- InheritanceType.JOINED: 정규화된 테이블 전략.
- InheritanceType.TABLE_PER_CLASS: 클래스마다 테이블 생성.
@Entity
@Inheritance(strategy = InheritanceType.JOINED)
public class BaseEntity {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
}
5. 기타 유용한 애너테이션
| 애너테이션 |
설명 |
주요 속성 |
예시 |
| @Version |
낙관적 락(Optimistic Lock)을 위한 버전 관리. |
없음 |
@Version private int version; |
| @Access |
필드 또는 프로퍼티 접근 방식 지정. |
AccessType(FIELD, PROPERTY) |
@Access(AccessType.FIELD) |
5.1. @Version
- 엔티티의 버전을 관리하여 **낙관적 락(Optimistic Locking)**을 구현할 때 사용.
@Version
private int version;
5.2. @Access
- 필드 접근(Field Access) 또는 프로퍼티 접근(Property Access) 방식을 지정.
@Access(AccessType.FIELD)
private String name;