使用 Hibernate Envers 进行实体审计

业务应用程序中的常见要求是在特定数据更改时存储版本控制信息;当某事发生变化时，谁改变了它，改变了什么。在这篇博文中，我们将介绍Hibernate Envers，它是Hibernate JPA库的一个组件，它为实体类提供了一个简单的审计/版本控制解决方案。Envers 可与 Hibernate 和 JPA 配合使用，您可以在 Hibernate 工作的任何地方使用 Envers。

Envers 将更改存储在特殊的审计表中，并提供多种查询方法来访问历史快照。

设置

若要开始使用 Envers，首先需要将库添加到项目的类路径中。在 Maven 托管文件中，添加此依赖项。


    <dependency>
      <groupId>org.hibernategroupId>
      <artifactId>hibernate-enversartifactId>
      <version>5.4.6.Finalversion>
    dependency>

绒球.xml

接下来，使用 @Audited注释批注 Envers 应跟踪的实体类或实体属性。对于以下示例，我使用两个实体类：员工和公司。在 Employee 类中，我添加了类，Envers 跟踪此类中的所有属性。@Audited


@Entity
@Audited(withModifiedFlag = true)
public class Employee {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private int id;
 
  private String lastName;
 
  private String firstName;
 
  private String street;
 
  private String city;
 
  @ManyToOne
  private Company company;

员工.java

在公司类中，我只添加到属性。Envers 会跟踪此属性并忽略所有其他属性。Envers 还为添加到类但想要忽略特定属性的情况提供了@NotAudited注释。@Auditedname@Audited


@Entity
public class Company {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private int id;
 
  @Audited
  private String name;
 
  private String street;
 
  private String city;
 
  @OneToMany(mappedBy = "company", cascade = CascadeType.ALL, orphanRemoval = true)
  private Set employees;

公司.java

确保实体使用不可变的唯一标识符（主键）。

表

在下面的示例项目中，我将休眠配置设置为。hibernate.hbm2ddl.autoupdate

      <property name="hibernate.hbm2ddl.auto" value="update" />

坚持不懈.xml

完成此配置后，Hibernate会自动创建“员工”和“公司”两个表。对于每个实体，它创建一个审核表，Envers 在其中跟踪更改。它还创建 REVINFO 表，该表跟踪修订号和发生更改时的时间戳。@Audited

每次要插入、更新或删除实体时，Envers 都会介入并通过在 REVINFO 表和相应的 AUD 表中插入新行来创建新的修订。@Audited

请注意，EMPLOYEE_AUD表包含 EMPLOYEE 表中每个字段的字段，而COMPANY_AUD表仅包含字段，这是因为我们只在 Company 类中批注了属性。AUD 表的 ID 字段是相应实体表的主键;这就是主键必须是不可变的原因。namename

在 Employee 类中，我们启用了默认情况下禁用的withModifiedFlag选项（）。您可以在EMPLOYEE_AUD表中看到此选项的效果。Envers 为每个属性添加了额外的布尔属性_MOD。此修改标志存储属性在给定修订时已更改的信息。@Audited(withModifiedFlag = true)

在公司类中，我们未启用此选项。因此，COMPANY_AUD表不包含NAME_MOD字段。

为了进行比较，如果不启用该选项，则EMPLOYEE_AUD表定义：

仅当您需要此信息时，才应启用，因为代价是附加字段会增加审核表的大小。有一个 Envers 查询（）依赖于此附加信息，因此，如果计划使用此查询方法，则必须启用该选项。withModifiedFlagforRevisionsOfEntityWithChange

自定义修订实体

请注意，默认情况下，Envers仅跟踪发生更改的日期和时间。但是，在多用户应用程序中，您通常还想知道谁进行了更改。

为此，我们需要创建自定义修订实体类。此类必须扩展DefaultRevisionEntity类，并且必须使用 and@RevisionEntity 进行批注。您可以添加任何您喜欢的属性，它们将与修订号和时间戳一起存储在 REVINFO 表中。@Entity


import javax.persistence.Entity;
import javax.persistence.Table;
 
import org.hibernate.envers.DefaultRevisionEntity;
import org.hibernate.envers.RevisionEntity;
 
@Entity
@Table(name = "REVINFO")
@RevisionEntity(CustomRevisionEntityListener.class)
public class CustomRevisionEntity extends DefaultRevisionEntity {
 
  private static final long serialVersionUID = 1L;
 
  private String username;
 
  public String getUsername() {
    return this.username;
  }
 
  public void setUsername(String username) {
    this.username = username;
  }
}

自定义修订实体.java

我们指定的侦听器必须实现RevisionListener接口。我们只需要实现一种方法：在此方法中，我们需要填写其他属性，在本例中为用户名。我们不必触摸修订号和时间戳，Envers会自动设置它们。@RevisionEntitynewRevision


import org.hibernate.envers.RevisionListener;
 
public class CustomRevisionEntityListener implements RevisionListener {
 
  @Override
  public void newRevision(Object revisionEntity) {
    CustomRevisionEntity customRevisionEntity = (CustomRevisionEntity) revisionEntity;
    customRevisionEntity.setUsername(CurrentUser.INSTANCE.get());
  }
}

CustomRevisionEntityListener.java

对于此演示应用程序，我们将登录用户存储到 ThreadLocal 变量中。上面的侦听器提取它，我们将用户名设置为CurrentUser.INSTANCE.get()CurrentUser.INSTANCE.set(....)


public class CurrentUser {
 
  public static final CurrentUser INSTANCE = new CurrentUser();
 
  private static final ThreadLocal storage = new ThreadLocal<>();
 
  public void logIn(String user) {
    storage.set(user);
  }
 
  public void logOut() {
    storage.remove();
  }
 
  public String get() {
    return storage.get();
  }
}

当前用户.java

完成此配置后，REVINFO 表现在包含一个新字段：用户名

我直接从 Envers 文档中复制了这三个类。访问此 URL 了解更多信息：Hibernate ORM 5.4.33.Final User Guide

例子

在本节中，我们将插入、更新和删除一些数据，并查看 Envers 如何存储更改。

修订版 1：插入

首先，用户“Alice”插入一家公司和两名员工。


    EntityManager em = JPAUtil.getEntityManagerFactory().createEntityManager();
    CurrentUser.INSTANCE.logIn("Alice");
 
    em.getTransaction().begin();
    Company company = new Company();
    company.setName("E Corp");
    company.setCity("New York City");
    company.setStreet(null);
 
    Set employees = new HashSet<>();
 
    Employee employee = new Employee();
    employee.setCompany(company);
    employee.setLastName("Spencer");
    employee.setFirstName("Linda");
    employee.setStreet("High Street 123");
    employee.setCity("Newark");
    employees.add(employee);
 
    employee = new Employee();
    employee.setCompany(company);
    employee.setLastName("Ralbern");
    employee.setFirstName("Michael");
    employee.setStreet("57th Street");
    employee.setCity("New York City");
    employees.add(employee);
 
    company.setEmployees(employees);
 
    em.persist(company);
    em.getTransaction().commit();

主.java

请注意，您不必调用任何特殊的 Envers 方法。只需编写标准的JPA（或Hibernate）代码。在后台，Envers 侦听任何更新，并自动将审核信息插入数据库。

Envers 在 REVINFO 表中插入了一行新行，其中包含时间戳和用户名。由于我们在一个事务中插入了三个实体，因此只创建了一个 REVINFO 行。

Envers 还在新公司的COMPANY_AUD中插入了一个新行，REVTYPE 为 0 表示插入操作。此外，Envers 在EMPLOYEE_AUD表中插入了两行新行。因为在插入中，所有属性都已更改，所有_MOD字段都包含值 true。


REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+
 
COMPANY_AUD
+----+-----+---------+--------+
| ID | REV | REVTYPE |  NAME  |
+----+-----+---------+--------+
|  1 |   1 |       0 | E Corp |
+----+-----+---------+--------+
 
EMPLOYEE_AUD
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
| ID | REV | REVTYPE |      CITY      | CITY_MOD | FIRSTNAME | FIRSTNAME_MOD | LASTNAME | LASTNAME_MOD |      STREET      | STREET_MOD | COMPANY_ID | COMPANY_MOD |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   1 |       0 | New York City  |     TRUE | Michael   |          TRUE | Ralbern  |         TRUE | 57th Street      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   1 |       0 | Newark         |     TRUE | Linda     |          TRUE | Spencer  |         TRUE | High Street 123  |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+

修订版 2：更新公司

在下一笔交易中，“Bob”将公司名称从“E Corp”更改为“EEE Corp”。


    CurrentUser.INSTANCE.logIn("Bob");
 
    em.getTransaction().begin();
    CriteriaBuilder cb = em.getCriteriaBuilder();
    CriteriaQuery q = cb.createQuery(Company.class);
    Root c = q.from(Company.class);
    ParameterExpression p = cb.parameter(String.class);
    q.select(c).where(cb.equal(c.get("name"), p));
 
    TypedQuery query1 = em.createQuery(q);
    query1.setParameter(p, "E Corp");
 
    company = query1.getSingleResult();
    company.setName("EEE Corp");
 
    em.getTransaction().commit();

主.java

Envers 创建一个新的修订版本，并在COMPANY_AUD表中插入一个新行。REVTYPE = 1 表示更新操作。


REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+
|  2 | 1564997410849 | Bob      |
+----+---------------+----------+
 
COMPANY_AUD
+----+-----+---------+----------+
| ID | REV | REVTYPE |   NAME   |
+----+-----+---------+----------+
|  1 |   1 |       0 | E Corp   |
+----+-----+---------+----------+
|  1 |   2 |       1 | EEE Corp |
+----+-----+---------+----------+

修订版 3：新员工

“鲍勃”插入新员工：珍妮特·罗宾逊


    CurrentUser.INSTANCE.logIn("Bob");
 
    em.getTransaction().begin();
    employee = new Employee();
    employee.setCompany(company);
    employee.setLastName("Robinson");
    employee.setFirstName("Janet");
    employee.setCity("Greenwich");
    employee.setStreet("Walsh Ln 10");
    company.getEmployees().add(employee);
    em.getTransaction().commit();

主.java


REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+
|  2 | 1564997410849 | Bob      |
+----+---------------+----------+
|  3 | 1564997410858 | Bob      |
+----+---------------+----------+
 
 
EMPLOYEE_AUD
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
| ID | REV | REVTYPE |      CITY      | CITY_MOD | FIRSTNAME | FIRSTNAME_MOD | LASTNAME | LASTNAME_MOD |      STREET      | STREET_MOD | COMPANY_ID | COMPANY_MOD |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   1 |       0 | New York City  |     TRUE | Michael   |          TRUE | Ralbern  |         TRUE | 57th Street      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   1 |       0 | Newark         |     TRUE | Linda     |          TRUE | Spencer  |         TRUE | High Street 123  |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  3 |   3 |       0 | Greenwich      |     TRUE | Janet     |          TRUE | Robinson |         TRUE | Walsh Ln 10      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+

Revision 4: Update Employee

"Alice" updates the street and city of the employee Linda Spencer


    CurrentUser.INSTANCE.logIn("Alice");
 
    em.getTransaction().begin();
    TypedQuery query2 = createEmployeeQuery(em, "Linda", "Spencer");
    employee = query2.getSingleResult();
    employee.setStreet("101 W 91st St");
    employee.setCity("New York City");
    em.getTransaction().commit();

Main.java


REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+
|  2 | 1564997410849 | Bob      |
+----+---------------+----------+
|  3 | 1564997410858 | Bob      |
+----+---------------+----------+
|  4 | 1564997410873 | Alice    |
+----+---------------+----------+

在这里，我们看到只有 CITY_MOD 和 STREET_MOD 设置为 true，因为这是我们在代码中更改的唯一两个属性。


EMPLOYEE_AUD
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
| ID | REV | REVTYPE |      CITY      | CITY_MOD | FIRSTNAME | FIRSTNAME_MOD | LASTNAME | LASTNAME_MOD |      STREET      | STREET_MOD | COMPANY_ID | COMPANY_MOD |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   1 |       0 | New York City  |     TRUE | Michael   |          TRUE | Ralbern  |         TRUE | 57th Street      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   1 |       0 | Newark         |     TRUE | Linda     |          TRUE | Spencer  |         TRUE | High Street 123  |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  3 |   3 |       0 | Greenwich      |     TRUE | Janet     |          TRUE | Robinson |         TRUE | Walsh Ln 10      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   4 |       1 | New York City  |     TRUE | Linda     |         FALSE | Spencer  |        FALSE | 101 W 91st St    |       TRUE |          1 |       FALSE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+

修订版 5：删除员工

爱丽丝删除了员工迈克尔·拉尔伯恩


    CurrentUser.INSTANCE.logIn("Alice");
 
    em.getTransaction().begin();
    TypedQuery query3 = createEmployeeQuery(em, "Michael", "Ralbern");
    employee = query3.getSingleResult();
    employee.getCompany().getEmployees().remove(employee);
    em.remove(employee);
    em.getTransaction().commit();

主.java


REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+
|  2 | 1564997410849 | Bob      |
+----+---------------+----------+
|  3 | 1564997410858 | Bob      |
+----+---------------+----------+
|  4 | 1564997410873 | Alice    |
+----+---------------+----------+
|  5 | 1564997410892 | Alice    |
+----+---------------+----------+

在这里，我们看到 REVTYPE 2，它表示 DELETE 操作。对于删除操作，所有属性都设置为 NULL。


EMPLOYEE_AUD
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
| ID | REV | REVTYPE |      CITY      | CITY_MOD | FIRSTNAME | FIRSTNAME_MOD | LASTNAME | LASTNAME_MOD |      STREET      | STREET_MOD | COMPANY_ID | COMPANY_MOD |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   1 |       0 | New York City  |     TRUE | Michael   |          TRUE | Ralbern  |         TRUE | 57th Street      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   1 |       0 | Newark         |     TRUE | Linda     |          TRUE | Spencer  |         TRUE | High Street 123  |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  3 |   3 |       0 | Greenwich      |     TRUE | Janet     |          TRUE | Robinson |         TRUE | Walsh Ln 10      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   4 |       1 | New York City  |     TRUE | Linda     |         FALSE | Spencer  |        FALSE | 101 W 91st St    |       TRUE |          1 |       FALSE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   5 |       2 | NULL           |     TRUE | NULL      |          TRUE | NULL     |         TRUE | NULL             |       TRUE |       NULL |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+

查询

存储审核/版本信息是故事的一面，但我们还需要一种方法来在需要时访问此信息。为此，Envers 提供了几种方法来查询审计表。

查询方法的主要入口点是类AuditReader。创建实例，并将实体管理器实例作为参数传递。AuditReaderFactory.get


    EntityManager em = JPAUtil.getEntityManagerFactory().createEntityManager();
    AuditReader reader = AuditReaderFactory.get(em);