企業級操作日誌設計：從硬編碼到 AOP 解耦的演進之路

業務背景與痛點

在某企業級專案中，需記錄操作人員、時間、模組、原始資料（列級）與變更後資料。初期系統架構缺乏統一日誌介面，各模組方法獨立、參數型別/順序/命名不一，導致硬編碼植入日誌極其繁瑣且難以維護。

方案演進對比

第一類：侵入式手工植入（初期專案適用）

1. 日誌操作類 + 介面調用：最直觀，但每個業務方法皆需手動呼叫，程式碼散落、耦合度高。
2. 訊息中間件（JMS）：非同步寫入，效能優於同步呼叫，但仍需各處植入發送邏輯，維護成本不降反增。
3. Log4j/Logback MDC 機制：利用診斷上下文（MDC）注入追蹤 ID，配合自定義 Appender 寫入資料庫。優點：對業務碼零侵入（僅需 AOP 切點）；缺點：結構化資料（舊/新值）序列化處理較繁瑣。

第二類：AOP 切面解耦（成熟專案首選）

採用 @BussAnnotation 標註業務語義（模組、操作類型），搭配 @Around 環繞通知攔截目標方法。

@Aspect
@Component
public class LogInterceptor {
    @Pointcut("@annotation(com.xxx.BussAnnotation)")
    public void bizPointcut() {}

    @Around("bizPointcut() && @annotation(anno)")
    public Object logAround(ProceedingJoinPoint pjp, BussAnnotation anno) throws Throwable {
        // 1. 解析註解元資料：anno.moduleName(), anno.option()
        // 2. 透過 pjp.getArgs() 獲取入參，配合 JSON 序列化保存完整物件圖
        // 3. 執行目標方法：Object result = pjp.proceed();
        // 4. 記錄回傳值/異常，非同步持久化至資料庫/ES
        return result;
    }
}

核心難點與解決策略

難點 1：參數無統一規範，導致「舊值/新值」難以自動提取

現狀：addUser(User u)、updateUser(User u, String x) 參數位置、型別不固定。

對策：

• 強制規範：所有寫操作方法第一參數為「業務實體物件」（含 ID），第二參數可選為「變更上下文」。
• 引入 @LogField 註解標註需追蹤的欄位，AOP 掃描註解自動構建變更集。
• 若無法規範歷史碼，採用「快照比對」：方法前後分別序列化實體，利用反射/JSON diff 產生變更日誌。

難點 2：大物件序列化效能與敏感資料脫敏

方案：

• 非同步寫入：日誌先入 BlockingQueue，專用執行緒批次落庫。
• 欄位級脫敏：配合 @Sensitive 註解，序列化時自動遮罩（身分證、手機、金額等）。

難點 3：攔截器（Interceptor）僅適用於 Controller 層

無法捕獲 Service/DAO 層的細粒度資料變更，故不作為主流方案。

架構建議總結

最佳實踐清單

1. 定義 OperationLog 統一實體：traceId、operator、module、action、entityType、entityId、beforeJson、afterJson、duration、status。
2. 建立 @AuditLog(module="用戶管理", action="UPDATE") 統一註解，替代散落的硬編碼。
3. AOP 切面僅負責「收集上下文 + 送入佇列」，持久化邏輯解耦至獨立模組。
4. 引入單元測試驗證：切面能否正確提取各式方法參數、異常場景是否記錄、效能基準（< 5ms 額外開銷）。

「日誌不是寫給機器看的，是寫給半夜排查 Bug 的自己看的。」—— 統一規範、非同步落庫、欄位脫敏，三者缺一不可。