EF Core 資料變更自動審計設計

Intro

有的時候我們需要知道每個資料表的變更記錄以便做一些資料審計，資料恢復以及資料同步等之類的事情，
EF 自帶了物件追蹤，使得我們可以很方便的做一些審計作業，每次變更發生了什么變化都變得很清晰，于是就基于 EF 封裝了一層資料變更自動審計

使用效果

測驗代碼：

private static void AutoAuditTest()
{
    // 審計配置
    AuditConfig.Configure(builder =>
    {
        builder
            // 配置操作用戶獲取方式
            .WithUserIdProvider(EnvironmentAuditUserIdProvider.Instance.Value)
            //.WithUnModifiedProperty() // 保存未修改的屬性,默認只保存發生修改的屬性
            // 保存更多屬性
            .EnrichWithProperty("MachineName", Environment.MachineName)
            .EnrichWithProperty(nameof(ApplicationHelper.ApplicationName), ApplicationHelper.ApplicationName)
            // 保存到自定義的存盤
            .WithStore<AuditFileStore>()
            .WithStore<AuditFileStore>("logs.log")
            // 忽略指定物體
            .IgnoreEntity<AuditRecord>()
            // 忽略指定物體的某個屬性
            .IgnoreProperty<TestEntity>(t => t.CreatedAt)
            // 忽略所有屬性名稱為 CreatedAt 的屬性
            .IgnoreProperty("CreatedAt")
            ;
    });
    
    DependencyResolver.TryInvokeService<TestDbContext>(dbContext =>
    {
        dbContext.Database.EnsureDeleted();
        dbContext.Database.EnsureCreated();
        var testEntity = new TestEntity()
        {
            Extra = new { Name = "Tom" }.ToJson(),
            CreatedAt = DateTimeOffset.UtcNow,
        };
        dbContext.TestEntities.Add(testEntity);
        dbContext.SaveChanges();

        testEntity.CreatedAt = DateTimeOffset.Now;
        testEntity.Extra = new { Name = "Jerry" }.ToJson();
        dbContext.SaveChanges();

        dbContext.Remove(testEntity);
        dbContext.SaveChanges();

        var testEntity1 = new TestEntity()
        {
            Extra = new { Name = "Tom1" }.ToJson(),
            CreatedAt = DateTimeOffset.UtcNow,
        };
        dbContext.TestEntities.Add(testEntity1);
        var testEntity2 = new TestEntity()
        {
            Extra = new { Name = "Tom2" }.ToJson(),
            CreatedAt = DateTimeOffset.UtcNow,
        };
        dbContext.TestEntities.Add(testEntity2);
        dbContext.SaveChanges();
    });
    DependencyResolver.TryInvokeService<TestDbContext>(dbContext =>
    {
        dbContext.Remove(new TestEntity()
        {
            Id = 2
        });
        dbContext.SaveChanges();
    });
    // disable audit
    AuditConfig.DisableAudit();
}

查看審計記錄資訊：

audit records

可以看到，每次資料變更都會被記錄下來，CreatedAt 沒有記錄是因為上面配置的忽略 CreatedAt 屬性資訊的記錄，

這里的 TableName ，屬性名稱和 Entity 定義的不同是為了測驗列名和屬性名稱不一致的情況，實際記錄的是資料庫里的表名稱和列名稱，之所以這樣設計考慮的是可能多個應用使用同一張表，但是不同的應用里可能使用的 Entity 和 Property 都不同，所以統一使用了資料庫的表名稱和欄位名稱，

OperationType是一個列舉，1是新增，2是洗掉，3是修改，

Extra 列對應的就是我們自定義的增加的審計屬性

UpdatedBy 是我們配置的 UserIdProvider 所提供的操作用戶的資訊

值得注意的是最后一條變更記錄，這條資料的洗掉沒有經過資料庫查詢，直接洗掉的，EF 不知道原本的除了主鍵之外的資訊，所以記錄的原始資訊可能不準確，不過還是知道誰洗掉的這一條資料，對比之前的變更還是可以滿足需求的，

實作原理

實作的原理是基于 EF 的內置的 Change Tracking 來實作的，EF 每次 SaveChanges 之前都會檢測變更，每條變更的記錄都會記錄變更前的屬性值以及變更之后的屬性值，因此我們可以在 SaveChanges 之前記錄變更前后的屬性，對于資料庫生成的值，如 SQL Server 里的自增主鍵，在保存之前，屬性的會被標記為 IsTemporary ，保存成功之后會自動更新，在保存之后可以獲取到資料庫生成的值，

實作代碼

首先實作一個 DbContextBase，重寫 SaveChanges 和 SaveChangesAsync 方法，增加

BeforeSaveChanges 和 AfterSaveChanges 方法，用于處理我們要自定義的保存之前和保存之后的邏輯，

public abstract class DbContextBase : DbContext
{
    protected DbContextBase()
    {
    }

    protected DbContextBase(DbContextOptions dbContextOptions) : base(dbContextOptions)
    {
    }

    protected virtual Task BeforeSaveChanges() => Task.CompletedTask;

    protected virtual Task AfterSaveChanges() => Task.CompletedTask;

    public override int SaveChanges()
    {
        BeforeSaveChanges().Wait();
        var result = base.SaveChanges();
        AfterSaveChanges().Wait();
        return result;
    }

    public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
    {
        await BeforeSaveChanges();
        var result = await base.SaveChangesAsync(cancellationToken);
        await AfterSaveChanges();
        return result;
    }

接著來實作一個用來自動審計的 AuditDbContextBase，核心代碼如下：

public abstract class AuditDbContextBase : DbContextBase
{
    protected AuditDbContextBase()
    {
    }

    protected AuditDbContextBase(DbContextOptions dbContextOptions) : base(dbContextOptions)
    {
    }

    protected List<AuditEntry> AuditEntries { get; set; }

    protected override Task BeforeSaveChanges()
    {
        AuditEntries = new List<AuditEntry>();
        foreach (var entityEntry in ChangeTracker.Entries())
        {
            if (entityEntry.State == EntityState.Detached || entityEntry.State == EntityState.Unchanged)
            {
                continue;
            }
            AuditEntries.Add(new AuditEntry(entityEntry));
        }

        return Task.CompletedTask;
    }

    protected override async Task AfterSaveChanges()
    {
        if (null != AuditEntries && AuditEntries.Count > 0)
        {
            foreach (var auditEntry in AuditEntries)
            {
                // update TemporaryProperties
                if (auditEntry.TemporaryProperties != null && auditEntry.TemporaryProperties.Count > 0)
                {
                    foreach (var temporaryProperty in auditEntry.TemporaryProperties)
                    {
                        var colName = temporaryProperty.Metadata.GetColumnName();
                        if (temporaryProperty.Metadata.IsPrimaryKey())
                        {
                            auditEntry.KeyValues[colName] = temporaryProperty.CurrentValue;
                        }

                        switch (auditEntry.OperationType)
                        {
                            case OperationType.Add:
                                auditEntry.NewValues[colName] = temporaryProperty.CurrentValue;
                                break;

                            case OperationType.Delete:
                                auditEntry.OriginalValues[colName] = temporaryProperty.OriginalValue;
                                break;

                            case OperationType.Update:
                                auditEntry.OriginalValues[colName] = temporaryProperty.OriginalValue;
                                auditEntry.NewValues[colName] = temporaryProperty.CurrentValue;
                                break;
                        }
                    }
                    // set to null
                    auditEntry.TemporaryProperties = null;
                }
        }
        // ... save audit entries
    }
}

此時我們已經可以實作自動的審計處理了，但是在實際業務處理的程序中，往往我們還會有更多的需求，

比如上面的實作還沒有加入更新人，不知道是由誰來操作的，有些欄位可能不希望被記錄下來，或者有些表不要記錄，還有我們向增加一些自定義的屬性，比如多個應用操作同一個資料庫表的時候我們可能希望記錄下來是哪一個用戶通過哪一個應用來更新的等等，所以之前上面的實作還是不能夠實際應用的，于是我又在上面的基礎上增加了一些配置以及擴展，使得自動審計擴展性更好，可定制性更強，

擴展設計

UserIdProvider

我們可以通過 UserIdProvider 來實作操作用戶資訊的獲取，默認提供兩個實作，定義如下：

public interface IAuditUserIdProvider
{
    string GetUserId();
}

默認實作：

// 獲取 Environment.UserName
public class EnvironmentAuditUserIdProvider : IAuditUserIdProvider
{
    private EnvironmentAuditUserIdProvider()
    {
    }

    public static Lazy<EnvironmentAuditUserIdProvider> Instance = new Lazy<EnvironmentAuditUserIdProvider>(() => new EnvironmentAuditUserIdProvider(), true);

    public string GetUserId() => Environment.UserName;
}
// 獲取 Thread.CurrentPrincipal.Identity.Name
public class ThreadPrincipalUserIdProvider : IAuditUserIdProvider
{
    public static Lazy<ThreadPrincipalUserIdProvider> Instance = new Lazy<ThreadPrincipalUserIdProvider>(() => new ThreadPrincipalUserIdProvider(), true);

    private ThreadPrincipalUserIdProvider()
    {
    }

    public string GetUserId() => Thread.CurrentPrincipal?.Identity?.Name;
}

當然如果是 asp.net core 你也可以實作相應的基于 HttpContext 實作的 UserIdProvider

Filters

基于我們可能希望忽略一些物體或屬性記錄，所以有必要增加 Filter 的記錄

基于物體的 Filter: Func<EntityEntry, bool>

基于屬性的 Filter: Func<EntityEntry, PropertyEntry, bool>

為了使用方便定義了一些擴展方法：


public static IAuditConfigBuilder IgnoreEntity(this IAuditConfigBuilder configBuilder, Type entityType)
{
    configBuilder.WithEntityFilter(entityEntry => entityEntry.Entity.GetType() != entityType);
    return configBuilder;
}

public static IAuditConfigBuilder IgnoreEntity<TEntity>(this IAuditConfigBuilder configBuilder) where TEntity : class
{
    configBuilder.WithEntityFilter(entityEntry => entityEntry.Entity.GetType() != typeof(TEntity));
    return configBuilder;
}

public static IAuditConfigBuilder IgnoreTable(this IAuditConfigBuilder configBuilder, string tableName)
{
    configBuilder.WithEntityFilter(entityEntry => entityEntry.Metadata.GetTableName() != tableName);
    return configBuilder;
}

public static IAuditConfigBuilder WithEntityFilter(this IAuditConfigBuilder configBuilder, Func<EntityEntry, bool> filterFunc)
{
    configBuilder.WithEntityFilter(filterFunc);
    return configBuilder;
}

public static IAuditConfigBuilder IgnoreProperty<TEntity>(this IAuditConfigBuilder configBuilder, Expression<Func<TEntity, object>> propertyExpression) where TEntity : class
{
    var propertyName = propertyExpression.GetMemberName();
    configBuilder.WithPropertyFilter(propertyEntry => propertyEntry.Metadata.Name != propertyName);
    return configBuilder;
}

public static IAuditConfigBuilder IgnoreProperty(this IAuditConfigBuilder configBuilder, string propertyName)
{
    configBuilder.WithPropertyFilter(propertyEntry => propertyEntry.Metadata.Name != propertyName);
    return configBuilder;
}

public static IAuditConfigBuilder IgnoreColumn(this IAuditConfigBuilder configBuilder, string columnName)
{
    configBuilder.WithPropertyFilter(propertyEntry => propertyEntry.Metadata.GetColumnName() != columnName);
    return configBuilder;
}

public static IAuditConfigBuilder IgnoreColumn(this IAuditConfigBuilder configBuilder, string tableName, string columnName)
{
    configBuilder.WithPropertyFilter((entityEntry, propertyEntry) => entityEntry.Metadata.GetTableName() != tableName
                                     && propertyEntry.Metadata.GetColumnName() != columnName);
    return configBuilder;
}

public static IAuditConfigBuilder WithPropertyFilter(this IAuditConfigBuilder configBuilder, Func<PropertyEntry, bool> filterFunc)
{
    configBuilder.WithPropertyFilter((entity, prop) => filterFunc.Invoke(prop));
    return configBuilder;
}

IAuditPropertyEnricher

上面由提到有時候我們希望審計記錄能夠記錄更多的資訊，需要提供給用戶一些自定義的擴展點，這里的 Enricher 的實作參考了 Serilog 里的做法，我們可以自定義一個 IAuditPropertyEnricher ，來豐富審計的資訊，默認提供了 AuditPropertyEnricher，可以支持 key-value 形式的補充資訊，實作如下：

public class AuditPropertyEnricher : IAuditPropertyEnricher
{
    private readonly string _propertyName;
    private readonly Func<AuditEntry, object> _propertyValueFactory;
    private readonly bool _overwrite;
    private readonly Func<AuditEntry, bool> _auditPropertyPredict = null;

    public AuditPropertyEnricher(string propertyName, object propertyValue, bool overwrite = false)
        : this(propertyName, (auditEntry) => propertyValue, overwrite)
        {
        }

    public AuditPropertyEnricher(string propertyName, Func<AuditEntry, object> propertyValueFactory, bool overwrite = false)
        : this(propertyName, propertyValueFactory, null, overwrite)
        {
        }

    public AuditPropertyEnricher(
        string propertyName,
        Func<AuditEntry, object> propertyValueFactory,
        Func<AuditEntry, bool> auditPropertyPredict,
        bool overwrite = false)
    {
        _propertyName = propertyName;
        _propertyValueFactory = propertyValueFactory;
        _auditPropertyPredict = auditPropertyPredict;
        _overwrite = overwrite;
    }

    public void Enrich(AuditEntry auditEntry)
    {
        if (_auditPropertyPredict?.Invoke(auditEntry) != false)
        {
            auditEntry.WithProperty(_propertyName, _propertyValueFactory, _overwrite);
        }
    }
}

為了方便使用，提供了一些方便的擴展方法：


public static IAuditConfigBuilder EnrichWithProperty(this IAuditConfigBuilder configBuilder, string propertyName, object value, bool overwrite = false)
{
    configBuilder.WithEnricher(new AuditPropertyEnricher(propertyName, value, overwrite));
    return configBuilder;
}

public static IAuditConfigBuilder EnrichWithProperty(this IAuditConfigBuilder configBuilder, string propertyName, Func<AuditEntry> valueFactory, bool overwrite = false)
{
    configBuilder.WithEnricher(new AuditPropertyEnricher(propertyName, valueFactory, overwrite));
    return configBuilder;
}

public static IAuditConfigBuilder EnrichWithProperty(this IAuditConfigBuilder configBuilder, string propertyName, object value, Func<AuditEntry, bool> predict, bool overwrite = false)
{
    configBuilder.WithEnricher(new AuditPropertyEnricher(propertyName, e => value, predict, overwrite));
    return configBuilder;
}

public static IAuditConfigBuilder EnrichWithProperty(this IAuditConfigBuilder configBuilder, string propertyName, Func<AuditEntry, object> valueFactory, Func<AuditEntry, bool> predict, bool overwrite = false)
{
    configBuilder.WithEnricher(new AuditPropertyEnricher(propertyName, valueFactory, predict, overwrite));
    return configBuilder;
}

IAuditStore

之前的測驗都是基于資料庫來的，審計記錄也是放在資料庫里的，有時候可能不希望和原始資料存在一個資料庫里，有時候甚至希望不放在資料庫里，為了實作可以自定義的存盤，提供了一個 IAuditStore 的介面，提供給用戶可以自定義審計資訊存盤的可能，

public interface IAuditStore
{
    Task Save(ICollection<AuditEntry> auditEntries);
}

使用

`DbContext` 配置

默認提供了一個 AuditDbContextBase 和 AuditDbContext，他們的區別在于 AuditDbContext 會創建一張 AuditRecords 表，記錄審計資訊，AuditDbContextBase 則不會，只會寫配置的存盤，

如果希望提供自動審計的功能，新建 DbContext 的時候需要繼承 AuditDbContext 或 AuditDbContextBase

審計配置

AuditConfig.Configure(builder =>
{
    builder
        // 配置操作用戶獲取方式
        .WithUserIdProvider(EnvironmentAuditUserIdProvider.Instance.Value)
        //.WithUnModifiedProperty() // 保存未修改的屬性,默認只保存發生修改的屬性
        // 保存更多屬性
        .EnrichWithProperty("MachineName", Environment.MachineName)
        .EnrichWithProperty(nameof(ApplicationHelper.ApplicationName), ApplicationHelper.ApplicationName)
        // 保存到自定義的存盤
        .WithStore<AuditFileStore>()
        .WithStore<AuditFileStore>("logs0.txt")
        // 忽略指定物體
        .IgnoreEntity<AuditRecord>()
        // 忽略指定物體的某個屬性
        .IgnoreProperty<TestEntity>(t => t.CreatedAt)
        // 忽略所有屬性名稱為 CreatedAt 的屬性
        .IgnoreProperty("CreatedAt")
        ;
});

如果希望暫時禁用審計可以使用 AuditConfig.DisableAudit() 來禁用，之后恢復可以使用 AuditConfig.EnableAudit()

// disable audit
AuditConfig.DisableAudit();
// enable audit
// AuditConfig.EnableAudit();

暫時想到的特性只有這些了，想要更多新特性？歡迎 Issue & PR

專案地址：https://github.com/WeihanLi/WeihanLi.EntityFramework

Reference

https://www.meziantou.net/entity-framework-core-history-audit-table.htm
https://github.com/WeihanLi/WeihanLi.EntityFramework

轉載請註明出處，本文鏈接：https://www.uj5u.com/net/49234.html

標籤：.NET Core

上一篇：ASP.NET Core MVC通過IViewLocationExpander擴展視圖搜索路徑

下一篇：abp(net core)+easyui+efcore實作倉儲管理系統——入庫管理之七(四十三)

EF Core 資料變更自動審計設計

EF Core 資料變更自動審計設計

Intro

使用效果

實作原理

實作代碼

擴展設計

UserIdProvider

Filters

IAuditPropertyEnricher

IAuditStore

使用

DbContext 配置

審計配置

More

Reference

`DbContext` 配置