‫مدیریت دغدغه‌های عرضی در Entity Framework Core با استفاده از Interceptorها

چکیده: در توسعه سامانه‌های مبتنی بر دات‌نت (NET Framework / .NET Core.)، یکپارچه‌سازی و پیاده‌سازی متمرکز منطق‌های زیرساختی و عرضی (Cross-Cutting Concerns) از اهمیت بالایی برخوردار است. تکرار کدهایی نظیر ثبت تاریخچه تغییرات (Audit Logging)، حذف نرم (Soft Delete) و درج پیام‌های الگوی Outbox در دستورات مختلف، علاوه بر افزایش خطای انسانی و نگهداری‌پذیری پایین، منجر به آلودگی کدهای حوزه کسب‌وکار (Domain Logic) می‌شود. قابلیت Interceptor در Entity Framework Core (به‌اختصار EF Core) ابزاری قدرتمند جهت فراتابی (Interception) و دستکاری عملیات پایگاه‌داده به صورت خودکار فراهم می‌سازد. این مقاله با بررسی ساختار SaveChangesInterceptor و پیاده‌سازی متمرکز الگوی Outbox، نشان می‌دهد که چگونه می‌توان با جداسازی کامل دغدغه‌های زیرساختی، کد بدنه برنامه را ساده، امن و عاری از پیچیدگی غیرضروری نگه داشت.

• حذف نرم (Soft Delete): تغییر حالت وضعیت داده به جای حذف فیزیکی آن از پایگاه‌داده.
• ثبت ردپا (Audit Trail): ثبت زمان تغییر، شناسه کاربر ایجادکننده یا ویرایش‌کننده.
• الگوی Outbox: ذخیره رویدادهای دامنه (Domain Events) در یک جدول واسط جهت ارسال مطمئن به پیام‌رسان‌ها (Message Brokers).

[ Domain Handler ] ──> context.SaveChangesAsync()
                               │
                               ▼
                   ┌───────────────────────┐
                   │   OutboxInterceptor   │ ──> (Inspect ChangeTracker & Insert Outbox Messages)
                   └───────────────────────┘
                               │
                               ▼
                   [ Execute DB Transaction ]

• تک‌مسئولیتی و تفکیک (Modularization): به جای انباشتن خطوط متعدد کد در DbContext اصلی، هر دغدغه زیرساختی (Outbox، Auditing و ...) در یک کلاس کاملاً مستقل و تست‌پذیر پیاده‌سازی می‌شود.
• قابلیت ترکیب (Composability): امکان تزریق و پیکربندی چندین Interceptor به‌صورت هم‌زمان و تعیین زنجیره اجرای آن‌ها وجود دارد.

public async Task Handle(DeleteUserCommand command, CancellationToken ct)
{
    var user = await _context.Users.FindAsync(command.Id, ct);
    user.Delete();

    var domainEvent = new UserDeletedEvent(user.Id);
    var outboxMessage = new OutboxMessage
    {
        Id = Guid.NewGuid(),
        Type = domainEvent.GetType().AssemblyQualifiedName!,
        Payload = JsonSerializer.Serialize(domainEvent, domainEvent.GetType()),
        CreatedAt = DateTime.UtcNow
    };

    _context.Set<OutboxMessage>().Add(outboxMessage);
    await _context.SaveChangesAsync(ct);
}

public interface IDomainEvent { }

public abstract class Entity
{
    private readonly List<IDomainEvent> _domainEvents = new();
    
    public IReadOnlyList<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();

    protected void Raise(IDomainEvent domainEvent) => _domainEvents.Add(domainEvent);

    public void ClearDomainEvents() => _domainEvents.Clear();
}

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

public class OutboxInterceptor : SaveChangesInterceptor
{
    public override ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Context is null)
            return base.SavingChangesAsync(eventData, result, cancellationToken);

        var context = eventData.Context;

        // ۱. استخراج تمامی رویدادهای موجودیت‌های متصل به ChangeTracker
        var domainEvents = context.ChangeTracker
            .Entries<Entity>()
            .Select(entry => entry.Entity)
            .SelectMany(entity =>
            {
                var events = entity.DomainEvents.ToList();
                entity.ClearDomainEvents(); // پاک‌سازی جهت جلوگیری از پردازش تکراری
                return events;
            })
            .ToList();

        // ۲. تبدیل رویدادها به پیام‌های Outbox
        var outboxMessages = domainEvents.Select(domainEvent => new OutboxMessage
        {
            Id = Guid.NewGuid(),
            Type = domainEvent.GetType().AssemblyQualifiedName!,
            Payload = JsonSerializer.Serialize(domainEvent, domainEvent.GetType()),
            CreatedAt = DateTime.UtcNow
        }).ToList();

        // ۳. افزودن پیام‌ها به پایگاه‌داده در همان تراکنش
        if (outboxMessages.Count > 0)
        {
            context.Set<OutboxMessage>().AddRange(outboxMessages);
        }

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

public async Task Handle(DeleteUserCommand command, CancellationToken ct)
{
    var user = await _context.Users.FindAsync(command.Id, ct);
    user.Delete(); // متد Delete درون خود یک UserDeletedEvent ثبت می‌کند
    
    await _context.SaveChangesAsync(ct);
}

قاعده طلایی:

اگر مجبور هستید عملکرد یا علت اجرای یک کد درون Interceptor را برای مدیر محصول (Product Manager) توضیح دهید، آن کد متعلق به Interceptor نیست و باید درون Domain / Application Handler قرار گیرد.

• هنگام ثبت Interceptor در DI Container، اگر Interceptor شما نیازمند وابستگی‌هایی با طول عمر Scoped است (مانند دریافت اطلاعات کاربر جاری از IHttpContextAccessor)، باید Interceptor نیز به‌صورت Scoped ثبت شده و یا از طریق IServiceProvider به Context اضافه شود:

services.AddScoped<OutboxInterceptor>();
services.AddDbContext<ApplicationDbContext>((sp, options) =>
{
    var interceptor = sp.GetRequiredService<OutboxInterceptor>();
    options.UseSqlServer(connectionString)
           .AddInterceptors(interceptor);
});

• در صورت استفاده از چند Interceptor همزمان (مثلاً یکی برای Audit Logging و دیگری برای Outbox)، ترتیب ثبت آن‌ها در AddInterceptors اهمیت دارد. فرآیندهایی که موجودیت‌ها را تغییر می‌دهند (مانند Soft Delete) باید قبل از Interceptor ثبت Outbox اجرا شوند تا رویدادهای تولیدشده احتمالی نیز توسط Outbox دریافت گردند.

• پس از ثبت پیام‌ها در جدول Outbox توسط Interceptor، ابزارهایی نظیر Wolverine یا MassTransit یا کارهای پس‌زمینه (IHostedService) می‌توانند پیام‌ها را خوانده و با تضمین حداقل یک‌بار تحویل (At-least-once delivery) پردازش کنند.