ردپای تغییرات (Audit Trail) با Interceptor در EF Core: چه کسی، چه چیزی را، کی تغییر داد

پاسخ کوتاه: موجودیت‌های حساس را با یک interface به نام IAudited علامت بزنید و یک SaveChangesInterceptor اضافه کنید که درست قبل از ذخیره، برای هر موجودیت اضافه، ویرایش یا حذف‌شده یک ردیف AuditEntry بنویسد: propertyهای تغییرکرده با مقدار قبلی و جدید، کاربر، زمان و شناسه همبستگی. چون در همان SaveChanges اضافه می‌شود، ردیف audit همراه با خود تغییر commit یا rollback می‌شود.

یک مثال واقعی: حق بیمه‌ای که خودش عوض شد

مشتری شکایت می‌کند که حق بیمه‌اش بین دو صورت‌حساب بالا رفته. جدول Policies فقط مقدار فعلی را نشان می‌دهد. job قیمت‌گذاری بود، کارشناس پنل یا یک باگ؟ سه تیم یک روز وقت می‌گذارند تا بک‌آپ‌ها را مقایسه کنند.

با audit trail یک کوئری جواب می‌دهد: حق بیمه سه‌شنبه ساعت ۱۰:۴۲ از ۱۸٬۴۰۰٬۰۰۰ به ۲۱٬۱۰۰٬۰۰۰ ریال تغییر کرد، توسط کاربر ops.ahmadi، در درخواست 3b9e.... گفت‌وگو از «چه شد؟» به «درست بود؟» می‌رسد؛ سؤالی که واقعاً مهم است.

کد قابل اجرا

جدول audit:

public interface IAudited { }

public sealed class AuditEntry
{
    public long Id { get; set; }
    public string Entity { get; set; } = "";
    public string EntityId { get; set; } = "";
    public string Action { get; set; } = "";      // Added, Modified, Deleted
    public string Changes { get; set; } = "";     // JSON: { "Status": { "Old": 1, "New": 2 } }
    public string? UserId { get; set; }
    public string? CorrelationId { get; set; }
    public DateTimeOffset AtUtc { get; set; }
}

Interceptor:

using System.Diagnostics;
using System.Text.Json;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.ChangeTracking;
using Microsoft.EntityFrameworkCore.Diagnostics;

public sealed class AuditInterceptor(ICurrentUser user, TimeProvider clock) : SaveChangesInterceptor
{
    public override ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Context is AppDbContext db)
            AddAuditEntries(db);

        return base.SavingChangesAsync(eventData, result, cancellationToken);
    }

    private void AddAuditEntries(AppDbContext db)
    {
        var now = clock.GetUtcNow();
        var changed = db.ChangeTracker.Entries()
            .Where(e => e.Entity is IAudited &&
                        e.State is EntityState.Added or EntityState.Modified or EntityState.Deleted)
            .ToList(); // materialise before adding AuditEntry rows

        foreach (var entry in changed)
        {
            db.AuditEntries.Add(new AuditEntry
            {
                Entity = entry.Metadata.ClrType.Name,
                EntityId = KeyOf(entry),
                Action = entry.State.ToString(),
                Changes = JsonSerializer.Serialize(ChangesOf(entry)),
                UserId = user.Id,
                CorrelationId = Activity.Current?.TraceId.ToString(),
                AtUtc = now,
            });
        }
    }

    private static string KeyOf(EntityEntry entry) => string.Join(",",
        entry.Properties.Where(p => p.Metadata.IsPrimaryKey()).Select(p => p.CurrentValue));

    private static Dictionary<string, object?> ChangesOf(EntityEntry entry) => entry.Properties
        .Where(p => entry.State != EntityState.Modified || p.IsModified)
        .ToDictionary(
            p => p.Metadata.Name,
            p => (object?)new
            {
                Old = entry.State == EntityState.Added ? null : p.OriginalValue,
                New = entry.State == EntityState.Deleted ? null : p.CurrentValue,
            });
}

ثبت در DI:

builder.Services.AddSingleton(TimeProvider.System);
builder.Services.AddScoped<ICurrentUser, HttpCurrentUser>();
builder.Services.AddScoped<AuditInterceptor>();

builder.Services.AddDbContext<AppDbContext>((sp, o) => o
    .UseSqlServer(builder.Configuration.GetConnectionString("Default"))
    .AddInterceptors(sp.GetRequiredService<AuditInterceptor>()));

حالا فقط کافی است بنویسید public class Policy : IAudited تا آن موجودیت audit شود.

نکات عملی

  • همان تراکنش، عمداً. ردیف‌های audit قبل از ذخیره اضافه می‌شوند؛ پس ذخیره ناموفق ردیف audit ندارد و ذخیره موفق همیشه دارد.
  • کلیدهای تولیدی. برای ردیف جدید با کلید identity، شناسه در این لحظه موقت است. برای موجودیت‌های audit‌شده کلید Guid.CreateVersion7() را ترجیح دهید یا کلید را در SavedChangesAsync بنویسید.
  • عملیات گروهی از آن رد می‌شوند. ExecuteUpdate و ExecuteDelete و SQL خام از change tracker نمی‌گذرند. آن مسیرها را صریحاً audit کنید یا روی جدول‌های audit‌شده استفاده‌شان نکنید.
  • چیزی را که باید، ماسک کنید. کد ملی کامل، شماره کارت یا توکن را در Changes ذخیره نکنید؛ آن propertyها را حذف یا ماسک کنید.
  • از جدول محافظت کنید. به کاربر دیتابیس اپلیکیشن روی AuditEntries فقط مجوز INSERT و SELECT بدهید تا ردپا توسط همان کدی که ثبتش می‌کند قابل ویرایش نباشد.

مزایا و معایب

مزایا

  • «چه کسی، چه چیزی، کی» با یک کوئری جواب داده می‌شود؛ برای پشتیبانی، انطباق با مقررات و دیباگ.
  • هیچ تغییری در کد کسب‌وکار لازم نیست: یک interface روی هر موجودیت.
  • اتمیک با خود تغییر؛ ردپا هیچ‌وقت جلوتر یا عقب‌تر از داده نیست.

معایب

  • آپدیت‌های گروهی و SQL خام را نمی‌بیند.
  • روی موجودیت‌های پرتغییر جدول سریع بزرگ می‌شود؛ برای نگهداری و آرشیو برنامه داشته باشید.
  • گزارش‌گیری از JSON سخت‌تر از ستون‌های تایپ‌دار است؛ برای تاریخچه نقطه‌به‌نقطه temporal table بهتر است.

به audit trail‌ای نیاز دارید که از بازرسی انطباق سربلند بیرون بیاید؟ ببینید چطور می‌توانم کمک کنم.

پرسش‌های متداول

چرا به‌جایش از temporal tableهای SQL Server استفاده نکنم؟

temporal table برای «این ردیف در تاریخ X چه شکلی بود» عالی است و کد اپلیکیشن لازم ندارد. ولی ثبت نمی‌کند چه کسی و چرا تغییر داد، مگر خودتان ستونش را اضافه کنید. خیلی از تیم‌ها هر دو را دارند: temporal table برای تاریخچه و جدول audit برای زمینه کاربر و درخواست.

جدول audit نوشتن را کند نمی‌کند؟

کمی: هر ذخیره audit‌شده در همان تراکنش ردیف‌های اضافه درج می‌کند. برای موجودیت‌های معمول کسب‌وکار ناچیز است. جدول‌های فنی پرحجم مثل لاگ یا outbox را audit نکنید و جدول audit را فقط‌درج با کلید clustered روی Id نگه دارید.

موجودیت‌هایی که شناسه‌شان را دیتابیس می‌سازد چه می‌شوند؟

برای موجودیت جدید با کلید identity، شناسه در SavingChanges هنوز موقت است. یا از کلید ساخته‌شده در کلاینت مثل Guid.CreateVersion7() استفاده کنید، یا کلید را بعد از درج در SavedChangesAsync ثبت کنید، به قیمت یک ذخیره دوم.