JPA 审计（AuditorAware）原理与事务边界陷阱：从自动填充到 afterCommit 取不到

本文聚焦 Spring Data JPA 的审计机制本身，不依赖任何具体业务，所有示例均为通用代码。

一、背景：为什么需要 JPA 审计

在持久层开发中，几乎每张表都有类似的"元数据字段"：

谁创建的（`createBy` / `createUserId`）

谁最后修改的（lastModifiedBy / updateUserId）
创建时间、修改时间

如果每次 save 都手写这些字段，不仅重复，还容易遗漏。JPA 审计的目标就是让框架在实体持久化/更新时自动填充这些字段。

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

二、核心概念

概念	说明
`@MappedSuperclass`	把公共字段定义抽到一个基类，子类表继承这些列
`@EntityListeners(AuditingEntityListener.class)`	为实体注册 JPA 生命周期监听器
`@CreatedBy` / `@LastModifiedBy`	标记"创建人/修改人"字段，由审计填充
`@CreatedDate` / `@LastModifiedDate`	标记"创建时间/修改时间"字段
`AuditingEntityListener`	Spring Data 提供的监听器，在 persist/flush 时触发填充
`AuditorAware<T>`	接口，告知框架"当前操作用户是谁"
`@EnableJpaAuditing`	开启审计能力的开关注解

三、审计基类的通用写法

java 复制代码

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

    @CreatedBy
    private String createdBy;

    @LastModifiedBy
    private String lastModifiedBy;

    @CreatedDate
    @Temporal(TemporalType.TIMESTAMP)
    private Date createdDate;

    @LastModifiedDate
    @Temporal(TemporalType.TIMESTAMP)
    private Date lastModifiedDate;

    // getter / setter 省略
}

子类实体直接继承即可，无需关心这些字段的赋值。

四、AuditorAware：审计的"数据来源"

框架并不知道"当前用户"从哪来，需要你提供实现：

java 复制代码

@Component
public class PrincipalAuditorAware implements AuditorAware<String> {

    @Override
    public Optional<String> getCurrentAuditor() {
        // 从任意"当前用户上下文"取，例如 SecurityContext、ThreadLocal、RPC 透传等
        String currentUser = CurrentUserHolder.get();
        return Optional.ofNullable(currentUser);
    }
}

启用审计：

java 复制代码

@Configuration
@EnableJpaAuditing
public class JpaAuditingConfiguration {

    @Bean
    public AuditorAware<String> auditorAware() {
        return new PrincipalAuditorAware();
    }
}

五、自动填充的触发时机（关键原理）

很多人误以为"调用 save 时就填好了"，其实不是。AuditingEntityListener 是通过 JPA 生命周期注解触发：

@PrePersist → 填充 @CreatedBy / @CreatedDate
@PreUpdate → 填充 @LastModifiedBy / @LastModifiedDate

而 @PrePersist / @PreUpdate 是在 EntityManager 执行持久化或 flush 的过程中回调的。这意味着：

审计填充发生在 flush 阶段，而 flush 必须在一个活跃事务里进行。

java 复制代码

@Transactional
public void create(Entity e) {
    repo.save(e);        // 仅纳入持久化上下文，@PrePersist 还没跑
}                        // 事务提交 → flush → @PrePersist 触发 → 自动填字段

六、事务边界与"上下文消失"问题

1. 事务的典型生命周期

复制代码

事务开启
  ├─ 业务代码执行（此时"当前用户上下文"通常在线程里）
  ├─ 事务提交 → flush → 审计监听器正常取到用户 → 自动填充 ✅
事务关闭 ← 此后线程的"请求级上下文"可能已被清理
afterCommit 回调执行
  └─ 此时已无活跃事务，且原请求上下文可能已消失

2. afterCommit 是什么

Spring 提供 TransactionSynchronization，允许在事务提交后执行回调：

java 复制代码

TransactionSynchronizationManager.registerSynchronization(
    new TransactionSynchronization() {
        @Override
        public void afterCommit() {
            // 事务已提交，这里执行"提交后动作"
        }
    });

常见用途：发 MQ、写审计日志、调用外部系统、异步通知等。

3. 为什么 afterCommit 里取不到审计用户

AuditorAware.getCurrentAuditor() 依赖某种"当前用户上下文"。这类上下文通常具有生命周期局限性：

基于请求（Request）：请求处理完即清除 → afterCommit 时已是"请求之后"，取不到。
基于 ThreadLocal + 请求拦截器：拦截器在请求结束时 remove() → afterCommit 时为空。
基于安全上下文（SecurityContextHolder 默认 ThreadLocal）：若事务外层清理了上下文，或回调跑在别的线程，也取不到。

而 afterCommit 的语义本就是"事务已结束、主流程早收尾"，所以任何依赖请求/主事务生命周期的上下文在这里都不可靠。

4. 表现出的现象

情况	结果
字段允许 null	`createdBy` 落库为 null，审计信息丢失
字段非空约束	落库抛 `NULL` 约束异常，整条记录写不进
`AuditorAware` 兜底返回默认值	落库一个"空用户/系统用户"，但不是真实操作人

这正是 JPA 审计在事务边界外的典型"坑"。

七、通用解决方案

方案 A：手动赋值（最直接、最常用）

在事务提交后的动作里，不依赖审计，直接设置字段：

java 复制代码

TransactionSynchronizationManager.registerSynchronization(
    new TransactionSynchronization() {
        @Override
        public void afterCommit() {
            SomeLog log = new SomeLog();
            log.setContent("...");
            // 手动填充审计字段，绕过 AuditorAware
            log.setCreatedBy("SYSTEM");
            log.setLastModifiedBy("SYSTEM");
            log.setCreatedDate(new Date());
            log.setLastModifiedDate(new Date());
            logRepository.saveAndFlush(log);
        }
    });

前提：saveAndFlush 必须在新事务 中（例如被 @Transactional(REQUIRES_NEW) 标注的方法调用），否则会因无事务而失败。

方案 B：在事务内提前捕获用户，传入回调

把"当前用户"在事务还活跃时取出来，作为不可变变量传给 afterCommit：

java 复制代码

@Transactional
public void business() {
    final String operator = CurrentUserHolder.get();   // 事务内取，可靠

    TransactionSynchronizationManager.registerSynchronization(
        new TransactionSynchronization() {
            @Override
            public void afterCommit() {
                SomeLog log = new SomeLog();
                log.setContent("...");
                log.setCreatedBy(operator);            // 用捕获到的值
                log.setLastModifiedBy(operator);
                log.setCreatedDate(new Date());
                log.setLastModifiedDate(new Date());
                logRepository.saveAndFlush(log);
            }
        });
}

这种方式能填真实操作人 ，而非固定 SYSTEM。

方案 C：AuditorAware 全局兜底

java 复制代码

@Override
public Optional<String> getCurrentAuditor() {
    return Optional.ofNullable(CurrentUserHolder.get())
                   .or(() -> Optional.of("SYSTEM"));
}

避免 NULL 约束异常，但所有边界外场景都会落到 SYSTEM，不够精确。

方案 D：独立事务 Service（推荐用于"提交后写库"）

把"提交后动作"抽到独立 @Service，用 REQUIRES_NEW 标注，由 afterCommit 调用它：

java 复制代码

@Service
public class PostCommitLogService {

    @Autowired
    private SomeLogRepository repo;

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void writeLog(String content, String operator) {
        SomeLog log = new SomeLog();
        log.setContent(content);
        log.setCreatedBy(operator);
        log.setLastModifiedBy(operator);
        log.setCreatedDate(new Date());
        log.setLastModifiedDate(new Date());
        repo.saveAndFlush(log);   // 在新事务内，flush 正常
    }
}

java 复制代码

@Transactional
public void business() {
    final String operator = CurrentUserHolder.get();

    TransactionSynchronizationManager.registerSynchronization(
        new TransactionSynchronization() {
            @Override
            public void afterCommit() {
                postCommitLogService.writeLog("done", operator);
            }
        });
}

这样既解决了"无事务 flush"问题，又解决了"审计用户取不到"问题（用户在事务内捕获后传入）。

八、关联陷阱清单

陷阱	说明
审计在 flush 时才填充	不是 save 时，依赖事务提交
afterCommit 无活跃事务	直接 `save` 不落库，`saveAndFlush` 抛 `TransactionRequiredException`
审计用户上下文消失	afterCommit 里 `AuditorAware` 取不到，需手动或传参
时间字段同理	`@CreatedDate` 也依赖 flush，边界外需手动 `new Date()`
乐观锁 `@Version`	边界外传入 detached 实体时，version 需手动给初值
detached 实体误 persist	边界外收到外部实体只读取，不要对其 `save`，否则抛 `detached entity passed to persist`

九、原则总结

审计填充依赖 flush，flush 依赖事务：凡是"事务之外"的写库，都不能指望自动审计。
afterCommit 是"事务已死"的世界：请求上下文、安全上下文、用户上下文在这里都不可信。
两条铁律 ：
- 提交后写库 → 必须开新事务 （REQUIRES_NEW 或 TransactionTemplate）。
- 提交后审计字段 → 必须手动设置 或事务内捕获用户后传入。
最干净的结构 ：把"提交后动作"封装成独立 @Service + REQUIRES_NEW 方法，调用方在事务内捕获所需数据（如操作人）传入，方法内手动填充审计字段。

一句话：JPA 审计是"事务内的便利"，不是"全局魔法"。一旦越过事务边界（尤其是 afterCommit），它就失效，必须由开发者显式接管字段赋值。

JPA 审计（AuditorAware）原理与事务边界陷阱：从自动填充到 afterCommit 取不到