Spring Boot应用使用@EnableMongoAuditing时触发NullPointerException问题排查

问题场景 #

在Spring Boot应用中添加@EnableMongoAuditing注解后，应用启动时抛出与审计机制相关的NullPointerException；移除该注解后问题消失，但需要保留审计功能。

相关实体类代码：

import ..*.model.ContractOverdue;
import *.model.Overdue;
import lombok.Builder;
import lombok.Data;
import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.mapping.Document;

import java.util.HashMap;

@Builder
@Data
@Document(collection = "contract-overdue")
public class MGReceiptContractOverdue {

    @Id
    private String id;
    private String contractRef;

    private HashMap<String, HashMap<Integer, Overdue>> overdueList;

    // Constructor and methods...
}

实体类中未定义任何审计相关字段，错误堆栈关键信息：

Caused by: java.lang.NullPointerException: null
    at org.springframework.data.mapping.context.PersistentPropertyPathFactory.from(PersistentPropertyPathFactory.java:266) ~[spring-data-commons-2.6.3.jar:2.6.3]
    at org.springframework.data.mapping.context.PersistentPropertyPathFactory.lambda$from$2(PersistentPropertyPathFactory.java:262) ~[spring-data-commons-2.6.3.jar:2.6.3]
    at org.springframework.data.mapping.model.BasicPersistentEntity.doWithProperties(BasicPersistentEntity.java:360) ~[spring-data-commons-2.6.3.jar:2.6.3]

问题原因 #

启用@EnableMongoAuditing后，Spring Data MongoDB会遍历所有实体类，尝试识别审计字段（如@CreatedDate、@LastModifiedDate）。但当前实体类中存在多层嵌套的HashMap泛型结构（HashMap<String, HashMap<Integer, Overdue>>），Spring Data Commons 2.6.x版本的PersistentPropertyPathFactory在解析这种复杂泛型嵌套时存在逻辑缺陷，导致空指针异常。

解决方案 #

方案1：添加审计字段 #

给实体类至少添加一个审计字段，让Spring Data的审计机制明确识别审计目标，跳过对复杂嵌套结构的无效解析：

import ..*.model.ContractOverdue;
import *.model.Overdue;
import lombok.Builder;
import lombok.Data;
import org.springframework.data.annotation.Id;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.mongodb.core.mapping.Document;

import java.time.LocalDateTime;
import java.util.HashMap;

@Builder
@Data
@Document(collection = "contract-overdue")
public class MGReceiptContractOverdue {

    @Id
    private String id;
    private String contractRef;

    private HashMap<String, HashMap<Integer, Overdue>> overdueList;
    
    @CreatedDate
    private LocalDateTime createdDate; // 审计字段，Spring会自动赋值

    // Constructor and methods...
}

方案2：升级Spring Data Commons版本 #

该空指针问题在Spring Data Commons 2.7.x及后续版本中已被官方修复，只需升级依赖版本即可。如果使用Spring Boot，可直接升级Spring Boot版本到2.7.x及以上（对应Spring Data Commons 2.7.x）。

方案3：标记实体类跳过审计 #

如果该实体类不需要审计功能，可使用@DisableAuditing注解标记，让全局审计机制忽略该实体：

@Builder
@Data
@Document(collection = "contract-overdue")
@DisableAuditing // 跳过该实体的审计处理
public class MGReceiptContractOverdue {
    // ... 原有代码
}

内容的提问来源于stack exchange，提问作者Smaillns