معماری Clean Architecture در دات‌نت ۸: پیاده‌سازی عملی و مزایای تست‌نویسی

پیاده‌سازی عملی در دات‌نت ۸: از ساختار پوشه‌ها تا کدنویسی

حالا که با تئوری و لایه‌ها آشنا شدیم، وقت آن است که آستین‌هایمان را بالا بزنیم و ببینیم این ساختار در محیط Visual Studio یا VS Code چگونه پیاده می‌شود. در دات‌نت ۸، بهترین روش برای مدیریت این لایه‌ها، استفاده از یک Solution واحد و چندین پروژه Class Library است. این کار باعث می‌شود که محدودیت‌های دسترسی (Dependency) را در سطح کامپایلر اعمال کنیم و اجازه ندهیم کسی به اشتباه لایه دامین را به لایه زیرساخت متصل کند.

بیایید با ساختار پوشه‌بندی شروع کنیم. یک ساختار استاندارد معمولاً به این شکل است:

• 📁 Src
  • 📁 Domain (Class Library) $\rightarrow$ بدون هیچ وابستگی
  • 📁 Application (Class Library) $\rightarrow$ وابسته به Domain
  • 📁 Infrastructure (Class Library) $\rightarrow$ وابسته به Application و Domain
  • 📁 WebAPI (ASP.NET Core Web API) $\rightarrow$ وابسته به Application و Infrastructure
• 📁 Tests
  • 📁 UnitTests
  • 📁 IntegrationTests

کدنویسی لایه دامین: تعریف موجودیت‌ها و قوانین

در لایه دامین، ما نباید از هیچ ابزار خارجی استفاده کنیم. بیایید یک موجودیت ساده برای "محصول" (Product) تعریف کنیم. نکته کلیدی اینجاست که ما از Encapsulation استفاده می‌کنیم تا از تغییرات غیرمجاز جلوگیری کنیم. به جای اینکه تمام Propertyها را با set عمومی تعریف کنیم، آن‌ها را محدود می‌کنیم.

تصور کنید اگر قیمت محصول را در هر جای برنامه بتوان تغییر داد، چه اتفاقی می‌افتد؟ احتمالاً در آینده با خطاهای عجیب در فاکتورها مواجه می‌شوید. پس منطق تغییر قیمت باید در خودِ موجودیت باشد:

public class Product : BaseEntity
{
    public string Name { get; private set; }
    public decimal Price { get; private set; }
    public int Stock { get; private set; }

    // سازنده برای اجبار به مقداردهی اولیه
    public Product(string name, decimal price, int stock)
    {
        if (string.IsNullOrWhiteSpace(name)) throw new DomainException("نام محصول نمی‌تواند خالی باشد");
        if (price < 0) throw new DomainException("قیمت نمی‌تواند منفی باشد");

        Name = name;
        Price = price;
        Stock = stock;
    }

    // متدی برای تغییر قیمت با رعایت قوانین بیزنس
    public void UpdatePrice(decimal newPrice)
    {
        if (newPrice < 0) throw new DomainException("قیمت جدید نامعتبر است");
        Price = newPrice;
    }
}
    

این یعنی لایه دامین فقط یک مدل ساده نیست، بلکه منطق کسب‌وکار را در خود جای داده است. این همان چیزی است که در الگوهای قدیمی (Anemic Domain Model) فراموش می‌شد و تمام منطق‌ها به متدهای غول‌پیکر در سرویس‌ها منتقل می‌شد.

پیاده‌سازی لایه اپلیکیشن با MediatR و CQRS

حالا می‌خواهیم عملیات "ثبت محصول" را پیاده کنیم. در دات‌نت ۸، استفاده از MediatR به ما اجازه می‌دهد تا وابستگی بین کنترلر و منطق اجرا را کاملاً قطع کنیم. در واقع کنترلر فقط یک "پیام" می‌فرستد و MediatR تصمیم می‌گیرد چه کسی آن پیام را پردازش کند.

ابتدا یک Command تعریف می‌کنیم (یک DTO ساده که داده‌های ورودی را می‌برد):

public record CreateProductCommand(string Name, decimal Price, int Stock) : IRequest<Guid>();
    

سپس Handler را می‌نویسیم. اینجا جایی است که جادوی هماهنگی اتفاق می‌افتد. هندلر لایه اپلیکیشن است، پس نباید بداند دیتابیس چیست، بلکه از اینترفیس IProductRepository استفاده می‌کند:

public class CreateProductHandler : IRequestHandler<CreateProductCommand, Guid>
{
    private readonly IProductRepository _repository;
    private readonly IUnitOfWork _unitOfWork;

    public CreateProductHandler(IProductRepository repository, IUnitOfWork unitOfWork)
    {
        _repository = repository;
        _unitOfWork = unitOfWork;
    }

    public async Task<Guid> Handle(CreateProductCommand request, CancellationToken cancellationToken)
    {
        // تبدیل Command به Entity لایه دامین
        var product = new Product(request.Name, request.Price, request.Stock);

        // ذخیره از طریق ریپوزیتوری (بدون دانستن جزئیات SQL)
        await _repository.AddAsync(product);
        await _unitOfWork.SaveChangesAsync();

        return product.Id;
    }
}
    

بیایید کمی مکث کنیم. آیا متوجه شدید که در کد بالا، هیچ اشاره‌ای به DbContext یا SqlConnection نشد؟ این یعنی اگر فردا بخواهیم دیتابیس را از SQL Server به یک فایل JSON تغییر دهیم، این کد حتی یک تغییر کوچک هم نمی‌خواهد. این یعنی رسیدن به استقلال کامل از ابزارها.

لایه زیرساخت: پیاده‌سازی واقعی قراردادها

حالا نوبت به لایه Infrastructure می‌رسد تا قول‌های داده شده در لایه‌های بالاتر را عملی کند. در اینجا ما IProductRepository را با استفاده از EF Core پیاده می‌کنیم.

public class ProductRepository : IProductRepository
    {
        private readonly ApplicationDbContext _context;
        public ProductRepository(ApplicationDbContext context) => _context = context;

        public async Task AddAsync(Product product) 
        {
            await _context.Products.AddAsync(product);
        }
    }
    

در این لایه، ما تمام پیچیدگی‌های مربوط به کانکشن استرینگ‌ها، تنظیمات Indexهای دیتابیس و بهینه‌سازی‌های کوئری را قرار می‌دهیم. نکته طلایی این است که لایه Presentation هرگز نباید به این کلاس دسترسی مستقیم داشته باشد؛ دسترسی فقط از طریق Dependency Injection در سطح Solution مدیریت می‌شود.

بسیاری از توسعه‌دهندگان در این مرحله دچار اشتباه می‌شوند و DbContext را در لایه اپلیکیشن تزریق می‌کنند. این کار دقیقاً همان چیزی است که Clean Architecture می‌خواهد از آن جلوگیری کند. به یاد داشته باشید: لایه اپلیکیشن فقط با اینترفیس‌ها (قراردادها) صحبت می‌کند، نه با پیاده‌سازی‌های concrete.

جادوی تزریق وابستگی (Dependency Injection) در دات‌نت ۸

اگر لایه‌ها از هم جدا هستند، پس چطور با هم ارتباط برقرار می‌کنند؟ پاسخ در DI Container نهفته است. در فایل Program.cs یا کلاس‌های DependencyInjection.cs در هر لایه، ما تعریف می‌کنیم که کدام اینترفیس توسط کدام کلاس پیاده شود.

مثلاً: services.AddScoped<IProductRepository, ProductRepository>();

این خط ساده، پل ارتباطی بین دنیای انتزاعی (Application) و دنیای واقعی (Infrastructure) است. با این روش، ما می‌توانیم در محیط تست، به جای ProductRepository واقعی، یک کلاس MockProductRepository قرار دهیم که هیچ دیتابیسی ندارد و فقط داده‌های تستی برمی‌گرداند. این دقیقاً همان جایی است که تست‌نویسی از یک کابوس به یک لذت تبدیل می‌شود.

اگر در پیاده‌سازی این زنجیره از وابستگی‌ها با مشکل مواجه شدید یا احساس می‌کنید ساختار پروژه‌تان بیش از حد پیچیده شده، پیشنهاد می‌کنم یک بار دیگر معماری خود را بررسی کنید. گاهی اوقات یک مشورت کوتاه با متخصصین می‌تواند از ماه‌ها بازنویسی کد در آینده جلوگیری کند؛ برای همین است که در بخش پشتیبانی ZiroxAI آماده‌ایم تا در تحلیل ساختار لایه‌بندی پروژه‌های شما کمک کنیم.

استراتژی مدیریت خطاها در معماری پاک

یک سوال رایج این است: "وقتی لایه‌ها جدا هستند، خطای دیتابیس چطور باید به کاربر برسد بدون اینکه جزئیات فنی دیتابیس لو برود؟" در Clean Architecture، ما از Custom Exceptions استفاده می‌کنیم.

در لایه دامین، خطایی به نام DomainException تعریف می‌کنیم. اگر در لایه زیرساخت خطای SQL رخ داد، ما آن را می‌گیریم (Catch می‌کنیم) و به یک خطای معنایی تبدیل می‌کنیم. سپس در لایه Presentation، یک Global Exception Middleware قرار می‌دهیم که تمام این خطاها را می‌گیرد و آن‌ها را به یک فرمت استاندارد (مثل RFC 7807) تبدیل کرده و برای کاربر می‌فرستد.

این یعنی کاربر هرگز پیام "SqlException: Primary Key Violation" را نمی‌بیند، بلکه پیامی ساده و انسانی دریافت می‌کند: "محصولی با این نام قبلاً ثبت شده است". این رویکرد نه تنها تجربه کاربری را بهبود می‌بخشد، بلکه از نظر امنیتی نیز جلوی نشت اطلاعات ساختاری دیتابیس را می‌گیرد.

تست‌نویسی در Clean Architecture: تبدیل ترس به اطمینان

بیایید با یک حقیقت تلخ روبرو شویم: اکثر برنامه‌نویسان از تست‌نویسی متنفرند یا آن را کاری زمان‌بر می‌دانند. دلیل این اتفاق این نیست که آن‌ها تنبل هستند، بلکه به این دلیل است که کدهایشان طوری نوشته شده که تست‌ناپذیر است. وقتی منطق برنامه با دیتابیس و APIهای خارجی گره خورده باشد، برای تست کردن یک متد ساده، باید کل دیتابیس را بالا بیاورید و ده‌ها رکورد تستی بسازید.

اما در Clean Architecture، تست‌نویسی شبیه به لوله‌کشی خانه است که هر لوله را می‌توان جداگانه تست کرد. چون هر لایه مستقل است، ما می‌توانیم از Mocking استفاده کنیم. یعنی به جای استفاده از دیتابیس واقعی، یک "جایگزین مجازی" می‌سازیم که دقیقاً همان رفتار دیتابیس را تقلید می‌کند اما در حافظه (RAM) اجرا می‌شود و سرعتش هزار برابر بیشتر است.

تست‌های واحد (Unit Tests) در هسته دامین

خالص‌ترین نوع تست، تست‌های لایه دامین است. چون این لایه هیچ وابستگی به هیچ چیز ندارد، تست‌های آن فوق‌العاده سریع و قابل اعتماد هستند. ما در اینجا روی قوانین بیزنس تمرکز می‌کنیم. برای مثال، آیا متد UpdatePrice واقعاً جلوی قیمت منفی را می‌گیرد؟

تصور کنید یک تست می‌نویسیم که قیمت محصول را روی -100 قرار می‌دهد. اگر کد ما درست باشد، باید یک DomainException پرتاب شود. این تست‌ها در چند میلی‌ثانیه اجرا می‌شوند و به ما اطمینان می‌دهند که قلب تپنده سیستم ما سالم است.

تست‌های لایه اپلیکیشن با Mocking

در لایه اپلیکیشن، ما با کلاس‌هایی سروکار داریم که به اینترفیس‌ها وابسته هستند. اینجا جایی است که کتابخانه‌هایی مثل Moq یا NSubstitute وارد می‌شوند. ما به جای ارسال درخواست به SQL Server، به MediatR می‌گوییم: "فرض کن وقتی متد AddAsync صدا زده شد، پاسخ موفقیت‌آمیز برگردان".

با این روش، ما می‌توانیم سناریوهای پیچیده را شبیه‌سازی کنیم. مثلاً: "اگر سرویس ارسال ایمیل با خطا مواجه شد، آیا سفارش همچنان در دیتابیس ذخیره می‌شود یا تراکنش (Transaction) لغو می‌گردد؟" پاسخ به این سوال بدون تست‌نویسی، مستلزم آن است که شما واقعاً سرویس ایمیل را از کار بیندازید تا ببینید چه اتفاقی می‌افتد! اما با Clean Architecture، شما این سناریو را در ۵ ثانیه شبیه‌سازی می‌کنید.

چالش‌ها و واقعیت‌های مسیر (آنچه در مقالات نمی‌نویسند)

بیایید صادق باشیم؛ Clean Architecture بدون هزینه نیست. اولین چالشی که با آن مواجه می‌شوید، "تعداد زیاد فایل‌ها" است. برای یک عملیات ساده، شما باید یک Command، یک Handler، یک Interface و یک Repository بسازید. برای کسی که عادت به کدنویسی سریع و تک‌فایلی دارد، این موضوع در ابتدا خسته‌کننده و حتی "اضافه‌کاری" به نظر می‌رسد.

اما بیایید به این موضوع از زاویه دیگری نگاه کنیم. این "تعداد فایل‌ها"، در واقع "نقشه راه" پروژه شماست. هر کسی که برای اولین بار پروژه شما را باز می‌کند، با نگاه به پوشه‌ها دقیقاً می‌فهمد که چه قابلیت‌هایی در سیستم وجود دارد، بدون اینکه نیاز باشد هزاران خط کد را بخواند تا بفهمد منطق ثبت سفارش کجاست.

دومین چالش، منحنی یادگیری است. تیم شما باید با مفاهیمی مثل CQRS، Dependency Inversion و DTOها آشنا شود. اگر تیم شما آماده این تغییر پارادایم نباشد، معماری پاک تبدیل به یک لایه اضافی می‌شود که فقط سرعت کار را می‌گیرد بدون اینکه سودی برساند.

جمع‌بندی و گام‌های نهایی برای شروع

معماری پاک در دات‌نت ۸ بیش از آنکه یک الگوی کدنویسی باشد، یک فلسفه مدیریت پیچیدگی است. این معماری به شما اجازه می‌دهد تا با خیال راحت رشد کنید، ابزارهایتان را عوض کنید و کدهایتان را بدون ترس از شکستن بخش‌های دیگر، تغییر دهید.

اگر می‌خواهید امروز شروع کنید، این نقشه راه ساده را دنبال کنید:

1. ابتدا لایه Domain را بسازید و تمام قوانین بیزنس را در آن متمرکز کنید.
2. لایه Application را با استفاده از MediatR پیاده کنید تا Use Caseها تفکیک شوند.
3. در لایه Infrastructure، فقط پیاده‌سازی‌های فنی (مثل EF Core) را قرار دهید.
4. در نهایت، لایه Presentation را به عنوان یک پوسته‌ی نازک روی سیستم قرار دهید.

در نهایت، به یاد داشته باشید که هیچ معماری "کامل" یا "مقدسی" وجود ندارد. Clean Architecture یک ابزار است، نه هدف. هدف نهایی شما، تحویل نرم‌افزاری است که ارزش تجاری ایجاد کند و نگهداری آن برای شما و تیمتان آسان باشد. گاهی اوقات در پروژه‌های واقعی، ممکن است نیاز باشد برخی از این قوانین را کمی منعطف کنید تا سرعت توسعه حفظ شود، اما همیشه بدانید که چه چیزی را تغییر می‌دهید و چرا.

شاید در حال حاضر احساس کنید که ساختار فعلی پروژه‌تان بیش از حد پیچیده شده یا می‌خواهید از معماری قدیمی به Clean Architecture مهاجرت کنید اما نمی‌دانید از کجا شروع کنید. انتقال یک سیستم زنده به یک معماری جدید، شبیه به جراحی قلب باز در حالی است که بیمار در حال دویدن است! برای اینکه این مسیر را بدون ریسک و با استانداردهای جهانی طی کنید، می‌توانید با متخصصین ما در بخش مشاوره ZiroxAI در ارتباط باشید تا با تحلیل دقیق کدها و بیزنس شما، بهینه‌ترین استراتژی بازسازی (Refactoring) را طراحی کنیم.