Spring Data JPA

데이터베이스에 데이터를 저장하고 조회하는 일은 모든 웹 애플리케이션의 핵심이다. JPA는 자바 객체와 관계형 데이터베이스 테이블을 매핑해 주는 표준 기술이고, Spring Data JPA는 그 JPA를 더 적은 코드로 쓰게 해 주는 스프링 모듈이다. 인터페이스만 선언하면 기본 CRUD 코드가 자동으로 만들어진다.

#1. JPA와 Spring Data JPA

• JPA (Java Persistence API): 자바 객체(엔티티)와 DB 테이블의 매핑을 정의하는 표준 명세다. SQL을 직접 쓰는 대신 객체를 다루면, JPA가 적절한 SQL을 생성·실행한다.

• Hibernate: JPA 명세의 대표적인 구현체다. 스프링 부트의 spring-boot-starter-data-jpa는 기본으로 Hibernate를 사용한다.

• Spring Data JPA: JPA를 한 단계 더 추상화한 스프링 모듈이다. JpaRepository를 상속한 인터페이스만 선언하면 구현 클래스가 자동 생성된다.

graph LR
    A[내 코드<br/>Repository 인터페이스] --> B[Spring Data JPA]
    B --> C[JPA 표준]
    C --> D[Hibernate 구현체]
    D --> E[(데이터베이스)]

#2. 엔티티 매핑

테이블과 매핑되는 클래스를 엔티티(Entity) 라고 한다.

import jakarta.persistence.*;

@Entity                              // JPA가 관리하는 엔티티
@Getter @Setter
@NoArgsConstructor                   // JPA는 기본 생성자가 필수
public class Member {

    @Id                              // 기본 키(PK)
    @GeneratedValue(strategy = GenerationType.IDENTITY)  // DB가 자동 증가
    private Long id;

    @Column(nullable = false, length = 20)   // 컬럼 제약조건
    private String name;

    private int age;

    @Enumerated(EnumType.STRING)     // enum을 문자열로 저장
    private Role role;
}

#3. 리포지토리 (Repository)

JpaRepository<엔티티, 기본키타입>를 상속한 인터페이스를 만들면, 기본 CRUD 메소드가 자동으로 제공된다.

public interface MemberRepository extends JpaRepository<Member, Long> {
}

이것만으로 다음 메소드를 바로 쓸 수 있다.

@Service
@RequiredArgsConstructor
@Transactional                       // 쓰기 작업은 트랜잭션 안에서
public class MemberService {

    private final MemberRepository memberRepository;

    public Long join(Member member) {
        return memberRepository.save(member).getId();
    }

    @Transactional(readOnly = true)  // 조회는 readOnly로 성능 최적화
    public Member findOne(Long id) {
        return memberRepository.findById(id)
                .orElseThrow(() -> new IllegalArgumentException("회원이 없습니다. id=" + id));
    }
}

#4. 쿼리 메소드

메소드 이름만 규칙에 맞게 지으면 Spring Data JPA가 SQL을 자동 생성한다.

public interface MemberRepository extends JpaRepository<Member, Long> {

    // SELECT * FROM member WHERE name = ?
    List<Member> findByName(String name);

    // WHERE name = ? AND age > ?
    List<Member> findByNameAndAgeGreaterThan(String name, int age);

    // WHERE name LIKE ?
    List<Member> findByNameContaining(String keyword);

    // ORDER BY age DESC
    List<Member> findByNameOrderByAgeDesc(String name);

    // 단건 + null 안전
    Optional<Member> findByEmail(String email);

    // 개수
    long countByAge(int age);
}

자주 쓰는 키워드:

#5. @Query — JPQL 직접 작성

복잡한 쿼리는 @Query로 직접 작성한다. JPQL은 테이블이 아니라 엔티티를 대상으로 하는 객체 지향 쿼리다.

public interface MemberRepository extends JpaRepository<Member, Long> {

    @Query("select m from Member m where m.name = :name and m.age > :age")
    List<Member> search(@Param("name") String name, @Param("age") int age);

    // 특정 값만 조회 (DTO 프로젝션)
    @Query("select new com.example.dto.MemberDto(m.id, m.name) from Member m")
    List<MemberDto> findMemberDto();

    // 네이티브 SQL이 필요하면 nativeQuery 사용
    @Query(value = "select * from member where name = :name", nativeQuery = true)
    List<Member> findByNameNative(@Param("name") String name);
}

#6. 페이징과 정렬

원본 노션의 "페이징 처리" 주제를 JPA 방식으로 풀어낸 부분이다. Pageable을 파라미터로 받으면 페이징·정렬이 자동으로 처리되고, Page 객체로 전체 개수·페이지 수까지 함께 받는다.

public interface MemberRepository extends JpaRepository<Member, Long> {

    Page<Member> findByNameContaining(String keyword, Pageable pageable);
}

@Service
@RequiredArgsConstructor
public class MemberService {

    private final MemberRepository memberRepository;

    public Page<Member> getPage(String keyword, int page) {
        // page: 0부터 시작, size: 10개씩, 정렬: id 내림차순
        Pageable pageable = PageRequest.of(page, 10, Sort.by(Sort.Direction.DESC, "id"));
        return memberRepository.findByNameContaining(keyword, pageable);
    }
}

Page 객체가 제공하는 정보:

#컨트롤러에서 받기

스프링 MVC는 요청 파라미터(?page=0&size=10&sort=id,desc)를 Pageable로 자동 바인딩한다.

@GetMapping("/members")
public String list(@RequestParam(defaultValue = "") String keyword,
                   @PageableDefault(size = 10, sort = "id", direction = Sort.Direction.DESC) Pageable pageable,
                   Model model) {
    Page<Member> members = memberRepository.findByNameContaining(keyword, pageable);
    model.addAttribute("members", members);
    return "members/list";
}

#타임리프에서 페이지 네비게이션

<tr th:each="member : ${members.content}">
    <td th:text="${member.name}"></td>
</tr>

<nav>
    <a th:if="${members.hasPrevious()}"
       th:href="@{/members(page=${members.number - 1})}">이전</a>
    <span th:text="${members.number + 1} + ' / ' + ${members.totalPages}"></span>
    <a th:if="${members.hasNext()}"
       th:href="@{/members(page=${members.number + 1})}">다음</a>
</nav>

#페이지 블록 — 1~10, 11~20 묶음

페이지가 많아지면 [이전] 1 2 … 100 [다음]을 다 그릴 수 없다. 보통 [이전] 11 12 … 20 [다음]처럼 10개씩 블록으로 보여 준다. 현재 페이지로 블록의 시작·끝을 계산한다.

int size = 10;                                  // 블록당 페이지 수
int current = members.getNumber();              // 현재 페이지(0부터)
int start = (current / size) * size;            // 블록 시작 (0,10,20…)
int end = Math.min(start + size, members.getTotalPages());  // 블록 끝
model.addAttribute("startPage", start);
model.addAttribute("endPage", end);

<a th:if="${members.hasPrevious()}"
   th:href="@{/members(page=${startPage - 1})}">이전</a>

<!-- startPage ~ endPage-1 까지 번호 출력 -->
<span th:each="i : ${#numbers.sequence(startPage, endPage - 1)}">
    <a th:href="@{/members(page=${i})}"
       th:text="${i + 1}"
       th:classappend="${i == members.number} ? 'active'"></a>
</span>

<a th:if="${members.hasNext()}"
   th:href="@{/members(page=${endPage})}">다음</a>

Slice<Member> findByNameContaining(String keyword, Pageable pageable);
// slice.hasNext() 는 되지만, slice.getTotalPages() 는 없음

#7. 연관관계 매핑 { #7 }

엔티티 간의 관계(회원 ↔ 주문 등)를 매핑한다. 한 명의 회원이 여러 주문을 갖는 1:N 관계 예시다. 방향·다중성·연관관계의 주인 같은 개념은 JPA 기초 — 연관관계의 이해에서 먼저 정리했으니, 여기서는 어노테이션으로 실제 매핑하는 코드에 집중한다.

@Entity
@Table(name = "orders")                  // MySQL에서 order는 예약어이므로 테이블명 지정
public class Order {

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

    @ManyToOne(fetch = FetchType.LAZY)   // 주문 N : 회원 1
    @JoinColumn(name = "member_id")      // FK 컬럼
    private Member member;
}

@Entity
public class Member {

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

    @OneToMany(mappedBy = "member")      // Order.member 가 연관관계의 주인
    private List<Order> orders = new ArrayList<>();
}

#N+1 문제 해결하기

LAZY 연관을 목록 순회에서 접근하면, 목록 조회 1번에 더해 항목마다 연관 조회가 N번 나가는 N+1 문제가 생긴다. (개념과 발생 원리는 JPA 기초 — N+1 문제에서 다뤘다.) Spring Data JPA에서는 세 가지로 해결한다.

① @Query + join fetch — 연관 엔티티를 한 번의 조인 쿼리로 함께 조회한다.

@Query("select o from Order o join fetch o.member")
List<Order> findAllWithMember();

② @EntityGraph — JPQL을 직접 쓰지 않고 어노테이션만으로 fetch join 효과를 낸다. 쿼리 메소드에도 붙일 수 있다.

@EntityGraph(attributePaths = "member")
List<Order> findAll();

③ 배치 사이즈 — application.yml에 한 줄 켜 두면, N번의 단건 조회를 IN 쿼리로 묶어 1+1번으로 줄인다. 컬렉션(@OneToMany) 조회에 특히 유용하다.

spring:
  jpa:
    properties:
      hibernate:
        default_batch_fetch_size: 100

#8. 동작 확인 — SQL 로그

프로젝트 설정에서 켜 둔 show-sql/format_sql 덕분에 JPA가 생성하는 SQL을 콘솔에서 확인할 수 있다.

Hibernate: select m1_0.id, m1_0.age, m1_0.name, m1_0.role from member m1_0 where m1_0.name=? binding parameter [1] as [VARCHAR] - [kim]

#9. 트랜잭션과 변경 감지(Dirty Checking) { #9 }

JPA에서 처음 놀라는 지점이 "수정할 때 save()를 부르지 않아도 된다" 는 것이다. 트랜잭션 안에서 조회한 엔티티의 값을 바꾸면, 트랜잭션이 커밋될 때 JPA가 변경을 감지해 자동으로 UPDATE SQL을 실행한다. 이를 변경 감지(dirty checking) 라고 한다.

@Service
@RequiredArgsConstructor
public class MemberService {

    private final MemberRepository memberRepository;

    @Transactional                       // 메소드 전체가 하나의 트랜잭션
    public void changeName(Long id, String newName) {
        Member member = memberRepository.findById(id).orElseThrow();
        member.setName(newName);          // 값만 바꾼다
        // memberRepository.save(member);  // ← 호출하지 않아도 된다!
    }                                     // 커밋 시점에 JPA가 UPDATE 자동 실행
}

원리는 이렇다. 영속성 컨텍스트(Persistence Context)는 조회한 엔티티의 최초 상태(스냅샷) 를 보관한다. 커밋(또는 flush) 시점에 현재 값과 스냅샷을 비교해, 달라진 필드가 있으면 UPDATE를 생성한다.

#@Transactional 의 주요 옵션

#10. 엔티티와 DTO 분리 { #10-dto }

Spring MVC — 요청과 응답의 @ResponseBody 예제에서는 Member 엔티티를 그대로 JSON으로 반환했다. 학습 단계에서는 간단하지만, 엔티티를 그대로 외부에 노출하면 여러 문제가 생긴다.

• 민감 정보 노출: password 같은 필드까지 JSON에 그대로 나간다.

• 양방향 연관관계 순환참조: Member → orders → member → orders ... 가 무한히 직렬화되어 오류가 난다.

• LAZY 직렬화 오류: 지연 로딩 연관 필드를 트랜잭션 밖에서 직렬화하려다 예외가 발생한다.

• API 스펙이 엔티티에 묶임: 엔티티 필드를 바꾸면 API 응답 모양이 의도치 않게 함께 바뀐다.

그래서 화면·API로 내보낼 데이터는 DTO(Data Transfer Object) 라는 별도 클래스에 필요한 값만 담아 변환한다.

// 응답 전용 DTO — 필요한 필드만, 안전하게
public record MemberDto(Long id, String name, int age) {
    public MemberDto(Member member) {
        this(member.getId(), member.getName(), member.getAge());
    }
}

@GetMapping("/api/members")
@ResponseBody
public List<MemberDto> apiList() {
    return memberRepository.findAll().stream()
            .map(MemberDto::new)        // 엔티티 → DTO 변환
            .toList();
}