[Spring] spring-data-envers 를 이용한 엔티티 변경 이력 관리

들어가며

시스템 운영 단계에서 중요 데이터의 변경 이력을 저장하고 관리해야 하는 경우가 있다.

 

보통 history 테이블을 따로 만들어 이것들을 관리하곤 하는데

JPA 를 사용중이라면 spring-data-envers 를 통해 이를 편리하게 설정하고 관리할 수 있다.

 

spring-data-envers 는 hibernate-envers 의 wrapping 프로젝트로

envers 를 편리하게 사용할 수 있는 기능(RevisionRepository, 메타데이터 조회)을 제공한다.

 

1. Dependency (gradle)

implementation("org.springframework.data:spring-data-envers")

2. Auditing 활성화

감사를 진행할 엔티티에 @Audited 를 추가한다

@Getter
@Entity
@Audited
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    private String email;
}

 

전체 테이블에 대해서 이력을 남기고 싶다면 클래스에 @Audited 를 붙이고,

정해진 필드만 관리하고 싶다면 각 필드에 대해 @Audited 어노테이션을 붙이면 된다.

또 전체 필드 중 제외하고 싶은 필드가 있다면 @NotAudited 를 붙이면 감사 대상에서 제외된다.

 

@Audited
private String name;

@NotAudited
private String email;

 

이력 조회 대상에 대해 변경되었는지 여부를 flag 를 통해 관리할 수도 있다.

이 flag 를 조회해서 해당 버전에서 어떤 엔티티가 바뀌었는지 boolean 값으로 관리할 수 있다.

 

@Audited(withModifiedFlag = true, modifiedColumnName = "nameChanged")
private String name;

 

 

연관관계 대상 테이블에 대한 이력 관리 전략을 바꿀 수도 있다.

원래는 연관관계 테이블도 반드시 @Audited 를 통해 이력 관리 대상으로 추가해야 한다.

 

이를 @NotAudited 로 아예 제외시키거나

targetAuditMode 를 NOT_AUDITED 로 설정하여 fk 값만 저장하도록 할 수도 있다.

 

// FK 만 이력 조회 대상으로 한다
@Audited(targetAuditMode = RelationTargetAuditMode.NOT_AUDITED)
@ManyToOne(fetch=FetchType.LAZY)
private Department department;

// 이력 관리 대상에서 제외한다
@NotAudited
private Department department;

 

3. RevInfo 테이블

hibernate.ddl-auto 옵션이 create 또는 update 일 때

envers 는 자동으로 REVINFO 테이블과 ***_AUD 테이블을 생성한다

 

 

create table REVINFO (
    REV integer not null auto_increment, 
    REVTSTMP bigint, 
    primary key (REV)
) engine=InnoDB

create table User_AUD (
    REV integer not null, 
    REVTYPE tinyint, 
    nameChanged bit, 
    id bigint not null, 
    name varchar(255), 
    primary key (REV, id)
) engine=InnoDB

alter table User_AUD 
    add constraint FKilft2rdosb65jocpcoan7xnjq 
        foreign key (REV) references REVINFO (REV)

REVINFO 는 envers 의 버전 관리 정보로 버전 번호인 REV, 그리고 수정 시간을 REVSTMP 으로 기록한다.

 

이력 관리에 대한 테이블은 ****_AUD 로 생성되는데

REVINFO 에 대한 FK 로 REV 를 가지고 있으며 원래 엔티티의 PK 와 복합키 쌍으로 관리된다.

 

REVTYPE 은 수정 타입으로 다음과 같이 관리된다.

 

public enum RevisionType {
    ADD((byte)0), // 추가
    MOD((byte)1), // 수정
    DEL((byte)2); // 삭제

    ...
}

만약 네이밍 방식을 바꾸고 싶거나 REVINFO 엔티티를 변경하고 싶다면 커스텀이 가능하다.

 

envers 를 사용한다면 REVINFO 엔티티의 커스텀은 거의 필수적인데

자세히 보면 REVINFO 엔티티의 PK 인 REV 의 타입은 Integer 이기 때문이다.

 

이력 조회에 경우 실제 운영단계에서는 잦은 추가가 발생하기 때문에 금방 INT_MAX 에 도달하게 되고,

더이상 이력을 생성할 수 없는 이슈가 발생할 수 있다.

 

@Getter
@Entity
@RevisionEntity
@Table(name = "RevisionHistory")
public class CustomRevisionEntity {
    @Id
    @Column
    @RevisionNumber
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long revisionId;

    @Column @RevisionTimestamp
    private Long updatedAt;

    public LocalDateTime getUpdatedAt() {
        return LocalDateTime.ofInstant(Instant.ofEpochMilli(updatedAt), ZoneId.systemDefault());
    }
}

 

REVINFO 를 @RevisionEntity 를 통해 재정의할 수 있다.

REV 는 @RevisionNumber , REVTSTMP 는 @RevisionTimestamp 로 재정의한다.

 

# custom revision entity 로 변경된 쿼리

create table RevisionHistory (
    revisionId bigint not null auto_increment, 
    updatedAt bigint, primary key (revisionId)
) engine=InnoDB

create table User_AUD (
    REVTYPE tinyint, 
    REV bigint not null, 
    id bigint not null, 
    email varchar(255), 
    name varchar(255), 
primary key (REV, id)) engine=InnoDB

alter table User_AUD 
    add constraint FK7gw0sgfolgrr3a6xju5tvqxxp 
        foreign key (REV) references RevisionHistory (revisionId)

 

다만 생성 쿼리를 보면 알 수 있다시피 User_AUD 쪽의 정보는 변경되지 않았는데

이는 application.yml 의 추가 설정을 통해 변경할 수 있다.

 

spring:
    jpa:
    properties:
      org.hibernate.envers:
        audit_table_suffix: History # 이력 테이블 이름의 _AUD 를 History 로 변경
        revision_field_name: revisionId # 이력 테이블 REV 컬럼명
        revision_type_field_name: revisionType # 이력 테이블 REVTYPE 컬럼명
        store_data_at_delete: true # 삭제시 저장 여부, 기본은 false 이다

revision_field_name 을 변경하면 REV ⇒ 해당 이름의 컬럼명으로 변경된다

여러 유용한 추가 설정이 있는데 검색 또는 envers 패키지를 찾아보면 좋을 듯 싶다.

 

https://docs.jboss.org/hibernate/envers/3.6/reference/en-US/html/configuration.html

Chapter 3. Configuration

 

 

# yml 설정으로 변경된 쿼리

create table RevisionHistory (
    revisionId bigint not null auto_increment, 
    updatedAt bigint, primary key (revisionId)
) engine=InnoDB

create table UserHistory (
    revisionType tinyint, 
    id bigint not null, 
    revisionId bigint not null, 
    email varchar(255), 
    name varchar(255), 
    primary key (id, revisionId)
) engine=InnoDB

alter table UserHistory 
    add constraint FKtqxax72rt5cgosfu35jtcghu7 
        foreign key (revisionId) references RevisionHistory (revisionId)

이제 컬럼명이 이쁘게 수정되었다.

 

여기서 마지막으로 소개할 기능은 RevisionListener 이다.

REVINFO 생성 단계에서 추가적인 정보를 부여하고 싶을 때 사용하는 기능이다.

 

예를 들면 중요한 데이터라 누가 해당 버전에서 데이터를 수정했는지 관리할 필요가 있다 하자.

수정한 사람을 기록하기 위해 RevisionListener 와 interceptor 를 적절하게 활용할 수 있다.

 

public class CustomRevisionEntityListener implements RevisionListener {
    @Override
    public void newRevision(Object o) {
        final Admin currentAdmin = AuditThreadContext.getCurrentAdmin();
        CustomRevisionEntity customRevisionEntity = (CustomRevisionEntity) o;
        if (currentAdmin != null) {
            customRevisionEntity.setAdminId(currentAdmin.getAdminId());
        }
    }
}

 

인터셉터에서 AuditThreadContext 라는 임의의 ThreadLocal 에 어드민 정보를 저장하고,

Revision 엔티티를 생성할 때 이를 꺼내와서 저장하는 방식으로 수정한 어드민 정보를 관리한다.

 

이를 통해 데이터를 수정한 사람이 누구인지 History 생성 단계에서 지정해줄 수 있다.

 

@Getter
@Entity
@Table(name = "RevisionHistory")
@RevisionEntity(CustomRevisionEntityListener.class)
public class CustomRevisionEntity {
    @Id
    @Column
    @RevisionNumber
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long revisionId;

    @Column @RevisionTimestamp
    private Long updatedAt;

    @Column private Long adminId;

    public void setAdminId(Long adminId) {
        this.adminId = adminId;
    }

    public LocalDateTime getUpdatedAt() {
        return LocalDateTime.ofInstant(Instant.ofEpochMilli(updatedAt), ZoneId.systemDefault());
    }
}

@RevisionEntity 에 새로운 컬럼을 지정한 후, 리스너 클래스를 등록하는 방식으로 사용한다.

 

4. RevisionRepository

@NoRepositoryBean
public interface RevisionRepository<T, ID, N extends Number & Comparable<N>> extends Repository<T, ID> {
    Optional<Revision<N, T>> findLastChangeRevision(ID id);

    Revisions<N, T> findRevisions(ID id);

    Page<Revision<N, T>> findRevisions(ID id, Pageable pageable);

    Optional<Revision<N, T>> findRevision(ID id, N revisionNumber);
}

 

spring-data-envers 는 기본적인 RevisionRepository 인터페이스를 제공하며 이를 상속받아 사용할 수 있다.

타입 인자는 <엔티티 클래스, 엔티티 ID 타입, REV 타입> 이다.

 

public interface UserRepository
    extends CrudRepository<User, Long>, RevisionRepository<User, Long, Long> {}

 

• 최신 버전 단건 조회

public User findLatestUserRevisionById(Long id) {
    Revision<Long, User> latestRevision 
        = userRepository.findRevisions(id).getLatestRevision();

    User user = latestRevision.getEntity(); // 감사 엔티티
    Optional<Long> revisionNumber = latestRevision.getRevisionNumber(); // 버전번호
    Optional<Instant> revisionInstant = latestRevision.getRevisionInstant(); // 수정일시

    return user;
}

• Jpa Pageable 을 이용한 페이징 조회

public Page<User> findUserRevisionPage(Long id, Pageable pageable) {
    Page<Revision<Long, User>> revisionPage = userRepository.findRevisions(id, pageable);

    return revisionPage.map(Revision::getEntity);
}

 

5. 동적 쿼리

RevisionRepository 로 해결할 수 없는 복잡한 동적 쿼리는 AuditReader 를 사용하여 구현할 수 있다.

@Configuration
@RequiredArgsConstructor
public class AuditReaderConfig {
    private final EntityManagerFactory entityManagerFactory;

    @Bean
    public AuditReader auditReader() {
        return AuditReaderFactory.get(entityManagerFactory.createEntityManager());
    }
}

public interface UserHistoryRepositoryCustom {
    Optional<User> findLatestById(Long userId);
}

@RequiredArgsConstructor
public class UserHistoryRepositoryCustomImpl implements UserHistoryRepositoryCustom {
    private final AuditReader auditReader;

    public Optional<User> findLatestById(Long userId) {
        List<?> results =
                    auditReader
                            .createQuery()
                            .forRevisionsOfEntity(User.class, true, true)
                            .add(AuditEntity.id().eq(userId))
                            .addOrder(AuditEntity.revisionNumber().desc())
                            .setMaxResults(1)
                            .getResultList();
        return (results.isEmpty()) ? Optional.empty() : Optional.of((User) results.get(0));
    }
}

AuditReader 의 forRevisionsOfEntity 의 파라미터에 따라 여러 옵션이 오버로딩 되어있는데 필요에 따라 사용할 수 있다.

위의 예시에서는 추가적인 Revision 메타데이터 없이 유저 엔티티만 가져오는 옵션을 주었다.

 

where 절 조건은 .add() 체이닝으로 추가할 수 있고

and 는 AuditConjunction or 은 AuditDisjunction 이라는 타입을 제공해서 추가할 수 있다.

 

private AuditConjunction allMatch(AuditCriterion... criterion) {
    final AuditConjunction auditConjunction = new AuditConjunction();
    Arrays.stream(criterion).forEach(auditConjunction::add);
    return auditConjunction;
}

private AuditDisjunction anyMatch(AuditCriterion... criterion) {
    final AuditDisjunction auditDisjunction = new AuditDisjunction();
    Arrays.stream(criterion).forEach(auditDisjunction::add);
    return auditDisjunction;
}

 

AuditReader 를 사용해서 1개 결과를 조회할 때 List 로 먼저 가져온 후에 처리하는 것이 좋다

getSingleResult() 는 결과가 없을 경우 NoResultException 이 발생하기 때문이다.

 

패치된 결과는 Object[] 형태인데 프로젝션 갯수가 늘어날 때 마다 원소의 개수가 증가한다.

프로젝트에서는 이를 정해진 타입으로 관리하고 싶어 추가 필드를 만들어서 관리 중이다.

 

현재 프로젝트에서는 @Audited 에 수정 플래그를 사용 중인데

수정 플래그도 같이 가져오려면 forRevisionsOfEntityWithChanges 을 사용하면 된다.

 

이를 Object[] 의 3번 인덱스 원소로 수정된 엔티티 컬럼명을 Set 으로 제공한다.

(modifiedFlag 모드를 사용하고 있지 않다면 오류가 발생한다)

 

@Getter
@AllArgsConstructor
public class AuditReaderResult<T> {
    private final T entity;
    private final CustomRevisionEntity revisionEntity;
    private final RevisionType revisionType;
    private final Set<String> revisionFields;

    @SuppressWarnings("unchecked")
    public static <T> AuditReaderResult<T> from(Object[] result) {
        return new AuditReaderResult<>(
                (T) result[0],
                (CustomRevisionEntity) result[1],
                (RevisionType) result[2],
                (Set<String>) result[3]);
    }
}

@RequiredArgsConstructor
public class UserHistoryRepositoryCustomImpl implements UserHistoryRepositoryCustom {
    private final AuditReader auditReader;

    public Optional<User> findLatestById(Long userId) {
        final AuditCriterion predicate = this.allMatch(userIdEq(userId));
        final Optional<AuditReaderResult<User>> user = this.queryOne(predicate);

        return user.map(AuditReaderResult::getEntity);
    }

    private AuditCriterion userIdEq(Long userId) {
        return AuditEntity.property("id").eq(userId);
    }

    private <T> Optional<AuditReaderResult<T>> queryOne(AuditCriterion... auditCriterion) {
        List<?> results;
        synchronized (this) {
            results =
                    auditReader
                            .createQuery()
                            .forRevisionsOfEntityWithChanges(User.class, true)
                            .add(this.allMatch(auditCriterion))
                            .addOrder(AuditEntity.revisionNumber().desc())
                            .setMaxResults(1)
                            .getResultList();
        }
        final List<AuditReaderResult<T>> histories = auditReaderResultOf(results);
        return (histories.isEmpty()) ? Optional.empty() : Optional.of(histories.get(0));
    }

    private <T> List<AuditReaderResult<T>> auditReaderResultOf(List<?> results) {
        return results.stream()
                .map(Object[].class::cast)
                .map(AuditReaderResult::<T>from)
                .collect(Collectors.toList());
    }

    private AuditConjunction allMatch(AuditCriterion... criterion) {
        final AuditConjunction auditConjunction = new AuditConjunction();
        Arrays.stream(criterion).forEach(auditConjunction::add);
        return auditConjunction;
    }
}

 

Pageable 을 이용한 페이지네이션도 setFirstResult() 와 setMaxResults() 를 적절하게 섞어 구현할 수 있을 것이다.

 

@SuppressWarnings("unchecked")
private <T> Page<AuditReaderResult<T>> queryAll(
        Pageable pageable, AuditCriterion... auditCriterion) {
    final List<Long> coveringIndexes = (List<Long>)
            auditReader
                    .createQuery()
                    .forRevisionsOfEntity(User.class, false, true)
                    .add(this.allMatch(auditCriterion))
                    .addProjection(AuditEntity.revisionNumber())
                    .getResultList();

    final List<?> results =
                auditReader
                        .createQuery()
                        .forRevisionsOfEntityWithChanges(User.class, true)
                        .add(revisionIdIn(coveringIndexes))
                        .addOrder(AuditEntity.revisionNumber().desc())
                        .setFirstResult((int) pageable.getOffset())
                        .setMaxResults(pageable.getPageSize())
                        .getResultList();
    final List<AuditReaderResult<T>> histories = auditReaderResultOf(results);
    return PageableExecutionUtils.getPage(histories, pageable, coveringIndexes::size);
}

private AuditCriterion revisionIdIn(List<Long> ids) {
    return AuditEntity.revisionNumber().in(ids);
}

 

마치며

지금까지 spring-data-envers 를 이용해서 이력 조회를 간편하게 설정하는 방법을 알아보았다.

 

envers 를 이용하면 History 테이블을 직접 구현하지 않고도 이력 관리가 가능하기 때문에

운영 단계에서 생산성을 높일 수 있을 것이다.

 

또 생각보다 hibernate 에 많은 기능이 구현되어있고 지원해주니 잘 찾아보면 수고를 덜 수 있을 것 같다.