2026년 Spring Data JPA 완벽 가이드

// Team.java
package com.kwonputer.domain;

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity
@Table(name = "teams")
public class Team {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

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

    // 양방향 연관관계의 주인이 아님 (읽기 전용)
    // mappedBy: Member 엔티티의 team 필드에 의해 매핑됨을 의미
    // CascadeType.ALL: Team이 영속화될 때 Member도 함께 영속화
    // orphanRemoval = true: 부모 엔티티에서 자식 엔티티가 제거되면 자식 엔티티도 DB에서 삭제
    @OneToMany(mappedBy = "team", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<Member> members = new ArrayList<>();

    protected Team() {}

    public Team(String name) {
        this.name = name;
    }

    // 연관관계 편의 메소드
    public void addMember(Member member) {
        this.members.add(member);
        member.setTeam(this); // Member의 team 필드도 설정
    }

    // Getter
    public Long getId() { return id; }
    public String getName() { return name; }
    public List<Member> getMembers() { return members; }

    // Setter (필요시 사용, 일반적으로 엔티티는 불변성을 지향)
    public void setName(String name) { this.name = name; }
}

// Member.java
package com.kwonputer.domain;

import jakarta.persistence.*;

&#64;Entity
&#64;Table(name = "members")
public class Member {

    &#64;Id
    &#64;GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    &#64;Column(nullable = false, length = 50)
    private String name;

    &#64;Column(nullable = false, unique = true, length = 100)
    private String email;

    // 연관관계의 주인 (외래 키를 관리)
    // fetch = FetchType.LAZY: 지연 로딩 (기본값은 EAGER)
    &#64;ManyToOne(fetch = FetchType.LAZY)
    &#64;JoinColumn(name = "team_id") // 외래 키 컬럼명 지정
    private Team team;

    protected Member() {}

    public Member(String name, String email) {
        this.name = name;
        this.email = email;
    }

    // Getter
    public Long getId() { return id; }
    public String getName() { return name; }
    public String getEmail() { return email; }
    public Team getTeam() { return team; }

    // Setter (연관관계 편의 메소드에서 사용)
    public void setTeam(Team team) {
        this.team = team;
    }
}

// MemberRepository.java
package com.kwonputer.repository;

import com.kwonputer.domain.Member;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface MemberRepository extends JpaRepository<Member, Long> {
    // Spring Data JPA가 자동으로 쿼리 메소드를 생성
    Member findByEmail(String email);
    List<Member> findByNameContaining(String name);
    List<Member> findByTeamName(String teamName); // Team 엔티티의 name 필드를 통해 조회
}

// TeamRepository.java
package com.kwonputer.repository;

import com.kwonputer.domain.Team;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface TeamRepository extends JpaRepository<Team, Long> {
    Team findByName(String name);
}

핵심 내용

쿼리 메소드와 JPQL: 데이터 조회 정복하기

데이터를 조회하는 것은 백엔드 애플리케이션의 핵심 기능 중 하나입니다. Spring Data JPA는 이 조회 기능을 매우 편리하게 사용할 수 있도록 두 가지 강력한 방법을 제공합니다. 바로 ‘쿼리 메소드’와 ‘JPQL’입니다.

1. 쿼리 메소드: 직관적인 메소드 이름으로 쿼리 생성

쿼리 메소드는 Spring Data JPA의 가장 큰 장점 중 하나로, 메소드 이름만으로도 SQL 쿼리를 자동으로 생성해줍니다. 정해진 규칙에 따라 메소드 이름을 작성하면, Spring Data JPA가 이를 파싱하여 적절한 JPQL(Java Persistence Query Language)을 생성하고 실행합니다. 이는 반복적인 쿼리 작성을 줄여 개발 생산성을 크게 높여줍니다.

주요 규칙:

☑ findBy[컬럼명]: 특정 컬럼으로 조회 (예: findByEmail(String email))

☑ findBy[컬럼명]And[다른컬럼명]: 여러 컬럼을 AND 조건으로 조회 (예: findByNameAndEmail(String name, String email))

☑ Containing, StartingWith, EndingWith: Like 연산자 (예: findByNameContaining(String keyword))

☑ OrderBy[컬럼명]Asc/Desc: 정렬 (예: findAllByOrderByNameDesc())

☑ 연관관계 필드 조회: findByTeamName(String teamName)처럼 연관된 엔티티의 필드로도 조회가 가능합니다.

2. @Query 어노테이션과 JPQL: 복잡한 쿼리에 대한 유연성

쿼리 메소드만으로는 모든 복잡한 조회 조건을 처리하기 어렵습니다. 이럴 때 @Query 어노테이션과 JPQL(Java Persistence Query Language)을 활용할 수 있습니다. JPQL은 SQL과 유사하지만, 데이터베이스 테이블이 아닌 ‘엔티티 객체’를 대상으로 쿼리한다는 점에서 차이가 있습니다. 이를 통해 객체지향적인 방식으로 쿼리를 작성할 수 있습니다.

// MemberRepository.java (추가)
package com.kwonputer.repository;

import com.kwonputer.domain.Member;
import com.kwonputer.dto.MemberInfoDto;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;

import java.util.List;
import java.util.Optional;

@Repository
public interface MemberRepository extends JpaRepository<Member, Long> {
    // 1. 쿼리 메소드 예시
    Optional<Member> findByEmail(String email);
    List<Member> findByNameStartingWith(String prefix);
    List<Member> findByTeamNameAndNameContaining(String teamName, String memberName);

    // 2. @Query 어노테이션과 JPQL 예시
    // :name, :email과 같이 파라미터를 명시적으로 바인딩
    @Query("SELECT m FROM Member m WHERE m.name = :name AND m.email = :email")
    List<Member> findMembersByNameAndEmail(@Param("name") String name, @Param("email") String email);

    // 네이티브 SQL 쿼리 사용 예시 (nativeQuery = true)
    @Query(value = "SELECT * FROM members WHERE team_id = :teamId", nativeQuery = true)
    List<Member> findMembersByTeamIdNative(@Param("teamId") Long teamId);

    // 3. DTO Projection: 인터페이스 기반
    // 인터페이스에 getter 메소드를 정의하여 필요한 필드만 조회
    @Query("SELECT m.name as memberName, m.email as memberEmail, t.name as teamName FROM Member m JOIN m.team t WHERE t.id = :teamId")
    List<MemberInfoProjection> findMemberInfoByTeamId(@Param("teamId") Long teamId);

    // 4. DTO Projection: 클래스 기반 (생성자 사용)
    @Query("SELECT new com.kwonputer.dto.MemberInfoDto(m.name, m.email, t.name) FROM Member m JOIN m.team t WHERE t.id = :teamId")
    List<MemberInfoDto> findMemberInfoDtoByTeamId(@Param("teamId") Long teamId);
}

// MemberInfoProjection.java (인터페이스 기반 DTO Projection)
package com.kwonputer.dto;

public interface MemberInfoProjection {
    String getMemberName();
    String getMemberEmail();
    String getTeamName();
}

// MemberInfoDto.java (클래스 기반 DTO Projection)
package com.kwonputer.dto;

public class MemberInfoDto {
    private String memberName;
    private String memberEmail;
    private String teamName;

    public MemberInfoDto(String memberName, String memberEmail, String teamName) {
        this.memberName = memberName;
        this.memberEmail = memberEmail;
        this.teamName = teamName;
    }

    // Getter
    public String getMemberName() { return memberName; }
    public String getMemberEmail() { return memberEmail; }
    public String getTeamName() { return teamName; }

    // Setter (필요시 추가)
    public void setMemberName(String memberName) { this.memberName = memberName; }
    public void setMemberEmail(String memberEmail) { this.memberEmail = memberEmail; }
    public void setTeamName(String teamName) { this.teamName = teamName; }
}

3. Projection: 필요한 데이터만 조회하기

엔티티 전체를 조회하는 것은 때때로 불필요한 데이터를 로딩하여 성능 저하를 야기할 수 있습니다. Projection은 필요한 특정 필드만 선택적으로 조회하는 기능입니다. 위 코드 예시처럼 인터페이스나 DTO 클래스를 활용하여 Projection을 구현할 수 있습니다. 이는 특히 대량의 데이터를 조회할 때 네트워크 전송량과 메모리 사용량을 줄여주는 효과적인 방법입니다.

인터페이스 기반 Projection은 런타임에 동적으로 구현체를 생성하여 데이터를 매핑합니다. 클래스 기반 Projection은 생성자를 통해 데이터를 주입받는 방식으로 동작하며, JPQL의 NEW 키워드를 사용하여 직접 DTO 객체를 생성합니다. 어떤 방식을 사용하든, 목적은 동일합니다: 불필요한 데이터 로딩을 최소화하고 애플리케이션의 효율성을 높이는 것입니다.

문제 해결

성능 저하의 주범 N+1 문제, 완벽 해결 전략

Spring Data JPA를 사용하면서 가장 흔하게 마주치고, 동시에 가장 큰 성능 문제를 일으키는 것이 바로 ‘N+1 문제’입니다. 이름만 들어도 벌써 머리가 아파오는 분들도 계실 텐데요, 권퓨터가 쉽게 설명하고 완벽한 해결 전략을 제시해 드릴게요!

1. N+1 문제란 무엇인가?

N+1 문제는 주로 ‘지연 로딩(Lazy Loading)’을 사용하는 연관관계에서 발생합니다. 예를 들어, 우리가 10개의 팀(Team)을 조회하면서 각 팀에 속한 회원(Member) 정보도 함께 조회하고 싶다고 가정해 봅시다. JPA는 기본적으로 @OneToMany 관계를 지연 로딩으로 설정합니다. 즉, 팀을 조회할 때는 회원 정보를 즉시 가져오지 않고, 실제로 회원 정보에 접근할 때(예: team.getMembers() 호출 시) 그때서야 추가 쿼리를 날려 가져옵니다.

여기서 문제가 발생합니다. 10개의 팀을 조회하는 데 1번의 쿼리(N=10에서 1)가 실행되고, 각 팀의 회원을 조회하기 위해 다시 10번의 쿼리가 추가로 실행됩니다. 총 1(팀 조회) + N(각 팀의 회원 조회) = 1 + 10 = 11번의 쿼리가 나가는 것이죠. 만약 팀의 개수가 100개라면 101번의 쿼리가 발생하게 되고, 이는 심각한 성능 저하로 이어집니다. 이것이 바로 N+1 문제입니다.

2. N+1 문제 해결 전략

다행히 N+1 문제를 해결할 수 있는 다양한 방법들이 있습니다. 상황에 따라 적절한 방법을 선택하는 것이 중요합니다.

가장 일반적으로는 Fetch Join이나 @EntityGraph를 사용하여 N+1 문제를 해결합니다. 대량의 데이터를 DTO로 바로 조회할 필요가 있다면 DTO Projection이 효과적입니다. 프로젝트의 특성과 요구사항에 맞춰 최적의 전략을 선택하는 것이 중요합니다.

// MemberRepository.java (N+1 해결 쿼리 추가)
package com.kwonputer.repository;

import com.kwonputer.domain.Member;
import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.stereotype.Repository;

import java.util.List;

@Repository
public interface MemberRepository extends JpaRepository<Member, Long> {

    // N+1 문제 발생 예시 (Team을 조회 후 각 Team의 Member에 접근 시 N번의 쿼리 발생)
    // List<Team> findAll();

    // 1. Fetch Join을 이용한 N+1 문제 해결 (Team과 Member를 한 번에 조회)
    // DISTINCT 키워드를 사용하여 중복된 Team 엔티티를 제거
    @Query("SELECT DISTINCT t FROM Team t JOIN FETCH t.members")
    List<Team> findAllTeamsWithMembersFetchJoin();

    // 2. @EntityGraph를 이용한 N+1 문제 해결
    // attributePaths = "members": Team을 조회할 때 members 컬렉션도 함께 Fetch 함
    @EntityGraph(attributePaths = "members")
    @Query("SELECT t FROM Team t") // JPQL 쿼리는 간단하게 작성
    List<Team> findAllTeamsWithMembersEntityGraph();

    // 특정 팀 이름으로 팀과 멤버를 함께 조회 (Fetch Join)
    @Query("SELECT DISTINCT t FROM Team t JOIN FETCH t.members WHERE t.name = :teamName")
    List<Team> findTeamsWithMembersByTeamNameFetchJoin(String teamName);
}

위 예시에서 findAllTeamsWithMembersFetchJoin() 메소드는 FETCH JOIN을 사용하여 팀과 회원 정보를 단 한 번의 쿼리로 가져옵니다. findAllTeamsWithMembersEntityGraph()는 @EntityGraph를 사용하여 동일한 효과를 냅니다. 이 두 가지 방법은 N+1 문제 해결에 있어 가장 강력한 도구이며, 실제 프로젝트에서 적극적으로 활용해야 합니다.

실전 적용

복잡한 쿼리 처리와 고급 기능 활용

Spring Data JPA는 단순 CRUD를 넘어 복잡한 비즈니스 요구사항을 충족시키기 위한 다양한 고급 기능을 제공합니다. 동적 쿼리 처리부터 데이터의 생성/수정 시간 자동화, 그리고 논리적 삭제까지, 실제 프로젝트에서 유용하게 활용할 수 있는 기능들을 알아볼까요?

1. Querydsl: 타입 세이프한 동적 쿼리

JPQL은 문자열 기반이기 때문에 컴파일 시점에 오류를 잡아내기 어렵고, 복잡한 동적 쿼리를 작성하기 번거롭다는 단점이 있습니다. Querydsl은 이러한 문제를 해결하기 위해 등장한 프레임워크입니다. Querydsl은 자바 코드로 쿼리를 작성할 수 있게 해주며, 정적 타입을 지원하여 컴파일 시점에 오류를 감지할 수 있게 합니다. 이는 런타임 오류를 줄이고 개발 생산성을 크게 향상시킵니다.

Querydsl을 사용하려면 엔티티를 기반으로 Q-Class(QMember, QTeam 등)를 생성해야 합니다. 이 Q-Class를 통해 타입 안전하게 엔티티 필드를 참조하여 쿼리를 구성할 수 있습니다. 예를 들어, 특정 조건에 따라 WHERE 절이 동적으로 추가되거나, 정렬 기준이 달라지는 쿼리 등을 매우 유연하게 작성할 수 있습니다.

2. Auditing: 생성/수정 시간 자동화

대부분의 엔티티는 언제 생성되었고, 누가 언제 마지막으로 수정했는지와 같은 감사(Auditing) 정보가 필요합니다. Spring Data JPA는 이 정보를 자동으로 관리해주는 강력한 기능을 제공합니다. @EnableJpaAuditing 어노테이션을 활성화하고 엔티티에 @CreatedDate, @LastModifiedDate, @CreatedBy, @LastModifiedBy 어노테이션을 붙이면 됩니다.

이 기능은 보통 @MappedSuperclass를 사용하여 모든 엔티티가 상속받는 베이스 엔티티에 구현함으로써 중복 코드를 제거하고 일관성을 유지합니다.

// BaseEntity.java
package com.kwonputer.domain;

import jakarta.persistence.Column;
import jakarta.persistence.EntityListeners;
import jakarta.persistence.MappedSuperclass;
import org.springframework.data.annotation.CreatedBy;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedBy;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;

import java.time.LocalDateTime;

@MappedSuperclass // 엔티티가 아니며, 자식 엔티티에게 매핑 정보만 제공
@EntityListeners(AuditingEntityListener.class) // JPA Auditing 기능 활성화
public abstract class BaseEntity {

    @CreatedDate
    @Column(updatable = false) // 생성 시간은 업데이트되지 않음
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime lastModifiedAt;

    @CreatedBy
    @Column(updatable = false)
    private String createdBy;

    @LastModifiedBy
    private String lastModifiedBy;

    // Getter
    public LocalDateTime getCreatedAt() { return createdAt; }
    public LocalDateTime getLastModifiedAt() { return lastModifiedAt; }
    public String getCreatedBy() { return createdBy; }
    public String getLastModifiedBy() { return lastModifiedBy; }
}

// Member.java (BaseEntity 상속 예시)
package com.kwonputer.domain;

import jakarta.persistence.*;

@Entity
@Table(name = "members")
public class Member extends BaseEntity { // BaseEntity 상속
    // ... 기존 필드 ...
}

실제 사용 시 @CreatedBy, @LastModifiedBy 필드에 값을 주입하려면 AuditorAware 인터페이스를 구현하여 현재 인증된 사용자 정보를 제공해야 합니다.

3. Soft Delete (논리적 삭제) 구현

데이터를 실제로 데이터베이스에서 삭제하는 대신, ‘삭제 여부’를 나타내는 플래그(예: deleted = true)를 설정하여 논리적으로 삭제 처리하는 방식을 Soft Delete라고 합니다. 이는 데이터 복구 용이성, 감사 로그 유지, 데이터 무결성 유지 등의 장점이 있습니다. Spring Data JPA에서는 @Where 어노테이션을 사용하여 Soft Delete를 쉽게 구현할 수 있습니다.

// Member.java (Soft Delete 적용 예시)
package com.kwonputer.domain;

import jakarta.persistence.*;
import org.hibernate.annotations.Where;

@Entity
@Table(name = "members")
@Where(clause = "deleted = false") // deleted=false인 엔티티만 조회
public class Member extends BaseEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

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

    @Column(nullable = false, unique = true, length = 100)
    private String email;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "team_id")
    private Team team;

    private boolean deleted = false; // 삭제 여부 플래그

    protected Member() {}

    public Member(String name, String email) {
        this.name = name;
        this.email = email;
    }

    // Getter
    public Long getId() { return id; }
    public String getName() { return name; }
    public String getEmail() { return email; }
    public Team getTeam() { return team; }
    public boolean isDeleted() { return deleted; }

    // Setter (연관관계 편의 메소드에서 사용)
    public void setTeam(Team team) {
        this.team = team;
    }

    // 논리적 삭제 메소드
    public void delete() {
        this.deleted = true;
    }
    // 논리적 복구 메소드
    public void restore() {
        this.deleted = false;
    }
}

@Where(clause = "deleted = false")를 엔티티에 적용하면, 해당 엔티티를 조회하는 모든 JPQL 쿼리에 자동으로 WHERE deleted = false 조건이 추가됩니다. 실제 삭제는 member.delete() 메소드를 호출하여 deleted 필드를 true로 변경하는 방식으로 이루어집니다.