☕
JPA & Hibernate 치트시트

엔티티 매핑, 연관관계, 영속성 컨텍스트, N+1 해결(Fetch Join/Batch Size), Spring Data JPA 및 실무 성능 최적화 레퍼런스
#jpa#hibernate#spring-data-jpa#orm#database#java#sql#entity최종 업데이트: 2026-09-26
JPA & Hibernate 치트시트 핵심 명령어 및 실전 가이드

엔티티 매핑, 연관관계, 영속성 컨텍스트, N+1 해결(Fetch Join/Batch Size), Spring Data JPA 및 실무 성능 최적화 레퍼런스
## 1. 엔티티 기본 매핑 (Entity Mapping)
```java
@Entity
@Table(name = "users", indexes = {
    @Index(name = "idx_user_email", columnList = "email", unique = true)
})
@NoArgsConstructor(access = AccessLevel.PROTECTED) // 기본 생성자 필수 (JPA 프록시용)
@Getter
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY) // MySQL: AUTO_INCREMENT
    private Long id;

    @Column(nullable = false, length = 50)
    private String name;

    @Column(unique = true, updatable = false) // 생성 후 변경 불가
    private String email;

    @Enumerated(EnumType.STRING) // 반드시 STRING 사용! (ORDINAL 절대 금지)
    private RoleType role;

    @Lob // 대용량 텍스트 (CLOB / BLOB)
    private String description;

    @Transient // DB 컬럼 매핑 제외 (인메모리 임시 계산용)
    private boolean isTemporary;
}
```

## 2. 연관관계 매핑 (Associations: 1:N, N:1, 1:1)
```java
// [다대일 N:1] - 항상 연관관계의 주인(FK 보유 테이블)으로 설정
@Entity
public class OrderItem {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // 실무 원칙: 모든 연관관계는 LAZY(지연 로딩)로 설정!
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id") // 외래키 컬럼명 지정
    private Order order;
}

// [일대다 1:N] - 양방향 매핑 시 mappedBy로 거울 설정 (연관관계 주인 X)
@Entity
public class Order {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> orderItems = new ArrayList<>();

    // 연관관계 편의 메서드 (객체 양방향 상태 동기화)
    public void addOrderItem(OrderItem item) {
        orderItems.add(item);
        item.setOrder(this);
    }
}
```

## 3. 영속성 컨텍스트 & 라이프사이클 (Persistence Context)
```text
[영속성 컨텍스트의 4가지 상태]
1. 비영속 (New/Transient)  : 엔티티 객체만 생성, 영속성 컨텍스트와 무관 (new Member())
2. 영속 (Managed)          : em.persist(), find()로 컨텍스트에 저장 및 관리됨
3. 준영속 (Detached)       : 컨텍스트에서 분리되어 영속성 기능 미작동 (em.detach(), em.clear())
4. 삭제 (Removed)          : 삭제 대기 상태 (em.remove())

[영속성 컨텍스트의 핵심 이점]
• 1차 캐시               : 동일 트랜잭션 내 식별자(@Id) 기준 조회 시 쿼리 생략
• 동일성(Identity) 보장   : a == b 항상 true (동일 @Id 객체)
• 쓰기 지연 (Write-behind): 커밋 시점까지 INSERT/UPDATE SQL을 큐에 모아 일괄 실행
• 변경 감지 (Dirty Checking): 스냅샷 비교 후 엔티티 수정 시 커밋 시점에 자동으로 UPDATE 실행
```
```java
// 영속성 컨텍스트 수동 조작
em.persist(user);   // 비영속 → 영속
em.flush();         // 쓰기 지연 저장소의 SQL을 DB에 즉시 전송 (동기화)
em.clear();         // 1차 캐시 전체 비우기 (테스트 및 대량 작업 시 필수)
```

## 4. 지연 로딩 & N+1 문제 해결 (Lazy vs Eager & Fetch Join)
```text
[N+1 발생 원인]
루트 쿼리 1건 조회 후, 루프를 돌며 연관 엔티티 조회를 위해 N번의 추가 쿼리가 발생하는 현상
주의: @ManyToOne, @OneToOne 기본값은 EAGER(즉시 로딩)이므로 명시적으로 LAZY로 변경 필수!
```
```java
// 해결책 1: JPQL 페치 조인 (Fetch Join) - 1회 inner/left join으로 한번에 로딩
@Query("SELECT o FROM Order o JOIN FETCH o.member JOIN FETCH o.delivery")
List<Order> findAllWithMemberAndDelivery();

// 해결책 2: @EntityGraph (스프링 데이터 JPA 전용 간편 페치 조인)
@EntityGraph(attributePaths = {"member", "delivery"})
@Query("SELECT o FROM Order o")
List<Order> findAllOrders();

// 해결책 3: 페이징 시 컬렉션(@OneToMany) 페치 조인 한계 극복 -> default_batch_fetch_size
// application.yml 설정:
// spring.jpa.properties.hibernate.default_batch_fetch_size: 100
// 컬렉션 조회 시 WHERE parent_id IN (?, ?, ...) 쿼리로 N+1을 1+1로 축소!
```

## 5. Spring Data JPA Repository 핵심 쿼리
```java
public interface UserRepository extends JpaRepository<User, Long> {

    // 1. 메서드 이름 기반 자동 쿼리 생성
    List<User> findByNameAndStatus(String name, UserStatus status);
    List<User> findByNameContainingIgnoreCase(String keyword);
    boolean existsByEmail(String email);
    long countByRole(RoleType role);

    // 2. @Query (정적 JPQL 작성 및 DTO 직접 조회)
    @Query("SELECT u FROM User u WHERE u.role = :role ORDER BY u.createdAt DESC")
    List<User> findActiveUsers(@Param("role") RoleType role);

    // 3. 벌크 수정/삭제 연산 (@Modifying 필수, 1차 캐시 정리 옵션)
    @Modifying(clearAutomatically = true, flushAutomatically = true)
    @Query("UPDATE User u SET u.point = u.point + :bonus WHERE u.role = :role")
    int giveBonusPoints(@Param("bonus") int bonus, @Param("role") RoleType role);

    // 4. 페이징 및 슬라이스 (Pageable 전달)
    Page<User> findByStatus(UserStatus status, Pageable pageable);
    Slice<User> findByRole(RoleType role, Pageable pageable); // 무한 스크롤용 (totalCount 쿼리 생략)
}
```

## 6. DTO 프로젝션 (DTO Projection & Record)
```java
// 1. Java Record 기반 프로젝션 DTO
public record UserSummaryDto(Long id, String name, String email) {}

// 2. Repository에서 new 생성자 식을 사용한 직접 조회 (엔티티 영속화 오버헤드 X)
public interface UserRepository extends JpaRepository<User, Long> {
    @Query("SELECT new com.example.dto.UserSummaryDto(u.id, u.name, u.email) " +
           "FROM User u WHERE u.status = :status")
    List<UserSummaryDto> findSummaryByStatus(@Param("status") UserStatus status);
}

// 3. 인터페이스 기반 Closed 프로젝션 (스프링이 프록시 객체 자동 생성)
public interface UserSummary {
    Long getId();
    String getName();
}
```

## 7. 공통 매핑 (@MappedSuperclass & @Embedded)
```java
// 1. 등록/수정일 공통 엔티티 (Auditing 활성화)
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
@Getter
public abstract class BaseTimeEntity {
    @CreatedDate
    @Column(updatable = false)
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;
}

// 2. 값 타입 임베디드 (Embedded Value Type - 불변 객체 설계)
@Embeddable
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@AllArgsConstructor
public class Address {
    private String city;
    private String street;
    private String zipcode;
}

// 사용처:
@Embedded
private Address deliveryAddress;
```

## 8. 동시성 제어 (Optimistic vs Pessimistic Lock)
```java
// 1. 낙관적 락 (Optimistic Lock) - 충돌 빈도가 낮을 때 버전 필드로 동시성 검증
@Entity
public class Product {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Version // 수정 시 버전 불일치 발생하면 OptimisticLockException 발생
    private Long version;
}

// 2. 비관적 락 (Pessimistic Lock) - 충돌이 잦거나 재고 차감 등 즉시 DB 락 필요 시
public interface ProductRepository extends JpaRepository<Product, Long> {
    // SELECT ... FOR UPDATE 실행
    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("SELECT p FROM Product p WHERE p.id = :id")
    Optional<Product> findByIdWithPessimisticLock(@Param("id") Long id);
}
```

## 9. JPA 트랜잭션 & OSIV 설정
```yaml
# application.yml 권장 실무 설정
spring:
  jpa:
    open-in-view: false # [중요] OSIV 비활성화: DB 커넥션 낭비 방지 (Service 계층까지만 영속성 유지)
    hibernate:
      ddl-auto: validate # 로컬: update/create, 운영/스테이징: 반드시 validate 또는 none
    properties:
      hibernate:
        format_sql: true
        show_sql: false # p6spy 또는 로깅 라이브러리 사용 권장
        default_batch_fetch_size: 100 # N+1 완화용 IN 쿼리 배치 사이즈
```
```java
// 읽기 전용 트랜잭션 최적화
@Transactional(readOnly = true)
public List<UserResponse> getUsers() {
    // 스냅샷을 생성하지 않아 메모리 절약, flush가 스킵되어 성능 대폭 향상!
    return userRepository.findAll().stream().map(UserResponse::from).toList();
}
```

## 10. 실무 트러블슈팅 & 핵심 주의사항
```text
1. MultipleBagFetchException
   - 하나의 JPQL 페치 조인에서 둘 이상의 @OneToMany List 컬렉션을 동시 fetch join 시 발생
   - 해결: 하나만 fetch join하고 나머지는 default_batch_fetch_size로 가져오거나 Set으로 변경

2. 컬렉션 페치 조인 시 Paging 금지 (HHH000104 경고)
   - 1:N 관계를 fetch join 하면서 Pageable을 넘기면 모든 레코드를 메모리에 퍼올려 페이징 수행(OOM 발생 위험)
   - 해결: XToOne 관계만 fetch join하고 컬렉션은 batch_fetch_size로 지연 로딩

3. MySQL GenerationType.IDENTITY 시 saveAll() 쓰기 지연 비활성화
   - IDENTITY 전략은 PK 생성을 DB에 위임하므로 persist() 즉시 INSERT 쿼리가 실행되어 JDBC 배치 인서트 불가
   - 대량 데이터(Bulk Insert)는 JdbcTemplate.batchUpdate() 사용 권장

4. 영속성 전이(Cascade) 남용 주의
   - 단일 부모 엔티티가 자식의 라이프사이클을 완전히 관리할 때만 CascadeType.ALL, orphanRemoval = true 적용
```
💬
JPA & Hibernate 치트시트

의견 및 질문

댓글 수정

댓글 삭제
