초안을 발행용 본문으로 다시 정리하고 있습니다. 현재 기준 버전과 오래된 javax.persistence 설명의 차이를 확인한 뒤, save -> isNew -> persist/merge 흐름이 초반에 바로 보이도록 구조를 다듬겠습니다.버전 차이까지 반영해 본문을 마무리 중입니다. 오래된 문서의 ID만 본다 설명과 현재 공식 문서의 @Version 우선 규칙을 분리해 적고, 직접 ID 할당 시 Persistable을 왜 써야 하는지도 로그 예시와 함께 정리하겠습니다.# Spring Data JPA는 새 엔티티를 어떻게 구분할까: save, persist, merge까지 한 번에 이해하기
빠른 답
- Spring Data JPA의
save()는 먼저isNew()로 새 엔티티인지 판단한 뒤persist()와merge()를 나눕니다. - 현재 기본 규칙은 non-primitive
@Version을 먼저 보고, 그런 필드가 없으면@Id를 봅니다. - 직접 ID를 넣는 엔티티는 기본 규칙만으로는 신규로 판정되지 않아
merge()와 불필요한 조회가 생기기 쉽습니다. - 이런 경우
Persistable로isNew()기준을 명시하면 동작과 성능을 더 예측 가능하게 만들 수 있습니다.
Repository.save()는 단순히 "저장"만 하는 메서드가 아닙니다. 같은 save()를 호출해도 어떤 엔티티는 곧바로 insert가 나가고, 어떤 엔티티는 먼저 select를 한 번 더 수행합니다. 이 차이는 대부분 저장 직전의 새 엔티티 판별 규칙에서 시작됩니다.
목차
흐름으로 보기
핵심은 이 다섯 단계입니다. save()가 호출되면 Spring Data JPA는 먼저 "이 객체가 아직 저장되지 않은 새 엔티티인가?"를 확인하고, 그 결과에 따라 EntityManager.persist() 또는 EntityManager.merge()를 호출합니다. 그래서 같은 리포지토리 메서드라도 엔티티 설계에 따라 SQL 흐름이 달라집니다.
왜 새 엔티티 판별이 중요한가
Spring Data JPA의 기본 구현인 SimpleJpaRepository를 보면 분기점이 아주 명확합니다.
@Override
@Transactional
public <S extends T> S save(S entity) {
if (entityInformation.isNew(entity)) {
entityManager.persist(entity);
return entity;
}
return entityManager.merge(entity);
}
이 한 줄 차이가 동작 방식과 성능을 모두 바꿉니다.
persist()는 새 엔티티를 영속성 컨텍스트에 편입시키는 경로입니다. 보통 신규 저장이라면 이 흐름이 가장 자연스럽습니다. 반면 merge()는 "이미 식별자를 가진 객체"를 기준으로 동작하는 경향이 강해서, Hibernate가 기존 row 존재 여부를 확인하려고 먼저 조회를 수행하는 경우가 많습니다.
여기서 자주 놓치는 점이 하나 더 있습니다. merge()는 전달한 객체 자체를 관리 상태로 만드는 것이 아니라, 그 상태를 복사한 관리 객체를 반환합니다. 그래서 save()가 merge() 경로를 탔다면 반환값을 무심코 버리는 코드가 이후 버그의 원인이 될 수 있습니다.
isNew는 무엇을 기준으로 판단할까
현재 공식 문서 기준으로 Spring Data JPA의 기본 전략은 다음 순서입니다.
- non-primitive 타입의
@Version필드가 있으면 그 값을 먼저 봅니다. - 그 값이
null이면 새 엔티티로 판단합니다. - 그런
@Version필드가 없으면@Id를 봅니다. - ID가
null이면 새 엔티티로 판단합니다.
여기서 중요한 예외가 있습니다. primitive 타입의 버전 필드, 예를 들어 long version은 새 엔티티 판별 기준으로 쓸 수 없습니다. JPA에서는 0이 첫 저장 버전으로 사용될 수 있기 때문입니다. 그래서 @Version long version은 "아직 저장되지 않았음"을 표현하는 신호가 되지 못하고, 이 경우 Spring Data JPA는 결국 ID 기준으로 돌아갑니다.
구현체 관점에서도 흐름은 비슷합니다. 일반 엔티티는 보통 JpaMetamodelEntityInformation이 판별을 담당하고, 엔티티가 Persistable을 구현하면 JpaPersistableEntityInformation이 entity.isNew()로 판별을 위임합니다. EntityInformation 자체를 커스터마이징하는 방법도 있지만, 실무에서는 드문 편입니다.
또 하나 덧붙이면, 내부 추상 구현까지 내려가면 primitive 숫자 ID는 0을 신규 신호로 해석하는 경로도 있습니다. 다만 최근 JPA 엔티티는 long보다 Long 같은 wrapper 타입 ID를 더 많이 쓰므로, 실무에서는 null 여부가 더 자주 기준이 됩니다.
@Version과 @Id는 어떻게 다르게 작동할까
헷갈리는 지점은 보통 여기입니다. "ID가 있으면 기존 엔티티 아닌가?"라고 생각하기 쉽지만, 현재 Spring Data JPA는 @Version을 더 먼저 볼 수 있습니다.
@Entity
class Member {
@Id
@GeneratedValue
private Long id;
@Version
private Long version;
private String name;
}
@Entity
class Coupon {
@Id
private String code;
@Version
private Long version;
private String description;
}
@Entity
class LegacyOrder {
@Id
private String orderNo;
@Version
private long version;
private String status;
}
Member는 가장 일반적인 형태입니다. 새 객체를 만들면 id == null, version == null이므로 자연스럽게 새 엔티티로 판단되고 persist()가 호출됩니다.
Coupon은 직접 ID를 넣는 구조이지만, version이 Long이고 아직 null이라면 여전히 새 엔티티로 판별될 수 있습니다. 즉 "직접 ID 할당 = 무조건 merge"는 정확한 설명이 아닙니다. wrapper 타입 @Version이 있으면 기본 규칙만으로도 신규 판별이 가능합니다.
문제는 LegacyOrder 같은 케이스입니다. version이 primitive long라서 null 판별을 할 수 없고, orderNo도 애플리케이션에서 이미 채워 넣었다면 기본 로직은 이 객체를 기존 엔티티처럼 해석하기 쉽습니다. 그러면 실제로는 새 객체인데도 merge()가 선택되고, 불필요한 조회가 먼저 나갈 수 있습니다.
직접 ID 할당 시 Persistable을 어떻게 적용할까
직접 ID를 넣는 엔티티에서 @Version만으로 신규 판별이 어렵다면, 가장 명확한 방법은 Persistable을 구현해 isNew() 기준을 엔티티가 직접 갖도록 만드는 것입니다.
공식 문서에서도 공통 베이스 클래스와 JPA 생명주기 콜백을 함께 쓰는 패턴을 제시합니다. 현재 스택 기준 예제는 jakarta.persistence.*를 사용하는 쪽이 맞습니다.
import jakarta.persistence.MappedSuperclass;
import jakarta.persistence.PostLoad;
import jakarta.persistence.PostPersist;
import jakarta.persistence.Transient;
import org.springframework.data.domain.Persistable;
@MappedSuperclass
public abstract class BaseEntity<ID> implements Persistable<ID> {
@Transient
private boolean newEntity = true;
@Override
public boolean isNew() {
return newEntity;
}
@PostPersist
@PostLoad
void markNotNew() {
this.newEntity = false;
}
}
@Entity
class PurchaseOrder extends BaseEntity<String> {
@Id
private String orderId;
private String title;
@Override
public String getId() {
return orderId;
}
}
이 방식의 장점은 신규 상태를 ID 존재 여부에만 의존하지 않는다는 점입니다. 직접 ID를 넣는 구조에서는 "ID가 있다"와 "이미 저장됐다"가 같은 뜻이 아니기 때문입니다.
다만 몇 가지 주의할 점이 있습니다.
@PostLoad가 빠지면 DB에서 읽어 온 엔티티도 계속 신규 상태로 남을 수 있습니다.isNew()를 무조건true로 두면 기존 데이터 저장 시 PK 충돌이 날 수 있습니다.- 프로퍼티 접근 전략을 쓰는 엔티티라면
getId()나isNew()가 영속 프로퍼티로 오해되지 않도록@Transient적용 여부를 함께 검토해야 합니다. - 생성 전략 ID를 쓰는 일반 엔티티라면 굳이
Persistable까지 도입할 필요는 없습니다.
save, persist, merge를 로그로 확인해보기
이 주제는 코드만 읽는 것보다 SQL 로그를 켜 보면 훨씬 빨리 이해됩니다. 현재 Hibernate 6 계열 기준으로는 아래 정도 설정이면 흐름을 확인하기 좋습니다.
spring:
jpa:
properties:
hibernate:
format_sql: true
logging:
level:
org.hibernate.SQL: DEBUG
org.hibernate.orm.jdbc.bind: TRACE
이 설정으로 save()를 실행하면 persist() 경로인지 merge() 경로인지 대체로 눈으로 구분할 수 있습니다. 새 엔티티로 확실히 판별되면 바로 insert가 보이고, 그렇지 않으면 select가 먼저 나오는 패턴이 자주 나타납니다.
# 1) Generated ID + wrapper @Version -> persist 경로
## 빠른 답
- Spring Data JPA는 save에서 항상 ID만 보지 않고 @Version 필드 유무와 타입도 함께 확인합니다.
- @Version이 wrapper 타입이면 null 여부로 새 엔티티를 판별하고, 없으면 보통 ID 값을 기준으로 판단합니다.
- 직접 ID를 할당하는 엔티티는 기본 판별 로직에서 신규로 보지 않을 수 있어 merge로 흘러가기 쉽습니다.
- 이 경우 Persistable을 사용해 isNew 기준을 명시해야 불필요한 조회와 혼란을 줄일 수 있습니다.
2026-04-05 14:10:11 DEBUG org.hibernate.SQL :
insert into member (name, version, id) values (?, ?, default)
2026-04-05 14:10:11 TRACE org.hibernate.orm.jdbc.bind :
binding parameter [1] as [VARCHAR] - [Kim]
2026-04-05 14:10:11 TRACE org.hibernate.orm.jdbc.bind :
binding parameter [2] as [BIGINT] - [0]
# 2) Manual ID + 기본 판별 실패 -> merge 경로
2026-04-05 14:10:12 DEBUG org.hibernate.SQL :
select po1_0.order_id, po1_0.title
from purchase_order po1_0
where po1_0.order_id=?
2026-04-05 14:10:12 TRACE org.hibernate.orm.jdbc.bind :
binding parameter [1] as [VARCHAR] - [PO-2026-0001]
2026-04-05 14:10:12 DEBUG org.hibernate.SQL :
insert into purchase_order (title, order_id) values (?, ?)
첫 번째 로그는 새 엔티티라는 신호가 명확해서 바로 insert로 들어갑니다. 두 번째 로그는 ID가 이미 채워져 있어 기존 row 존재 여부를 먼저 확인하려는 흐름이 보입니다. SQL 형태는 DB와 Dialect에 따라 달라질 수 있지만, save() 직후 select가 먼저 보인다면 merge() 경로를 의심해 볼 만합니다.
특히 배치 저장에서 이런 패턴이 섞이면 성능 차이가 바로 드러납니다. 애플리케이션 입장에서는 같은 save() 호출인데, 내부적으로는 조회 한 번이 더 붙기 때문입니다.
버전 차이와 마이그레이션 포인트
이 주제는 오래된 블로그 글과 현재 공식 문서가 다르게 말하는 대표적인 예입니다.
2026년 4월 기준으로 Spring Data JPA 현재 문서는 stable 라인으로 4.0.4와 3.5.10을 제공하고, Persisting Entities 문서는 기본 신규 판별 전략을 "@Version 우선, 없으면 @Id"로 설명합니다. 반면 오래된 Spring Data JPA 1.7 문서는 기본 전략을 사실상 ID inspection 중심으로 설명합니다.
그래서 예전 글에서 "Spring Data JPA는 ID만 본다"라고 배웠다면, 현재 기준으로는 설명이 반쯤만 맞습니다. 지금은 wrapper 타입의 @Version 필드가 있으면 그 값이 더 먼저 기준이 됩니다.
마이그레이션 관점에서도 차이가 있습니다.
- 현재 Spring Boot 3.x와 4.x 계열 예제는
javax.persistence가 아니라jakarta.persistence를 전제로 읽는 편이 맞습니다. 최신 Spring Boot System Requirements 문서도 현재 라인을 그 기준 위에서 설명합니다. - Hibernate 5 시절 글에서는 바인딩 로그를
org.hibernate.type.descriptor.sql.BasicBinder로 보는 예제가 많지만, Hibernate 6 계열에서는org.hibernate.orm.jdbc.bind설정이 더 잘 맞는 경우가 많습니다. 관련 범주는 Hibernate Logging guide를 함께 보는 편이 안전합니다. - 오래된 설명을 그대로 복사하면 "왜 로그가 안 나오지?", "왜 직접 ID인데도 신규 처리가 안 되지?" 같은 혼란이 생길 수 있습니다. 현재 스택에서는 import 패키지, Hibernate 메이저 버전, 그리고 Spring Data JPA 문서 버전을 같이 봐야 합니다.
실무에서 자주 놓치는 주의점
save()는insert전용 메서드가 아닙니다. 신규 판별이 먼저입니다.- 직접 ID를 넣는다고 해서 항상
merge()는 아니지만, wrapper 타입@Version이 없으면 그렇게 흘러가기 쉽습니다. @Version long version처럼 primitive 버전 필드는 신규 판별 기준으로 적합하지 않습니다.merge()는 전달 객체와 다른 관리 객체를 반환할 수 있으므로 반환값을 무시하면 이후 상태 동기화가 꼬일 수 있습니다.- 이미 영속성 컨텍스트에서 관리 중인 엔티티라면 수정 후 dirty checking에 맡기는 편이 더 자연스럽고, 매번
save()를 습관적으로 호출할 필요는 없습니다. - 대량 저장에서
select + insert패턴이 반복되면 먼저 엔티티 신규 판별 규칙부터 의심하는 편이 빠릅니다.
결국 기준은 단순합니다. 생성 전략 ID를 쓰는 평범한 엔티티라면 기본 규칙에 맡겨도 대체로 문제가 없습니다. 하지만 직접 ID를 할당하는 순간부터는 "새 엔티티의 기준을 누가 책임질 것인가"를 설계에 넣어야 합니다. 그 기준이 없으면 save()는 동작해도, 왜 merge()가 타는지 계속 헷갈리게 됩니다.
원문 참고
https://www.maeil-mail.kr/question/27
댓글
댓글 쓰기