告別手工記錄！一文教你用 Spring Boot 玩轉自動化數(shù)據(jù)變更追蹤

作者：路條編程 2025-10-20 01:10:00

通過 Javers + AOP + 注解的結合，我們實現(xiàn)了一個零侵入、自動化、結構化的數(shù)據(jù)變更追蹤系統(tǒng)。? 它讓業(yè)務代碼保持純凈，讓審計邏輯統(tǒng)一、透明、可查詢。

在現(xiàn)代企業(yè)系統(tǒng)中，數(shù)據(jù)變更的可追溯性已不再是可選項，而是合規(guī)與審計的核心要求。本文將帶你一步步構建一個基于 Spring Boot + Javers 的自動化數(shù)據(jù)變更追蹤方案，真正告別手工記錄與混亂日志，讓系統(tǒng)能“自己講清楚”數(shù)據(jù)是何時、由誰、怎么變的。

為什么要自動化數(shù)據(jù)變更追蹤？

在金融、政務、電商、配置管理等系統(tǒng)中，運營人員最常問的幾個問題往往是：

誰改了這條數(shù)據(jù)？
什么時候改的？
改了哪些字段？
原始值是什么？能恢復嗎？

這些問題的背后，本質(zhì)上都是數(shù)據(jù)變更追蹤（Data Change Audit）。很多團隊初期往往采用“人工記錄”的方式：

public void updatePrice(Long productId, BigDecimal newPrice) {
    Product old = productRepository.findById(productId).get();
    productRepository.updatePrice(productId, newPrice);
    auditService.save("價格從 " + old.getPrice() + " 改為 " + newPrice);
}

這種方式簡單直接，但當系統(tǒng)規(guī)模擴展后，問題接踵而至：

代碼重復：幾乎每個業(yè)務方法都需要寫同樣的日志邏輯。
維護困難：字段一變，日志邏輯也要改。
風格混亂：不同開發(fā)者記錄格式不一致。
難以查詢：字符串拼接日志沒法結構化檢索。
邏輯耦合：業(yè)務代碼被審計邏輯污染。

典型痛點案例：

某產(chǎn)品價格被誤改，查了半天日志才定位到操作人；某配置被誤刪，卻發(fā)現(xiàn)沒有字段級的變更記錄。

這些問題說明：手工審計已經(jīng)難以支撐復雜系統(tǒng)的可維護性。

目標與需求分析

要讓系統(tǒng)“自己追蹤變化”，我們需要一個自動化、可插拔的審計體系，它應滿足以下特性：

需求項	說明
零侵入性	業(yè)務邏輯不關心審計細節(jié)
自動化	配置或注解即可開啟
精確記錄	字段級別差異追蹤
結構化存儲	JSON 格式便于檢索
元數(shù)據(jù)完整	包含操作人、時間、動作類型等信息

技術方案選型

我們選用 Javers 作為核心比對組件，結合 Spring AOP 完成切面攔截與日志統(tǒng)一記錄。 Javers 的優(yōu)勢在于：

提供 專業(yè)對象差異算法（支持復雜嵌套結構）；
與 Spring Boot 無縫集成；
可輸出標準 JSON 差異；
支持 MongoDB、SQL、文件等多種存儲方式。

系統(tǒng)設計思路

整體架構如下：

┌─────────────────┐
│   Controller    │
└─────────┬───────┘
          │ AOP攔截
┌─────────▼───────┐
│     Service     │ ← 業(yè)務邏輯保持純凈
└─────────┬───────┘
          │
┌─────────▼───────┐
│   AuditAspect   │ ← 審計切面統(tǒng)一處理
└─────────┬───────┘
          │
┌─────────▼───────┐
│   Javers Core   │ ← 對象差異比對引擎
└─────────┬───────┘
          │
┌─────────▼───────┐
│  Audit Storage  │ ← 結構化存儲與查詢
└─────────────────┘

核心設計理念：

注解驅動：通過 @Audit 控制哪些方法被追蹤；
AOP 攔截：自動捕捉方法執(zhí)行；
Javers 比對：檢測對象變化；
統(tǒng)一存儲：結構化記錄變更日志。

項目依賴配置

在 /src/main/resources/pom.xml 中加入以下依賴：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-aop</artifactId>
    </dependency>
    <dependency>
        <groupId>org.javers</groupId>
        <artifactId>javers-core</artifactId>
        <version>7.3.1</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

核心模塊實現(xiàn)

審計注解 /src/main/java/com/icoderoad/audit/Audit.java

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Audit {


    String idField() default "id"; // 從實體中提取ID字段名


    String idParam() default "";   // 從方法參數(shù)中直接獲取ID


    ActionType action() default ActionType.AUTO; // 操作類型推斷


    String actorParam() default ""; // 操作人參數(shù)名


    int entityIndex() default 0; // 實體參數(shù)位置


    enum ActionType {
        CREATE, UPDATE, DELETE, AUTO
    }
}

審計切面 /src/main/java/com/icoderoad/audit/AuditAspect.java

@Slf4j
@Aspect
@Component
@RequiredArgsConstructor
public class AuditAspect {


    private final Javers javers;
    private final List<AuditLog> auditTimeline = new CopyOnWriteArrayList<>();
    private final Map<String, Object> dataStore = new ConcurrentHashMap<>();
    private final AtomicLong auditSequence = new AtomicLong(0);


    @Around("@annotation(audit)")
    public Object around(ProceedingJoinPoint joinPoint, Audit audit) throws Throwable {
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        String[] paramNames = signature.getParameterNames();
        Object[] args = joinPoint.getArgs();


        // 提取ID
        String entityId = extractEntityId(args, paramNames, audit);
        if (entityId == null) {
            log.warn("跳過審計：未找到實體ID");
            return joinPoint.proceed();
        }


        // 獲取執(zhí)行前快照
        Object before = dataStore.get(entityId);


        Object result = joinPoint.proceed();


        // 獲取執(zhí)行后快照
        Object after = args[audit.entityIndex()];


        Audit.ActionType actionType = audit.action();
        Diff diff = javers.compare(before, after);


        // 記錄審計日志
        recordAudit(after != null ? after.getClass().getSimpleName() : "Unknown",
                entityId,
                actionType.name(),
                extractActor(args, paramNames, audit),
                javers.getJsonConverter().toJson(diff));


        if (actionType != Audit.ActionType.DELETE) {
            dataStore.put(entityId, after);
        } else {
            dataStore.remove(entityId);
        }


        return result;
    }


    private String extractEntityId(Object[] args, String[] names, Audit audit) {
        if (!audit.idParam().isEmpty()) {
            for (int i = 0; i < names.length; i++) {
                if (names[i].equals(audit.idParam())) {
                    return args[i].toString();
                }
            }
        }
        return null;
    }


    private String extractActor(Object[] args, String[] names, Audit audit) {
        if (!audit.actorParam().isEmpty()) {
            for (int i = 0; i < names.length; i++) {
                if (names[i].equals(audit.actorParam())) {
                    return args[i].toString();
                }
            }
        }
        return "system";
    }


    private void recordAudit(String entity, String id, String action, String actor, String diffJson) {
        AuditLog logEntry = new AuditLog(
                String.valueOf(auditSequence.incrementAndGet()),
                entity,
                id,
                action,
                actor,
                Instant.now(),
                diffJson
        );
        auditTimeline.add(logEntry);
        log.info("審計記錄：{}", logEntry);
    }
}

業(yè)務服務 /src/main/java/com/icoderoad/service/ProductService.java

@Service
public class ProductService {


    private final Map<String, Product> products = new ConcurrentHashMap<>();


    @Audit(action = Audit.ActionType.CREATE, idParam = "id", actorParam = "actor", entityIndex = 1)
    public Product create(String id, ProductRequest request, String actor) {
        Product newProduct = new Product(id, request.name(), request.price(), request.description());
        return products.put(id, newProduct);
    }


    @Audit(action = Audit.ActionType.UPDATE, idParam = "id", actorParam = "actor", entityIndex = 1)
    public Product update(String id, ProductRequest request, String actor) {
        if (!products.containsKey(id)) throw new IllegalArgumentException("產(chǎn)品不存在: " + id);
        Product updated = new Product(id, request.name(), request.price(), request.description());
        return products.put(id, updated);
    }


    @Audit(action = Audit.ActionType.DELETE, idParam = "id", actorParam = "actor")
    public boolean delete(String id, String actor) {
        return products.remove(id) != null;
    }
}

審計日志實體 /src/main/java/com/icoderoad/audit/AuditLog.java

public record AuditLog(
        String id,
        String entityType,
        String entityId,
        String action,
        String actor,
        Instant occurredAt,
        String diffJson
) {}

Javers 配置 /src/main/java/com/icoderoad/config/JaversConfig.java

@Configuration
public class JaversConfig {


    @Bean
    public Javers javers() {
        return JaversBuilder.javers()
                .withPrettyPrint(true)
                .build();
    }
}

典型使用場景

產(chǎn)品更新操作

PUT /api/products/prod-001
X-User: 張三

請求體：

{
  "name": "iPhone 15",
  "price": 99.99,
  "description": "最新款手機"
}

生成審計日志：

{
  "entityId": "prod-001",
  "action": "UPDATE",
  "actor": "張三",
  "diffJson": "{\"changes\":[{\"field\":\"price\",\"oldValue\":100.00,\"newValue\":99.99}]}"
}

刪除操作

DELETE /api/products/prod-001
X-User: 李四

對應審計：

{
  "entityId": "prod-001",
  "action": "DELETE",
  "actor": "李四",
  "diffJson": "{\"changes\":[]}"
}

結語：讓系統(tǒng)“自己說話”的力量

通過 Javers + AOP + 注解 的結合，我們實現(xiàn)了一個零侵入、自動化、結構化的數(shù)據(jù)變更追蹤系統(tǒng)。它讓業(yè)務代碼保持純凈，讓審計邏輯統(tǒng)一、透明、可查詢。

這套方案帶來的收益包括：

開發(fā)效率提升：無需手寫日志邏輯；
維護成本降低：集中管理切面邏輯；
數(shù)據(jù)分析友好：結構化 JSON 格式，便于后期審計與BI接入。

在合規(guī)時代，系統(tǒng)不僅要“能跑”，更要“能解釋”。讓你的 Spring Boot 項目從今天起，真正具備可追溯的數(shù)據(jù)生命力。

責任編輯：武曉燕來源：路條編程

Spring 自動化數(shù)據(jù)