‫هنر استثناهای سفارشی در توسعه نرم‌افزار با NET.: رویکردی بر پایه طراحی دامنه محور (DDD)

• اعتبارسنجی دامنه (Domain Validation): این نوع اعتبارسنجی قلب تپنده برنامه شماست. هدف آن حصول اطمینان از این است که موجودیت‌ها (Entities) و اشیاء مقدار (Value Objects) شما همیشه و در هر شرایطی در یک وضعیت معتبر باقی بمانند. این قوانین، همان قواعد ذاتی کسب‌وکار (Business Invariants) هستند که هرگز نباید نقض شوند.
• اعتبارسنجی برنامه (Application Validation): این لایه اولین خط دفاعی شماست. وظیفه آن اعتبارسنجی ورودی‌های کاربر (مانند DTOها و Commandها) قبل از رسیدن به منطق اصلی دامنه است. این اعتبارسنجی بیشتر بر روی فرمت داده‌ها، الزامی بودن فیلدها و موارد این‌چنینی تمرکز دارد.

• کپسوله‌سازی قوانین ذاتی (Encapsulate Business Invariants): موجودیت‌ها و اشیاء مقدار باید خودشان مسئول حفظ اعتبارشان باشند. این کار از طریق سازنده‌ها (Constructors) یا متدهای کارخانه‌ای (Factory Methods) انجام می‌شود. اصل مهم این است: ایجاد یک شیء در وضعیت نامعتبر باید غیرممکن باشد.
• استفاده از الگوهای مشخص: برای بررسی‌های ساده و پرتکرار از Guard Clauseها استفاده کنید. برای قوانین پیچیده‌تر که ممکن است بین چند موجودیت مشترک باشند یا نیاز به ترکیب داشته باشند، الگوی Specification یک راه‌حل عالی است.
• بازگرداندن نتایج صریح (Explicit Results): به جای پرتاب استثناهای عمومی (Generic Exceptions) برای خطاهای قابل پیش‌بینی (مانند نامعتبر بودن ورودی)، از الگوی Result استفاده کنید. این الگو به وضوح نشان می‌دهد که یک عملیات می‌تواند موفق یا ناموفق باشد و کد را خواناتر می‌کند. استثناها را برای شرایط واقعاً استثنایی و غیرمنتظره نگه دارید.
• پرهیز از مدل‌های کم‌خون (Anemic Models): بزرگترین آفت در DDD، مدل‌های دامنه کم‌خون هستند؛ کلاس‌هایی که فقط شامل داده (Properties) هستند و هیچ رفتار یا منطقی ندارند. موجودیت‌های شما باید زنده باشند و علاوه بر داده، رفتارها و منطق اعتبارسنجی را نیز در خود جای دهند.

// Domain/Common/Guard.cs
namespace Domain.Common;

// یک استثنای سفارشی برای خطاهای اعتبارسنجی دامنه
public class DomainValidationException : Exception
{
    public DomainValidationException(string message) : base(message) { }
}

public static class Guard
{
    public static void AgainstNullOrEmpty(string value, string parameterName)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new DomainValidationException($"{parameterName} نمی‌تواند خالی باشد.");
    }

    public static void AgainstNegative(decimal value, string parameterName)
    {
        if (value < 0)
            throw new DomainValidationException($"{parameterName} نمی‌تواند مقداری منفی داشته باشد.");
    }

    public static void AgainstZeroOrNegative(int value, string parameterName)
    {
        if (value <= 0)
            throw new DomainValidationException($"{parameterName} باید مقداری بزرگتر از صفر داشته باشد.");
    }
}

// Domain/ValueObjects/Money.cs
using Domain.Common;

namespace Domain.ValueObjects;

// استفاده از record برای تعریف یک شیء مقدار تغییرناپذیر (Immutable)
public record Money
{
    public decimal Amount { get; }
    public string Currency { get; }

    // سازنده را private می‌کنیم تا کسی نتواند شیء را در وضعیت نامعتبر بسازد
    private Money(decimal amount, string currency)
    {
        Amount = amount;
        Currency = currency;
    }

    // از یک متد کارخانه‌ای استاتیک برای ساخت شیء استفاده می‌کنیم
    public static Money Create(decimal amount, string currency)
    {
        // اعمال قوانین با Guard Clause ها
        Guard.AgainstNegative(amount, nameof(amount));
        Guard.AgainstNullOrEmpty(currency, nameof(currency));
        
        // می‌توانیم قوانین پیچیده‌تری هم اضافه کنیم
        if (currency.Length != 3)
            throw new DomainValidationException("کد ارز باید ۳ حرفی باشد.");

        return new Money(amount, currency);
    }
}

// Domain/Entities/Order.cs
using Domain.Common;
using Domain.ValueObjects;

public class Order : Entity // فرض می‌کنیم Entity یک کلاس پایه با یک شناسه (Id) است
{
    public CustomerId CustomerId { get; private set; }
    public DateTime OrderDate { get; private set; }
    public OrderStatus Status { get; private set; }

    private readonly List<OrderItem> _items = [];
    public IReadOnlyList<OrderItem> Items => _items.AsReadOnly();

    // سازنده بدون پارامتر برای استفاده EF Core
    // این سازنده باید private یا protected باشد تا از بیرون فراخوانی نشود
    private Order() { }

    public static Order Create(CustomerId customerId, DateTime orderDate)
    {
        // بررسی قوانین ذاتی کسب‌وکار
        if (orderDate > DateTime.UtcNow)
            throw new DomainValidationException("تاریخ سفارش نمی‌تواند در آینده باشد.");

        var order = new Order
        {
            Id = Guid.NewGuid(),
            CustomerId = customerId,
            OrderDate = orderDate,
            Status = OrderStatus.Pending
        };

        return order;
    }

    // مثال دیگری از منطق تجاری درون موجودیت
    public void AddItem(ProductId productId, int quantity, Money price)
    {
        // یک قانون: نمی‌توان به سفارشی که نهایی شده، آیتم اضافه کرد
        if (Status == OrderStatus.Confirmed || Status == OrderStatus.Shipped)
            throw new DomainValidationException("امکان افزودن آیتم به سفارش نهایی‌شده وجود ندارد.");
            
        Guard.AgainstZeroOrNegative(quantity, nameof(quantity));

        var existingItem = _items.FirstOrDefault(i => i.ProductId == productId);
        if (existingItem != null)
        {
            // اگر آیتم قبلاً وجود داشته، تعدادش را افزایش بده
            existingItem.AddQuantity(quantity);
        }
        else
        {
            _items.Add(OrderItem.Create(this.Id, productId, quantity, price));
        }
    }
}

// Domain/Specifications/ISpecification.cs
namespace Domain.Specifications;

public interface ISpecification<T>
{
    bool IsSatisfiedBy(T entity);
    string ErrorMessage { get; }
}

// Domain/Specifications/OrderMustHaveItemsSpec.cs
using Domain.Entities;

public class OrderMustHaveItemsSpec : ISpecification<Order>
{
    public string ErrorMessage => "سفارش برای تایید شدن باید حداقل یک آیتم داشته باشد.";

    public bool IsSatisfiedBy(Order order) => order.Items.Any();
}

// بخشی از کلاس Order
public void Confirm()
{
    var spec = new OrderMustHaveItemsSpec();
    if (!spec.IsSatisfiedBy(this))
    {
        throw new DomainValidationException(spec.ErrorMessage);
    }

    // قانون دیگر: فقط سفارش در حالت Pending می‌تواند تایید شود
    if (Status != OrderStatus.Pending)
    {
        throw new DomainValidationException("سفارش در وضعیت فعلی قابل تایید نیست.");
    }
    
    Status = OrderStatus.Confirmed;
    // رویداد دامنه (Domain Event) را منتشر کن (اختیاری)
    // AddDomainEvent(new OrderConfirmedEvent(this.Id));
}

// Domain/Common/Result.cs
namespace Domain.Common;

public class Result
{
    public bool IsSuccess { get; }
    public bool IsFailure => !IsSuccess;
    public string? Error { get; }

    protected Result(bool success, string? error)
    {
        IsSuccess = success;
        Error = error;
    }

    public static Result Success() => new(true, null);
    public static Result Failure(string error) => new(false, error);
    
    public static Result<T> Success<T>(T value) => Result<T>.Success(value);
    public static Result<T> Failure<T>(string error) => Result<T>.Failure(error);
}


public class Result<T> : Result
{
    public T? Value { get; }

    protected internal Result(bool success, T? value, string? error) : base(success, error)
    {
        Value = value;
    }

    public static Result<T> Success(T value) => new(true, value, null);
    public static new Result<T> Failure(string error) => new(false, default, error);
}

// بازنویسی متد Create در کلاس Order
public static Result<Order> Create(CustomerId customerId, DateTime orderDate)
{
    if (orderDate > DateTime.UtcNow)
        return Result.Failure<Order>("تاریخ سفارش نمی‌تواند در آینده باشد.");

    var order = new Order { /* ... تخصیص مقادیر ... */ };
    return Result.Success(order);
}

// بازنویسی متد Confirm در کلاس Order
public Result Confirm()
{
    var spec = new OrderMustHaveItemsSpec();
    if (!spec.IsSatisfiedBy(this))
        return Result.Failure(spec.ErrorMessage);

    if (Status != OrderStatus.Pending)
        return Result.Failure("سفارش در وضعیت فعلی قابل تایید نیست.");
    
    Status = OrderStatus.Confirmed;
    return Result.Success();
}

// در لایه Application
var createResult = Order.Create(customerId, DateTime.UtcNow);

if (createResult.IsFailure)
{
    return BadRequest(createResult.Error); // یا هر پاسخ خطای دیگری
}

var order = createResult.Value;
order.AddItem(...);

var confirmResult = order.Confirm();
if (confirmResult.IsFailure)
{
    return BadRequest(confirmResult.Error);
}

_orderRepository.Update(order);
await _unitOfWork.SaveChangesAsync();

// Application/Orders/Commands/CreateOrder/CreateOrderCommandValidator.cs
using FluentValidation;

public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId)
            .NotEmpty().WithMessage("شناسه مشتری الزامی است.");

        RuleFor(x => x.Items)
            .NotEmpty().WithMessage("سفارش باید حداقل شامل یک آیتم باشد.");

        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(i => i.Quantity)
                .GreaterThan(0).WithMessage("تعداد محصول باید بیشتر از صفر باشد.");
            item.RuleFor(i => i.Price)
                .GreaterThan(0).WithMessage("قیمت محصول باید بیشتر از صفر باشد.");
        });
    }
}

• Application Validation (Fail Fast): برای ارائه بازخورد سریع به کاربر و جلوگیری از ارسال درخواست‌های نامعتبر به هسته سیستم.
• Domain Validation (Always Valid): برای تضمین اینکه قوانین اصلی کسب‌وکار تحت هیچ شرایطی (چه از طریق API، چه یک background job یا تست واحد) نقض نمی‌شوند. لایه دامنه شما نباید به لایه Application اعتماد کند.

// Tests/Domain/OrderTests.cs
using Domain.Entities;
using FluentAssertions;
using Xunit;

public class OrderTests
{
    [Fact]
    public void Create_WhenOrderDateIsInFuture_ShouldReturnFailure()
    {
        // Arrange
        var futureDate = DateTime.UtcNow.AddDays(1);
        var customerId = new CustomerId(Guid.NewGuid());

        // Act
        var result = Order.Create(customerId, futureDate);

        // Assert
        result.IsFailure.Should().BeTrue();
        result.Error.Should().Be("تاریخ سفارش نمی‌تواند در آینده باشد.");
    }

    [Fact]
    public void Confirm_WhenOrderHasNoItems_ShouldReturnFailure()
    {
        // Arrange
        var orderResult = Order.Create(new CustomerId(Guid.NewGuid()), DateTime.UtcNow);
        var order = orderResult.Value;

        // Act
        var confirmResult = order.Confirm();

        // Assert
        confirmResult.IsFailure.Should().BeTrue();
        confirmResult.Error.Should().Contain("حداقل یک آیتم");
    }

    [Fact]
    public void AddItem_ToConfirmedOrder_ShouldThrowException()
    {
        // Arrange
        var orderResult = Order.Create(new CustomerId(Guid.NewGuid()), DateTime.UtcNow);
        var order = orderResult.Value;
        order.AddItem(new ProductId(Guid.NewGuid()), 1, Money.Create(100, "USD"));
        order.Confirm();

        // Act
        Action action = () => order.AddItem(new ProductId(Guid.NewGuid()), 1, Money.Create(50, "USD"));

        // Assert
        action.Should().Throw<DomainValidationException>()
            .WithMessage("امکان افزودن آیتم به سفارش نهایی‌شده وجود ندارد.");
    }
}

• قوانین ذاتی را در دامنه متمرکز کنید: منطق کسب‌وکار شما باید در قلب سیستم، یعنی لایه دامنه، محافظت شود.
• از ابزار مناسب استفاده کنید:Guard Clause برای بررسی‌های ساده و Specification برای قوانین پیچیده.
• نتایج را صریح برگردانید: از الگوی Result برای خطاهای قابل پیش‌بینی کسب‌وکار استفاده کنید و استثناها را برای شرایط واقعاً استثنایی نگه دارید.
• دامنه را پاک نگه دارید: لایه دامنه شما نباید هیچ وابستگی به فریمورک‌های لایه Application (مانند FluentValidation یا ASP.NET Core) داشته باشد.
• ورودی‌ها را در لایه Application اعتبارسنجی کنید: از DTOها و Commandها در همان ابتدای خط لوله درخواست (Request Pipeline) محافظت کنید.
• برای قوانین دامنه تست بنویسید: این تست‌ها تضمین می‌کنند که منطق اصلی کسب‌وکار شما با تغییر کد همچنان معتبر باقی می‌ماند.