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

---
title: "official-doc / Spring Data JPA — Auditing (Annotation-based, AuditorAware SPI, @EnableJpaAuditing)"
source_type: official-doc
url: https://docs.spring.io/spring-data/jpa/reference/auditing.html
archive_url:
related_branches: [feature-persistence-auditing-contract]
related_projects: [ca-tmpl]
tags: [official-doc, ca-tmpl, persistence, spring-data, auditing]
created: 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]]` (생성 시)