Spring Data JPA Auditing 자동으로 기록되는 엔티티 이력 관리하기

안녕하세요! 오늘은 Spring Data JPA에서 제공하는 아주 유용한 기능인 Auditing에 대해 알아보려고 합니다. 데이터베이스 테이블에 누가, 언제 데이터를 생성하거나 수정했는지 자동으로 기록하고 싶었던 적이 있으신가요? 이번 글을 읽으면 Spring Data JPA Auditing의 개념과 설정 방법, 실제 사용 예제를 통해 이러한 정보를 어떻게 쉽게 관리할 수 있는지 알 수 있어요. 또한 초보자부터 고급 사용자까지 모두 활용할 수 있는 실용적인 팁도 함께 소개해드립니다.

 

참고로 이 글을 정리하는 이유는 면접에서 이 기능을 이야기 했으면 좋았지 않을까 하는 생각에 작성한다.

엔티티에 수정자가 추가된다고 하면 어떻게 하는게 좋을까요? 라는 질문에 엔티티에 곧바로 추가한다라는 답변을 했는데 그 답변보다는 Auditing 기능을 사용한다고 하면 어땠을까? 라고 복기해봤다.

Auditing이란 무엇일까요?

'Auditing'이란 단어는 '감사' 또는 '검사'라는 의미를 가지고 있어요. 데이터베이스 맥락에서는 데이터가 언제, 누구에 의해 생성되거나 수정되었는지를 기록하는 과정을 말합니다. 마치 회계사가 장부를 검사하듯, 우리 시스템의 데이터 변경 이력을 추적하는 것이죠.

Spring Data JPA Auditing은 이러한 감사 정보를 자동으로 기록해주는 기능입니다. 각 엔티티(데이터베이스 테이블에 해당하는 객체)가 생성되거나 수정될 때마다 다음과 같은 정보를 자동으로 채워줍니다:

• 생성 시간 (createdAt)
• 마지막 수정 시간 (updatedAt)
• 생성자 정보 (createdBy)
• 마지막 수정자 정보 (updatedBy)

이 정보들은 데이터의 이력 관리, 문제 추적, 보안 감사 등 다양한 목적으로 활용할 수 있어요.

Auditing이 필요한 상황들

실제로 언제 Auditing이 필요할까요? 몇 가지 일상적인 예를 들어볼게요

1. 게시판 시스템에서 누가 언제 글을 작성했는지, 마지막 수정은 언제 이루어졌는지 표시할 때
2. 회원 정보가 언제 생성되고 마지막으로 언제 업데이트되었는지 관리할 때
3. 주문 시스템에서 주문이 생성된 시간과 상태가 변경된 시간을 추적할 때
4. 관리자 페이지에서 어떤 관리자가 어떤 데이터를 수정했는지 감사(audit)할 때

이런 정보들을 매번 수동으로 설정하는 것은 번거롭고 실수할 가능성도 높습니다. 그래서 Spring Data JPA는 이 작업을 자동화해주는 Auditing 기능을 제공하는 것이죠.

Auditing 설정하기: 4단계 과정

Spring Data JPA에서 Auditing을 사용하기 위한 설정은 크게 4단계로 이루어집니다.

1. @EnableJpaAuditing 어노테이션 추가하기

먼저 Spring 설정 클래스에 @EnableJpaAuditing 어노테이션을 추가해야 합니다. 이 어노테이션은 JPA Auditing 기능을 활성화시켜줍니다.

import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;

@Configuration
@EnableJpaAuditing
public class JpaConfig {
    // 추가 설정이 필요하다면 여기에 작성
}

2. AuditorAware 구현체 만들기

createdBy와 updatedBy 필드를 자동으로 채우려면, 현재 사용자(작업 수행자)의 정보를 제공하는 AuditorAware 인터페이스의 구현체가 필요합니다.

import org.springframework.data.domain.AuditorAware;
import org.springframework.stereotype.Component;

import java.util.Optional;

@Component
public class SpringSecurityAuditorAware implements AuditorAware<String> {
    @Override
    public Optional<String> getCurrentAuditor() {
        // 여기서는 간단히 "system"이라는 값을 반환
        // 실제로는 로그인한 사용자 정보를 반환하도록 구현
        return Optional.of("system");
    }
}

실제 애플리케이션에서는 Spring Security를 사용하여 현재 로그인한 사용자의 정보를 가져오는 방식으로 구현하는 경우가 많아요.

3. 엔티티에 @EntityListeners 추가하기

Auditing 기능을 적용할 엔티티 클래스에 @EntityListeners(AuditingEntityListener.class) 어노테이션을 추가합니다.

import org.springframework.data.jpa.domain.support.AuditingEntityListener;

import javax.persistence.Entity;
import javax.persistence.EntityListeners;

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Post {
    // 엔티티 필드들...
}

4. Auditing 필드에 어노테이션 추가하기

마지막으로, 자동으로 값이 채워질 필드들에 적절한 어노테이션을 추가합니다:

• @CreatedDate: 엔티티가 생성된 시간을 기록
• @LastModifiedDate: 엔티티가 마지막으로 수정된 시간을 기록
• @CreatedBy: 엔티티를 생성한 사용자 정보를 기록
• @LastModifiedBy: 엔티티를 마지막으로 수정한 사용자 정보를 기록

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 java.time.LocalDateTime;

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Post {
    // 다른 필드들...

    @CreatedDate
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    @CreatedBy
    private String createdBy;

    @LastModifiedBy
    private String updatedBy;

    // getter, setter 등...
}

실전 예제: 게시판 시스템에 Auditing 적용하기

이제 위에서 배운 지식을 활용해서 간단한 게시판 시스템에 Auditing을 적용해볼게요.

기본 설정 클래스

먼저 Auditing을 활성화하는 설정 클래스를 작성합니다:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.domain.AuditorAware;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;

import java.util.Optional;

@Configuration
@EnableJpaAuditing
public class AuditConfig {

    @Bean
    public AuditorAware<String> auditorProvider() {
        return new AuditorAware<String>() {
            @Override
            public Optional<String> getCurrentAuditor() {
                Authentication auth = SecurityContextHolder.getContext().getAuthentication();

                if (auth == null || !auth.isAuthenticated()) {
                    return Optional.of("anonymousUser");
                }

                return Optional.of(auth.getName());
            }
        };
    }
}

이 설정은 Spring Security와 연동하여, 현재 로그인한 사용자의 이름을 Auditing 정보로 사용합니다.

공통 Auditing 엔티티 만들기

여러 엔티티에서 공통으로 사용할 수 있는 기본 Auditing 엔티티를 만들어 봅시다:

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 javax.persistence.EntityListeners;
import javax.persistence.MappedSuperclass;
import java.time.LocalDateTime;

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseEntity {

    @CreatedDate
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    @CreatedBy
    private String createdBy;

    @LastModifiedBy
    private String updatedBy;

    // getter 메소드들
    public LocalDateTime getCreatedAt() {
        return createdAt;
    }

    public LocalDateTime getUpdatedAt() {
        return updatedAt;
    }

    public String getCreatedBy() {
        return createdBy;
    }

    public String getUpdatedBy() {
        return updatedBy;
    }
}

여기서 @MappedSuperclass 어노테이션은 이 클래스가 데이터베이스 테이블로 매핑되지 않고, 이 클래스를 상속받는 엔티티 클래스에만 매핑 정보를 제공한다는 것을 의미합니다.

게시물 엔티티 만들기

이제 BaseEntity를 상속받는 Post 엔티티를 만들어 봅시다:

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class Post extends BaseEntity {

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

    private String title;

    private String content;

    // getter, setter 메소드들
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getContent() {
        return content;
    }

    public void setContent(String content) {
        this.content = content;
    }
}

이렇게 하면 Post 엔티티는 자동으로 생성 시간, 수정 시간, 생성자, 수정자 정보를 가지게 됩니다. 새 게시물을 작성하거나 기존 게시물을 수정할 때마다 이 정보들이 자동으로 업데이트됩니다.

어떻게 동작하는지 이해하기

Auditing이 어떻게 동작하는지 더 깊이 이해해볼까요?

1. 새로운 엔티티가 저장될 때:
   • @CreatedDate 필드에 현재 시간이 자동으로 설정됩니다.
   • @LastModifiedDate 필드도 같은 시간으로 설정됩니다.
   • @CreatedBy 필드에 AuditorAware.getCurrentAuditor()가 반환한 값이 설정됩니다.
   • @LastModifiedBy 필드도 같은 값으로 설정됩니다.
2. 기존 엔티티가 업데이트될 때:
   • @CreatedDate와 @CreatedBy 필드는 그대로 유지됩니다.
   • @LastModifiedDate 필드는 현재 시간으로 업데이트됩니다.
   • @LastModifiedBy 필드는 현재 AuditorAware.getCurrentAuditor()가 반환한 값으로 업데이트됩니다.

이 모든 작업은 JPA의 엔티티 라이프사이클 이벤트를 활용하여 자동으로 처리됩니다. 그래서 개발자가 직접 이런 값들을 설정해줄 필요가 없어요.

고급자를 위한 팁

여기까지 Spring Data JPA Auditing의 기본적인 사용법을 알아보았습니다. 이제 좀 더 고급 기능과 팁을 살펴볼게요.

1. 시간 정보만 기록하기

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseTimeEntity {

    @CreatedDate
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    // getter 메소드들
    public LocalDateTime getCreatedAt() {
        return createdAt;
    }

    public LocalDateTime getUpdatedAt() {
        return updatedAt;
    }
}

이렇게 시간 정보만 담은 기본 엔티티를 만들면, 사용자 정보가 필요하지 않은 엔티티에서 이 클래스를 상속받아 사용할 수 있습니다.

2. 다양한 타입의 사용자 ID 사용하기

앞서 예제에서는 사용자 ID를 String 타입으로 사용했지만, 프로젝트의 요구사항에 따라 Long, Integer, UUID 등 다양한 타입을 사용할 수 있습니다.

@Component
public class LongAuditorAware implements AuditorAware<Long> {
    @Override
    public Optional<Long> getCurrentAuditor() {
        // SecurityContext나 다른 방법으로 사용자 ID를 가져옴
        // 예를 들어, 현재 로그인한 사용자의 ID가 123이라고 가정
        return Optional.of(123L);
    }
}

이 경우 BaseEntity 클래스에서도 createdBy와 updatedBy 필드의 타입을 Long으로 변경해야 합니다.

3. 사용자 엔티티 객체 직접 저장하기

단순히 ID나 이름 대신 사용자 엔티티 객체 자체를 저장할 수도 있습니다. 하지만 이 방식은 몇 가지 주의할 점이 있습니다.

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseEntity {

    @CreatedDate
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    @CreatedBy
    @ManyToOne
    @JoinColumn(name = "created_by_id")
    private User createdBy;

    @LastModifiedBy
    @ManyToOne
    @JoinColumn(name = "updated_by_id")
    private User updatedBy;

    // getter 메소드들...
}

이 방식을 사용할 때 주의할 점:

• 순환 참조가 발생할 가능성이 있습니다.
• Lazy Loading 설정에 따라 성능 이슈가 발생할 수 있습니다.
• 사용자 정보가 변경될 경우 Auditing 정보도 함께 변경될 수 있습니다.

그래서 보통은 사용자 객체 자체보다는 ID나 사용자 이름을 저장하는 것이 권장됩니다.

4. Custom Auditor 설정하기

Spring Security를 사용하지 않거나, 특별한 요구사항이 있는 경우 커스텀 Auditor를 설정할 수 있습니다.

@Component
public class CustomAuditorAware implements AuditorAware<String> {

    @Autowired
    private HttpServletRequest request;

    @Override
    public Optional<String> getCurrentAuditor() {
        // HTTP 요청 헤더에서 사용자 정보를 가져오는 예제
        String userInfo = request.getHeader("X-User-Info");
        if (userInfo != null && !userInfo.isEmpty()) {
            return Optional.of(userInfo);
        }
        return Optional.of("system");
    }
}

이렇게 HTTP 요청 헤더, 세션 정보, ThreadLocal 등 다양한 방법으로 사용자 정보를 가져올 수 있습니다.

5. 조건부 Auditing 적용하기

특정 조건에서만 Auditing을 적용하고 싶을 때는 JPA의 @PrePersist와 @PreUpdate 이벤트를 활용할 수 있습니다.

@Entity
public class ConditionalAuditEntity {

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

    private String content;

    private LocalDateTime createdAt;

    private LocalDateTime updatedAt;

    @PrePersist
    public void prePersist() {
        // 특정 조건에 따라 createdAt 설정
        if (this.content != null && !this.content.isEmpty()) {
            this.createdAt = LocalDateTime.now();
            this.updatedAt = this.createdAt;
        }
    }

    @PreUpdate
    public void preUpdate() {
        // 특정 조건에 따라 updatedAt 설정
        if (this.content != null && !this.content.isEmpty()) {
            this.updatedAt = LocalDateTime.now();
        }
    }

    // getter, setter 메소드들...
}

이 방식은 Spring Data JPA Auditing보다 직접적인 제어가 필요할 때 유용합니다.

자주 발생하는 문제와 해결 방법

Auditing을 사용하다 보면 몇 가지 일반적인 문제가 발생할 수 있습니다. 여기에 그 문제들과 해결 방법을 소개합니다.

1. Auditing 정보가 null로 설정되는 문제

AuditorAware.getCurrentAuditor()에서 Optional.empty()를 반환하면 Auditing 필드가 null로 설정됩니다. 이를 방지하기 위해 항상 기본값을 반환하도록 구현합니다.

@Override
public Optional<String> getCurrentAuditor() {
    Authentication auth = SecurityContextHolder.getContext().getAuthentication();

    if (auth == null || !auth.isAuthenticated() || auth.getPrincipal().equals("anonymousUser")) {
        return Optional.of("system"); // 기본값 설정
    }

    return Optional.of(auth.getName());
}

2. 특정 필드만 업데이트할 때 Auditing 정보가 변경되지 않는 문제

JPA의 @DynamicUpdate 어노테이션을 사용하여 변경된 필드만 업데이트하도록 설정하면, Auditing 필드가 업데이트되지 않을 수 있습니다. 이 경우 해당 엔티티에 @DynamicUpdate(false)를 설정하거나, 명시적으로 Auditing 필드도 함께 업데이트해야 합니다.

3. 대량 업데이트 시 Auditing이 동작하지 않는 문제

UPDATE 쿼리를 직접 실행하는 경우(예: @Query를 사용한 업데이트나 Querydsl을 사용한 대량 업데이트), JPA의 엔티티 라이프사이클 이벤트가 발생하지 않아 Auditing이 동작하지 않습니다. 이 경우 업데이트 쿼리에 Auditing 정보를 명시적으로 포함시켜야 합니다.

@Modifying
@Query("UPDATE Post p SET p.title = :title, p.updatedAt = :now, p.updatedBy = :user WHERE p.id = :id")
int updatePost(@Param("id") Long id, @Param("title") String title, 
               @Param("now") LocalDateTime now, @Param("user") String user);

실제 프로젝트에서의 Auditing 활용 예시

Auditing을 실제 프로젝트에서 어떻게 활용할 수 있는지 몇 가지 예시를 살펴보겠습니다.

1. 게시판 시스템에서의 활용

게시판 시스템에서는 게시물의 작성 시간, 수정 시간, 작성자, 수정자 정보를 표시하는 데 Auditing을 활용할 수 있습니다.

@Service
public class PostService {

    @Autowired
    private PostRepository postRepository;

    public PostDto getPost(Long id) {
        Post post = postRepository.findById(id)
                .orElseThrow(() -> new PostNotFoundException(id));

        return PostDto.builder()
                .id(post.getId())
                .title(post.getTitle())
                .content(post.getContent())
                .createdAt(post.getCreatedAt())
                .createdBy(post.getCreatedBy())
                .updatedAt(post.getUpdatedAt())
                .updatedBy(post.getUpdatedBy())
                .build();
    }
}

그리고 화면에 다음과 같이 표시할 수 있습니다:

<div class="post-info">
    <span>작성자: ${post.createdBy}</span>
    <span>작성일: ${post.createdAt}</span>
    <c:if test="${post.updatedAt != post.createdAt}">
        <span>(수정됨: ${post.updatedAt}, ${post.updatedBy})</span>
    </c:if>
</div>

2. 관리자 페이지에서의 활용

관리자 페이지에서는 특정 데이터가 누구에 의해 언제 생성되고 수정되었는지 추적할 수 있습니다.

@GetMapping("/admin/audit-log")
public String getAuditLog(Model model) {
    List<AuditLog> auditLogs = auditLogService.getRecentAuditLogs();
    model.addAttribute("auditLogs", auditLogs);
    return "admin/audit-log";
}

여기서 AuditLog는 엔티티의 생성 및 수정 정보를 포함하는 별도의 DTO나 엔티티일 수 있습니다.

3. 데이터 변경 이력 추적

더 상세한 변경 이력 추적이 필요한 경우, Auditing과 함께 별도의 이력 테이블을 활용할 수 있습니다.

@Entity
public class PostHistory {

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

    private Long postId;

    private String title;

    private String content;

    private LocalDateTime changedAt;

    private String changedBy;

    // getter, setter 메소드들...
}

그리고 Post 엔티티가 업데이트될 때마다 이력을 저장합니다:

@Service
public class PostService {

    @Autowired
    private PostRepository postRepository;

    @Autowired
    private PostHistoryRepository postHistoryRepository;

    @Transactional
    public Post updatePost(Long id, PostUpdateRequest request) {
        Post post = postRepository.findById(id)
                .orElseThrow(() -> new PostNotFoundException(id));

        // 현재 상태를 이력으로 저장
        PostHistory history = new PostHistory();
        history.setPostId(post.getId());
        history.setTitle(post.getTitle());
        history.setContent(post.getContent());
        history.setChangedAt(LocalDateTime.now());
        history.setChangedBy(post.getUpdatedBy());
        postHistoryRepository.save(history);

        // 게시물 업데이트
        post.setTitle(request.getTitle());
        post.setContent(request.getContent());
        return postRepository.save(post);
    }
}

마무리

이번 글에서는 Spring Data JPA Auditing의 개념과 사용법, 그리고 실제 프로젝트에서의 활용 방법에 대해 알아보았습니다. Auditing은 데이터의 생성 및 수정 이력을 관리하는 매우 유용한 기능으로, 특히 여러 사용자가 접근하는 웹 애플리케이션에서 중요한 역할을 합니다.

간단한 설정만으로도 모든 엔티티에 일관된 Auditing 정보를 자동으로 기록할 수 있어, 개발자의 부담을 크게 줄여줍니다. 또한 필요에 따라 다양하게 확장하고 커스터마이징할 수 있어 여러 상황에 맞게 활용할 수 있습니다.

더 알아보기

Auditing과 함께 사용할 수 있는 Hibernate Envers

참고

https://docs.spring.io/spring-data/jpa/reference/auditing.html

Auditing :: Spring Data JPA

https://hudi.blog/spring-data-jpa-auditing-create-update-date/

Spring Data JPA Auditing으로 엔티티의 생성/수정 시각 자동으로 기록

 

Claude AI