llm-wiki/raw/official-docs/spring-data-jpa-auditing-official.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
official-doc / Spring Data JPA — Auditing (Annotation-based, AuditorAware SPI, @EnableJpaAuditing)	official-doc	https://docs.spring.io/spring-data/jpa/reference/auditing.html		feature-persistence-auditing-contract	ca-tmpl	official-doc ca-tmpl persistence spring-data auditing	2026-06-10

official-doc / Spring Data JPA — Auditing

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/ 에 source-summary-template 형식으로 별도 작성. 원본은 raw 에 영구 보관.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-persistence-auditing-contract	D1/D2: @CreatedDate / @LastModifiedDate / @CreatedBy / @LastModifiedBy 를 @MappedSuperclass 에 선언하고 @EntityListeners(AuditingEntityListener.class) 로 활성화. D5: AuditorAware<T> SPI 를 통해 현재 actor (created_by/updated_by) 를 security/runtime context 에서 주입.

출처 / Source

• 원본 URL: https://docs.spring.io/spring-data/jpa/reference/auditing.html
• 아카이브 URL: (미지정)
• 저자 / 조직: Spring Team / VMware (Broadcom)
• 발행일: 공식 레퍼런스 (버전 비의존, 문서 자체에 날짜 없음)
• 마지막 확인일: 2026-06-10

왜 저장했는지 / Why archived

Spring Data JPA 가 공식 제공하는 Auditing 메커니즘(네 가지 어노테이션 + AuditorAware SPI + @EnableJpaAuditing) 의 정확한 적용 조건과 활성화 절차를 branch feature-persistence-auditing-contract 의 D1/D2/D5 결정 근거로 보존. 특히 auditing 메타데이터가 root entity 가 아닌 embedded/MappedSuperclass 에 위치할 수 있다는 공식 확인이 핵심.

핵심 인용 / Key quotes (verbatim, self-grep verified)

[§Basics / Annotation-based Auditing Metadata] "We provide @CreatedBy and @LastModifiedBy to capture the user who created or modified the entity as well as @CreatedDate and @LastModifiedDate to capture when the change happened."

[§Basics / Annotation-based Auditing Metadata] "Auditing metadata does not necessarily need to live in the root level entity but can be added to an embedded one (depending on the actual store in use), as shown in the snippet below."

[§Basics / AuditorAware] "In case you use either @CreatedBy or @LastModifiedBy, the auditing infrastructure somehow needs to become aware of the current principal. To do so, we provide an AuditorAware<T> SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is. The generic type T defines what type the properties annotated with @CreatedBy or @LastModifiedBy have to be."

[§General Auditing Configuration] "You can also enable the AuditingEntityListener on a per-entity basis by using the @EntityListeners annotation, as follows:"

[§General Auditing Configuration] "As of Spring Data JPA 1.5, you can enable auditing by annotating a configuration class with the @EnableJpaAuditing annotation. You must still modify the orm.xml file and have spring-aspects.jar on the classpath. The following example shows how to use the @EnableJpaAuditing annotation:"

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
C1	Spring Data JPA 는 @CreatedBy, @LastModifiedBy, @CreatedDate, @LastModifiedDate 네 가지 어노테이션으로 auditing 메타데이터를 선언적으로 캡처한다	[§Annotation-based Auditing Metadata] "We provide @CreatedBy and @LastModifiedBy to capture the user who created or modified the entity as well as @CreatedDate and @LastModifiedDate to capture when the change happened."	official-vendor-doc	Spring Data JPA 를 사용하는 모든 JPA 엔티티	네 어노테이션이 동시에 모두 필요하다는 뜻이 아님 — 문서는 "selectively" 적용 가능하다고 명시
C2	Auditing 메타데이터는 root entity 에 놓지 않아도 되고 embedded 엔티티(또는 MappedSuperclass)에 추가할 수 있다	[§Annotation-based Auditing Metadata] "Auditing metadata does not necessarily need to live in the root level entity but can be added to an embedded one (depending on the actual store in use), as shown in the snippet below."	official-vendor-doc	도메인 핵심 클래스와 auditing 관심사 분리를 원하는 경우	"actual store in use" 라는 단서가 있음 — JPA 외 다른 Spring Data 스토어에서는 동작이 다를 수 있음
C3	@CreatedBy 또는 @LastModifiedBy 를 사용하려면 반드시 AuditorAware<T> SPI 를 구현해 현재 사용자(principal)를 auditing infrastructure 에 제공해야 한다	[§AuditorAware] "In case you use either @CreatedBy or @LastModifiedBy, the auditing infrastructure somehow needs to become aware of the current principal. To do so, we provide an AuditorAware<T> SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is."	official-vendor-doc	@CreatedBy / @LastModifiedBy 를 사용하는 모든 Spring Data JPA 애플리케이션	@CreatedDate / @LastModifiedDate 만 쓰는 경우에는 AuditorAware 구현 불필요 — 문서가 명시("Applications that only track creation and modification dates are not required to make their entities implement AuditorAware.")
C4	AuditingEntityListener 는 @EntityListeners(AuditingEntityListener.class) 어노테이션으로 엔티티 단위로 활성화할 수 있다	[§General Auditing Configuration] "You can also enable the AuditingEntityListener on a per-entity basis by using the @EntityListeners annotation, as follows:"	official-vendor-doc	특정 엔티티에만 auditing 을 선택적으로 적용하려는 경우	orm.xml global 등록과의 우선순위·충돌 여부는 이 문서만으로 판단 불가
C5	Spring Data JPA 1.5 이상에서는 Java Configuration 클래스에 @EnableJpaAuditing 을 붙여 auditing 을 활성화할 수 있으며, AuditorAware 빈이 ApplicationContext 에 노출되어 있으면 infrastructure 가 자동으로 감지해 사용한다	[§General Auditing Configuration] "As of Spring Data JPA 1.5, you can enable auditing by annotating a configuration class with the @EnableJpaAuditing annotation." + "If you expose a bean of type AuditorAware to the ApplicationContext, the auditing infrastructure automatically picks it up and uses it to determine the current user to be set on domain types."	official-vendor-doc	Spring Data JPA 1.5+ + Java Config 방식	orm.xml 수정과 spring-aspects.jar classpath 등록이 여전히 필요하다는 단서가 있음 — 문서 원문: "You must still modify the orm.xml file and have spring-aspects.jar on the classpath."

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:

  • C1: 네 가지 auditing 어노테이션의 공식 존재와 역할 (created/modified by/date)
  • C2: MappedSuperclass / embedded 위치에 auditing 메타데이터를 두는 것이 공식 지원됨
  • C3: @CreatedBy / @LastModifiedBy 사용 시 AuditorAware<T> 구현 의무
  • C4: @EntityListeners(AuditingEntityListener.class) 를 통한 per-entity 활성화
  • C5: @EnableJpaAuditing + AuditorAware 빈 자동 감지를 통한 Java Config 활성화

• 이 자료가 증명하지 않는 것:

  • @MappedSuperclass 패턴의 도메인 순수성(domain purity) 효과 — clean architecture 설계 맥락은 이 문서 범위 밖
  • 복수의 AuditorAware 빈 중 특정 빈을 선택하는 전략 (단, auditorAwareRef 속성 언급은 있음)
  • Reactive Stack (ReactiveAuditorAware) 과의 동작 차이
  • spring-aspects.jar 가 없을 때의 fallback 동작

• 내 프로젝트(ca-tmpl)에 적용하려면 추가 확인이 필요한 것:

  • @MappedSuperclass 에 @EntityListeners 를 두었을 때 자식 엔티티가 리스너를 상속받는지 — JPA spec 에서는 상속되나, 로컬 검증 필요
  • AuditorAware 를 Spring Security SecurityContextHolder 기반으로 구현했을 때 테스트 컨텍스트에서의 동작 (mock/stub 필요 여부)
  • spring-aspects.jar 의존성이 Gradle build file 에 이미 포함되어 있는지

메모 / Notes

• @MappedSuperclass 에 auditing 어노테이션을 선언하고 @EntityListeners 를 같이 붙이는 패턴이 C2 ("embedded one") 와 C4 ("per-entity @EntityListeners") 의 조합임. 이것이 D1/D2 결정의 구체적 구현 형태.
• C5 에 "You must still modify the orm.xml file" 조건이 있음 — orm.xml 없이 @EnableJpaAuditing 만으로 충분한지 Spring Boot auto-configuration 관점에서 별도 확인 필요.
• 추가로 봐야 할 동일 출처 페이지: Spring Data Commons 공통 auditing 페이지 (https://docs.spring.io/spring-data/commons/reference/auditing.html)

Related / 관련

• 같은 주제 다른 official-doc / company-tech-blog: (추가 시)
• 이 자료를 인용한 wiki 요약: [[wiki/concepts/spring-data-jpa-auditing]] (생성 시)