آموزش معماری تمیز در مهندسی نرم افزار و سیستم های بزرگ

در مهندسی نرم افزار سازمانی، مرز میان پروژه‌ای که پس از چند سال هنوز چابک، توسعه پذیر و سودآور باقی می‌ماند با پروژه‌ای که تبدیل به باتلاق کدهای موروثی (Legacy Swamp) و کلاف سردرگم اسپاگتی می‌شود، در یک فاکتور بنیادین خلاصه می‌شود: نحوه معماری نرم افزار، مدیریت مرزهای تفکیک‌شده (Boundaries) و جهت وابستگی های سورس‌کد. الگوی معماری تمیز (Clean Architecture) که توسط رابرت سی. مارتین (عمو باب - Robert C. Martin) در سال ۲۰۱۲ فرموله و استاندارد شد، پاسخی مهندسی‌شده و ساختاریافته به بزرگ‌ترین چالش شرکت های نرم افزاری است: چگونه سیستمی بسازیم که هسته کسب‌وکار آن بدون کوچک‌ترین وابستگی به دیتابیس، رابط کاربری، فریم ورک های وب و سرویس هایی خارجی نفس بکشد و تغییر هر ابزار در گذر زمان، کمترین اصطکاک و هزینه را به سازمان تحمیل کند؟

در این راهنمای مرجع و دانشنامه‌ای، قصد نداریم صرفاً به تعاریف سطحی و نظریه‌پردازی های کلی بپردازیم؛ بلکه قرار است کالبدشکافی عمیقی از قوانین بنیادین وابستگی (The Dependency Rule)، اصل وارونگی کنترل (IoC) و وابستگی (DIP)، کالبدشکافی لایه های چهارگانه دوار، پیاده سازی خط‌به‌خط یک سناریوی تجاری با مقیاس واقعی در دنیای تجارت الکترونیک، مدیریت ترانزاکشن های اتمیک با الگوی Unit of Work، هم‌افزایی با مفاهیم Domain-Driven Design (DDD) و CQRS، استراتژی تست های واحد فوق‌سریع بدون نیاز به دیتابیس و نقشه راه مهاجرت گام‌به‌گام سیستم های قدیمی داشته باشیم.

تبارشناسی بحران در سیستم های سازمانی: چرا معماری سنتی سه لایه (۳-Tier) محکوم به شکست است؟

بیش از دو دهه است که معماری لایه‌ای سنتی (Three-Tier Architecture) به عنوان الگوی استاندارد در دانشگاه ها، آموزشگاه ها و تیم های توسعه تدریس می‌شود. در این الگو، سیستم به سه لایه افقی تقسیم می‌گردد:

Presentation Layer (Controllers / Web API / Views)
                  ↓ Direct Dependency
Business Logic Layer (Services / Managers)
                  ↓ Direct Dependency
Data Access Layer (Database / ORM Entities / DAOs)

در نگاه اولیه و در پروژه هایی ساده دانشجویی یا CRUDهای دم‌دستی، این معماری تمیز و کارآمد به نظر می‌رسد. اما نقص ساختاری مهلک آن کجاست؟ جهت پیکان های وابستگی در این معماری از بالا به پایین و مستقیماً به سمت پایگاه داده نشانه رفته است. به بیان دیگر، کل منطق کسب‌وکار سیستم حول محور جداول پایگاه داده و ابزار ORM مدل سازی می‌شود (Database-Driven Architecture).

هنگامی که اندازه پروژه از چند هزار خط کد فراتر رفته و عمر آن به چند سال می‌رسد، قانون دوم لمان (Lehman's Laws of Software Evolution) خود را نشان می‌دهد: «سیستم های نرم افزاری با گذشت زمان تمایل به افزایش پیچیدگی و بی‌نظمی دارند، مگر آنکه کار مداومی روی نگه داری معماری آن ها انجام شود.» وابستگی مستقیم لایه تجاری به پایگاه داده، سه فاجعه بزرگ را رقم می‌زند:

فاجعه اول: پدیده مدل های نحیف دامین (Anemic Domain Models)

وقتی جداول پایگاه داده نقطه عزیمت طراحی قرار می‌گیرند، کلاس های برنامه تبدیل به صرفاً حامل های بی‌خاصیت داده (Data Bags) با متدهای گتر و ستر (Getters and Setters) می‌شوند. رفتارهای واقعی کسب‌وکار، محاسبات مالی، اعتبارسنجی ها و قوانین بیزینس به جای آنکه در دل خود موجودیت کپسوله شوند، در کلاس های متورمی به نام OrderService یا UserManager با هزاران خط کد پخش می‌شوند. در نتیجه، این کلاس های سرویس تبدیل به God Objects غیرقابل نگه داری می‌شوند و اصل کپسوله سازی در برنامه نویسی شیءگرا به طور کامل نابود می‌گردد.

فاجعه دوم: کندی شدید و شکنندگی تست های خودکار

در معماری سنتی، چون لایه سرویس مستقیماً کلاس های مخزن داده و ORM را صدا می‌زند، امکان اجرای تست واحد خالص وجود ندارد. برای تست کردن اینکه آیا «در صورت اعمال کوپن تخفیف، مبلغ سفارش به درستی محاسبه می‌شود یا خیر»، توسعه دهنده ناچار است کل اتصال دیتابیس را لود کند، مایگریشن ها را اجرا نماید، دیتای اولیه را در جدول بریزد و پس از تست، دیتابیس را پاک سازی کند. این امر باعث می‌شود زمان اجرای هر تست از چند میلی‌ثانیه به چند ثانیه افزایش یابد. در شرکتی با ۳۰۰۰ تست خودکار، اجرای سوییت تست از ۵ دقیقه به بیش از ۲ ساعت در پایپ لاین CI/CD می‌رسد؛ وضعیتی که انگیزه نوشتن تست را در تیم توسعه به کلی نابود می‌کند.

فاجعه سوم: قفل شدگی عمیق روی ابزار های زیرساختی (Infrastructure Lock-In)

اگر پس از سه سال تصمیم بگیرید که به دلیل حجم تراکنش ها، پایگاه داده رابطه ای خود را به یک مدل توزیع شده یا ترکیبی با ردیس (Redis) و مونگو (MongoDB) تغییر دهید، یا اگر نسخه فریم ورک وب شما منسوخ شود، با یک بن‌بست کامل روبرو می‌شوید. از آنجا که انوتیشن ها، متدها و تایپ های ORM در تمام سرویس هایی تجاری نفوذ کرده‌اند، هیچ تغییری بدون شکستن صدها متد بیزینس امکان پذیر نیست.

فلسفه بنیادین و ۵ ویژگی حیاتی معماری تمیز رابرت مارتین

معماری تمیز برای حل ریشه‌ای این بن‌بست متولد شد. این معماری یک استاندارد خلق‌الساعه نیست، بلکه تلفیقی بلوغ‌یافته از معماری شش‌ضلعی (Hexagonal Architecture / Ports and Adapters) الستیر کاکبرن، معماری پیازی (Onion Architecture) جفری پالرمو و الگو های Screaming Architecture است. طبق تبیین رابرت مارتین، هر سیستمی که از معماری تمیز پیروی کند، باید پنج ویژگی اساسی زیر را در عمل به نمایش بگذارد:

1. استقلال از فریم ورک ها (Independent of Frameworks): معماری نرم افزار نباید وابسته به وجود کتابخانه ها یا فریم ورک های سنگین (مانند Spring, Django, NestJS, FastAPI, ASP.NET Core) باشد. فریم ورک ها صرفاً ابزار هایی برای عرضه محصول به دنیای خارج هستند و هسته برنامه باید بدون آن ها و با زبان استاندارد پایتون، جاوا، تایپ‌اسکریپت یا گو کامپایل و اجرا شود.
2. تست پذیری مستقل و خالص (Testable): تمامی قوانین کسب‌وکار باید بدون حضور UI، بدون سرور دیتابیس، بدون وب‌سرور و بدون هرگونه اتصال شبکه قابل تست باشند. تست های هسته تجاری باید در حافظه رم و با سرعت میکروثانیه اجرا شوند.
3. استقلال از رابط کاربری (Independent of UI): رابط کاربری باید به راحتی و بدون تغییر کوچک‌ترین خطی از قوانین تجاری قابل تعویض باشد. تبدیل یک واسط کاربری وب به کنسول متنی (CLI)، یا مهاجرت از REST API به gRPC، GraphQL یا پروتکل های پیام‌رسان نظیر AMQP نباید تاثیری بر منطق Use Caseها بگذارد.
4. استقلال از پایگاه داده (Independent of Database): شما باید بتوانید دیتابیس PostgreSQL را با Oracle, MongoDB, Couchbase, Cassandra یا حتی فایل های متنی روی دیسک تعویض کنید؛ بدون آنکه دامین و موارد کاربرد بویی از این تغییر ببرند. کسب‌وکار برنامه هرگز نباید پایگاه داده محور باشد.
5. استقلال از عوامل خارجی (Independent of any External Agency): در واقع، هسته تجاری شما کاملاً از دنیای پیرامون بی‌خبر است و مرزهای آن با قراردادها (Interfaces) ایزوله شده است.

کالبدشکافی قانون طلایی وابستگی (The Dependency Rule) و عبور از مرزها

اگر قرار باشد فقط و فقط یک قانون را در تمام طول حیات مهندسی خود به خاطر بسپارید، آن قانون طلایی وابستگی است:

بیایید با دقت به تصویر بالا نگاه کنیم. یک تناقض ظاهری در اینجا رخ می‌دهد که کلید درک معماری تمیز است:

• در زمان اجرا (Runtime Control Flow): کاربر دکمه‌ای در فرانت اند را فشار می‌دهد. درخواست به OrderController می‌رسد؛ کنترلر سناریوی CreateOrderUseCase را صدا می‌زند؛ این Use Case موجودیت Order را ارزیابی کرده و سپس برای ذخیره داده، دیتابیس PostgreSQL را فراخوانی می‌کند. بنابراین جریان اجرا از چپ به راست (از لایه بیرونی وب به سمت لایه بیرونی دیتابیس) حرکت می‌کند.
• در زمان کامپایل و سورس‌کد (Source Code Dependencies): اگر قرار بود لایه Use Case مستقیماً کلاس دیتابیس را ایمپورت کند، قانون وابستگی شکسته می‌شد و بیزینس به زیرساخت وابسته می‌گردید. اینجاست که اصل وارونگی وابستگی (DIP) وارد میدان می‌شود: لایه دامین یک قرارداد انتزاعی به نام IOrderRepository تعریف می‌کند. لایه زیرساخت (Postgres) این قرارداد را پیاده سازی می‌نماید. در نتیجه، وابستگی سورس‌کد ۱۸۰ درجه معکوس شده و به سمت درون نشانه می‌رود!

واکاوی تشریحی و وظایف لایه های چهارگانه دوار

حلقه اول (مرکز دایره): موجودیت های تجاری دامین (Entities & Value Objects)

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

• موجودیت ها (Entities): اشیائی هستند که شناسه پایدار (Identity) دارند. به عنوان مثال، یک کاربر یا یک سفارش حتی اگر تمام مشخصات و آدرس آن تغییر کند، همچنان همان کاربر یا همان سفارش قبلی با همان شناسه یکتا است. در این لایه، تمامی رفتارهای مربوط به تغییر حالت، اعمال تخفیف، اعتبارسنجی مبالغ و قوانین تغییر وضعیت باید مستقیماً در قالب متدهای همین کلاس ها پیاده سازی شوند.
• اشیاء مقداری (Value Objects): اشیائی فاقد شناسه اختصاصی که هویت آن ها صرفاً بر پایه مقادیر صفاتشان تعریف می‌شود. بارزترین نمونه آن Money (شامل فیلد مبلغ و نوع ارز)، EmailAddress، یا GeoLocation است. اشیاء مقداری الزاماً تغییرناپذیر (Immutable) هستند؛ یعنی هر عملیاتی روی آن ها (مثلاً اضافه کردن دو مقدار پول) منجر به تولید یک شیء جدید می‌شود.
• ناورداهای دامین (Domain Invariants): شرایط و الزاماتی که تحت هر شرایطی باید در دامین صادق باشند؛ برای مثال: «مبلغ کل سفارش هرگز نمی‌تواند منفی باشد» یا «یک سفارش لغوشده نمی‌تواند مجدداً پرداخت شود». این شروط باید در لحظه تغییر وضعیت یا درون سازنده کلاس بررسی و استثنا پرتاب کنند.

حلقه دوم: سناریوهای کاربردی برنامه (Application Business Rules / Use Cases)

این لایه شامل سناریوهای خاصی است که کاربران یا سیستم های دیگر برای دستیابی به یک هدف کاری مشخص انجام می‌دهند؛ مانند «ثبت‌نام کاربر جدید»، «افزودن محصول به سبد خرید»، «تایید تراکنش بانکی»، یا «تغییر آدرس ارسال سفارش». Use Caseها منطق دامین را هماهنگ (Orchestrate) می‌کنند:

• دریافت اشیاء انتقال داده (DTO) از لایه های بیرونی.
• واکشی موجودیت های مورد نیاز از طریق اینترفیس ریپازیتوری.
• فراخوانی متدهای موجودیت دامین برای اجرای قوانین تجاری.
• ذخیره وضعیت جدید موجودیت در مخزن داده.
• ارسال رویدادهای دامین یا اعلان ها به سیستم های پیرامونی.

حلقه سوم: آداپتورهای واسط (Interface Adapters)

نقش حیاتی این لایه، تبدیل و میانجی‌گری فرمت داده هاست:

• کنترلرها (Controllers): ورودی های خام محیط شبکه (مانند JSON بدنه HTTP POST یا پارامترهای Query String) را دریافت، نوع‌سنجی اولیه و به شیء فرمان (Command DTO) تبدیل کرده و به Use Case پاس می‌دهند.
• پرزنترها (Presenters / Serializers): نتایج بازگشتی از Use Case را دریافت کرده و به ساختار مناسب برای کلاینت (مثلاً قالب JSON با ساختار صفحه بندی یا قالب HTML) فرمت بندی می‌کنند.
• درگاه ها و نگاشت‌گرها (Gateways & Data Mappers): مدل های ذخیره سازی جداول دیتابیس را به آبجکت های غنی دامین و برعکس تبدیل می‌کنند.

حلقه چهارم: ابزار ها، درایورها و فریم ورک ها (Frameworks & Drivers)

بیرونی‌ترین لایه که شامل پکیج ها و کدهای تکنیکال است: درایور دیتابیس (psycopg۲, asyncpg, pymongo)، کدهای ORM (مانند SQLAlchemy یا Prisma)، وب‌سرور (Uvicorn, Gunicorn, Nginx)، پکیج های ارسال ایمیل، ابزار های لاگینگ و صف های پیام نظیر Apache Kafka یا RabbitMQ. در معماری تمیز، این ابزار ها صرفاً کدهای چسباننده (Glue Code) هستند.

پیشنهاد مطالعه

بهترین زبان برنامه نویسی اندروید در سال ۲۰۲۶: مقایسه جامع

انتخاب زبان برنامه نویسی برای ساخت اپلیکیشن اندروید، مهم ترین و سرنوشت سازترین تصمیم فنی در چرخه حیات هر پروژه موبایل است. تصمیمی که مستقیماً سرعت عر…

مشاهده مقاله ←

پیاده سازی عملی و گام به گام در یک سناریوی تجاری پیچیده (Production-Ready Engine)

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

گام ۱: لایه دامین - اشیاء مقداری، استثناها و موجودیت غنی

# src/domain/exceptions/domain_errors.py
class DomainException(Exception):
    pass

class CurrencyMismatchError(DomainException):
    pass

class OrderStateError(DomainException):
    pass

class InsufficientPaymentError(DomainException):
    pass

# src/domain/value_objects/money.py
from dataclasses import dataclass
from domain.exceptions.domain_errors import CurrencyMismatchError

@dataclass(frozen=True)
class Money:
    amount: float
    currency: str = "IRR"

    def __post_init__(self):
        if self.amount < ۰:
            raise ValueError("مبلغ مالی نمی تواند منفی باشد.")

    def add(self, other: 'Money') -> 'Money':
        if self.currency != other.currency:
            raise CurrencyMismatchError(f"ارزهای {self.currency} و {other.currency} قابل جمع نیستند.")
        return Money(round(self.amount + other.amount, ۲), self.currency)

    def multiply(self, factor: int) -> 'Money':
        if factor < ۰:
            raise ValueError("ضریب ضرب نمی تواند منفی باشد.")
        return Money(round(self.amount * factor, ۲), self.currency)

# src/domain/entities/order.py
from datetime import datetime
from typing import List
from domain.value_objects.money import Money
from domain.exceptions.domain_errors import OrderStateError, InsufficientPaymentError

class OrderItem:
    def __init__(self, product_id: str, quantity: int, unit_price: Money):
        if quantity <= ۰:
            raise ValueError("تعداد کالا در سفارش باید حداقل ۱ باشد.")
        self.product_id = product_id
        self.quantity = quantity
        self.unit_price = unit_price

    @property
    def subtotal(self) -> Money:
        return self.unit_price.multiply(self.quantity)

class Order:
    def __init__(self, order_id: str, customer_id: str, items: List[OrderItem]):
        if not items:
            raise OrderStateError("سفارش نمی تواند فاقد قلم کالا باشد.")
        self.id = order_id
        self.customer_id = customer_id
        self.items = items
        self.created_at = datetime.utcnow()
        self.status = "CREATED"
        self.paid_at = None

    def calculate_total(self) -> Money:
        base_currency = self.items[۰].unit_price.currency
        total = Money(۰.۰, base_currency)
        for item in self.items:
            total = total.add(item.subtotal)
        return total

    def process_payment(self, paid_amount: Money) -> None:
        if self.status != "CREATED":
            raise OrderStateError(f"سفارش در وضعیت {self.status} امکان پرداخت مجدد ندارد.")
        
        total = self.calculate_total()
        if paid_amount.amount < total.amount:
            raise InsufficientPaymentError(
                f"مبلغ واریزی ({paid_amount.amount}) از مبلغ کل ({total.amount}) کمتر است."
            )
        
        self.status = "PAID"
        self.paid_at = datetime.utcnow()

گام ۲: لایه دامین - قراردادهای مخزن داده و سرویس های خارجی (Ports)

# src/domain/repositories/i_order_repository.py
from abc import ABC, abstractmethod
from typing import Optional
from domain.entities.order import Order

class IOrderRepository(ABC):
    @abstractmethod
    def save(self, order: Order) -> None:
        pass

    @abstractmethod
    def find_by_id(self, order_id: str) -> Optional[Order]:
        pass

# src/domain/ports/i_payment_gateway.py
from abc import ABC, abstractmethod
from domain.value_objects.money import Money

class IPaymentGateway(ABC):
    @abstractmethod
    def charge(self, customer_id: str, amount: Money, token: str) -> bool:
        pass

گام ۳: لایه اپلیکیشن - اشیاء انتقال داده (DTO) و Use Caseهای مستقل

# src/application/dto/order_requests.py
from dataclasses import dataclass
from typing import List, Optional

@dataclass(frozen=True)
class OrderItemDTO:
    product_id: str
    quantity: int
    unit_price: float
    currency: str = "IRR"

@dataclass(frozen=True)
class CreateOrderCommand:
    order_id: str
    customer_id: str
    items: List[OrderItemDTO]

@dataclass(frozen=True)
class PayOrderCommand:
    order_id: str
    payment_token: str
    amount: float
    currency: str = "IRR"

@dataclass(frozen=True)
class OrderResponseDTO:
    order_id: str
    customer_id: str
    status: str
    total_amount: float
    currency: str
    created_at_iso: str

# src/application/use_cases/create_order_use_case.py
from domain.entities.order import Order, OrderItem
from domain.value_objects.money import Money
from domain.repositories.i_order_repository import IOrderRepository
from application.dto.order_requests import CreateOrderCommand, OrderResponseDTO

class CreateOrderUseCase:
    def __init__(self, order_repo: IOrderRepository):
        self.order_repo = order_repo

    def execute(self, command: CreateOrderCommand) -> OrderResponseDTO:
        domain_items = [
            OrderItem(
                product_id=it.product_id,
                quantity=it.quantity,
                unit_price=Money(it.unit_price, it.currency)
            )
            for it in command.items
        ]
        order = Order(command.order_id, command.customer_id, domain_items)
        self.order_repo.save(order)

        total = order.calculate_total()
        return OrderResponseDTO(
            order_id=order.id,
            customer_id=order.customer_id,
            status=order.status,
            total_amount=total.amount,
            currency=total.currency,
            created_at_iso=order.created_at.isoformat()
        )

گام ۴: لایه زیرساخت (Infrastructure) - آداپتور پایگاه داده PostgreSQL

# src/infrastructure/persistence/postgres_order_repository.py
import json
from typing import Optional
from domain.entities.order import Order, OrderItem
from domain.value_objects.money import Money
from domain.repositories.i_order_repository import IOrderRepository

class PostgresOrderRepository(IOrderRepository):
    def __init__(self, db_connection_pool):
        self.pool = db_connection_pool

    def save(self, order: Order) -> None:
        with self.pool.cursor() as cur:
            cur.execute("""
                INSERT INTO orders (id, customer_id, status, total_amount, currency, created_at, paid_at)
                VALUES (%s, %s, %s, %s, %s, %s, %s)
                ON CONFLICT (id) DO UPDATE SET 
                    status = EXCLUDED.status,
                    paid_at = EXCLUDED.paid_at;
            """, (
                order.id, order.customer_id, order.status, 
                order.calculate_total().amount, order.calculate_total().currency,
                order.created_at, order.paid_at
            ))
            
            for item in order.items:
                cur.execute("""
                    INSERT INTO order_items (order_id, product_id, quantity, unit_price, currency)
                    VALUES (%s, %s, %s, %s, %s)
                    ON CONFLICT DO NOTHING;
                """, (order.id, item.product_id, item.quantity, item.unit_price.amount, item.unit_price.currency))

    def find_by_id(self, order_id: str) -> Optional[Order]:
        with self.pool.cursor() as cur:
            cur.execute("SELECT id, customer_id, status, created_at FROM orders WHERE id = %s", (order_id,))
            order_row = cur.fetchone()
            if not order_row:
                return None
            
            cur.execute("SELECT product_id, quantity, unit_price, currency FROM order_items WHERE order_id = %s", (order_id,))
            item_rows = cur.fetchall()
            
            items = [
                OrderItem(r[۰], r[۱], Money(r[۲], r[۳]))
                for r in item_rows
            ]
            order = Order(order_row[۰], order_row[۱], items)
            order.status = order_row[۲]
            return order

گام ۵: لایه ارائه (Presentation) - کنترلر وب FastAPI و تزریق وابستگی

# src/presentation/http/order_router.py
from fastapi import APIRouter, Depends, HTTPException, status
from pydantic import BaseModel, Field
from typing import List
from application.dto.order_requests import CreateOrderCommand, OrderItemDTO
from application.use_cases.create_order_use_case import CreateOrderUseCase
from domain.exceptions.domain_errors import DomainException

router = APIRouter(prefix="/api/v۱/orders", tags=["Order Management"])

class ItemRequestModel(BaseModel):
    product_id: str = Field(..., example="PROD-۹۰۰")
    quantity: int = Field(..., gt=۰, example=۲)
    unit_price: float = Field(..., gt=۰, example=۴۵۰۰۰۰.۰)

class CreateOrderRequestModel(BaseModel):
    order_id: str = Field(..., example="ORD-۲۰۲۶-۰۰۱")
    customer_id: str = Field(..., example="CUST-۷۷")
    items: List[ItemRequestModel]

@router.post("/", status_code=status.HTTP_۲۰۱_CREATED)
def create_order(
    payload: CreateOrderRequestModel,
    use_case: CreateOrderUseCase = Depends(get_create_order_use_case)
):
    try:
        command = CreateOrderCommand(
            order_id=payload.order_id,
            customer_id=payload.customer_id,
            items=[OrderItemDTO(it.product_id, it.quantity, it.unit_price) for it in payload.items]
        )
        response_dto = use_case.execute(command)
        return {
            "success": True,
            "message": "سفارش با موفقیت در سیستم ثبت گردید.",
            "data": response_dto
        }
    except DomainException as ex:
        raise HTTPException(status_code=status.HTTP_۴۰۰_BAD_REQUEST, detail=str(ex))
    except Exception as ex:
        raise HTTPException(status_code=status.HTTP_۵۰۰_INTERNAL_SERVER_ERROR, detail="خطای بحرانی در سرور")

مدیریت ترانزاکشن های اتمیک (ACID) با الگوی Unit of Work بدون شکستن مرزها

یکی از پرتکرارترین ابهامات مهندسان ارشد در معماری تمیز این است: «اگر یک Use Case نیاز داشته باشد همزمان سفارش را ثبت کند، موجودی انبار را کسر نماید و یک فاکتور مالی ایجاد کند، چگونه می‌توان تضمین کرد که اگر کسر موجودی با شکست مواجه شد، کل عملیات رول‌بک (Rollback) شود؛ بدون اینکه شیء Session دیتابیس یا ترانزاکشن SQL وارد لایه Use Case شود؟»

راهکار طلایی این مسئله، الگوی Unit of Work (واحد کار) است. ما یک انتزاع در دامین تعریف می‌کنیم که چرخه حیات تراکنش را کنترل می‌کند، اما پیاده سازی واقعی آن در لایه زیرساخت با سشن دیتابیس کار می‌کند:

# src/domain/ports/i_unit_of_work.py
from abc import ABC, abstractmethod
from domain.repositories.i_order_repository import IOrderRepository

class IUnitOfWork(ABC):
    orders: IOrderRepository

    @abstractmethod
    def __enter__(self) -> 'IUnitOfWork':
        pass

    @abstractmethod
    def __exit__(self, exc_type, exc_val, exc_tb):
        pass

    @abstractmethod
    def commit(self) -> None:
        pass

    @abstractmethod
    def rollback(self) -> None:
        pass

# پیاده سازی در زیرساخت با SQLAlchemy:
class SqlAlchemyUnitOfWork(IUnitOfWork):
    def __init__(self, session_factory):
        self.session_factory = session_factory

    def __enter__(self):
        self.session = self.session_factory()
        self.orders = PostgresOrderRepository(self.session)
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        if exc_type:
            self.rollback()
        self.session.close()

    def commit(self):
        self.session.commit()

    def rollback(self):
        self.session.rollback()

پیشنهاد مطالعه

آموزش داکر از صفر تا پروداکشن: راهنمای کاربردی با دستورات

آموزش جامع داکر (Docker) از مفاهیم اولیه کانتینر ها تا نوشتن داکرفایل، دستورات کاربردی داکر، Docker Compose و استقرار در محیط پروداکشن برای توسعه دهن…

مشاهده مقاله ←

استراتژی جامع آزمون نرم افزار (The Testing Pyramid in Clean Architecture)

معماری تمیز بالاترین بازدهی خود را در زمان نوشتن و اجرای تست های خودکار نشان می‌دهد. به دلیل ایزولاسیون کامل دامین، سرعت اجرای تست های واحد با شبیه‌سازهای درون‌حافظه‌ای (In-Memory Fakes) تا ۱۰۰ برابر افزایش می‌یابد:

# tests/unit/test_create_order.py
import pytest
from typing import Dict
from domain.entities.order import Order
from domain.repositories.i_order_repository import IOrderRepository
from application.dto.order_requests import CreateOrderCommand, OrderItemDTO
from application.use_cases.create_order_use_case import CreateOrderUseCase
from domain.exceptions.domain_errors import OrderStateError

class FakeOrderRepository(IOrderRepository):
    def __init__(self):
        self._orders: Dict[str, Order] = {}

    def save(self, order: Order) -> None:
        self._orders[order.id] = order

    def find_by_id(self, order_id: str):
        return self._orders.get(order_id)

def test_create_order_successfully_in_memory():
    repo = FakeOrderRepository()
    use_case = CreateOrderUseCase(order_repo=repo)
    
    command = CreateOrderCommand(
        order_id="ORD-۹۹",
        customer_id="USER-۱",
        items=[OrderItemDTO(product_id="P۱", quantity=۳, unit_price=۲۰۰۰۰.۰)]
    )
    result = use_case.execute(command)
    
    assert result.order_id == "ORD-۹۹"
    assert result.total_amount == ۶۰۰۰۰.۰
    assert result.status == "CREATED"
    assert "ORD-۹۹" in repo._orders

def test_order_creation_fails_without_items():
    repo = FakeOrderRepository()
    use_case = CreateOrderUseCase(order_repo=repo)
    
    command = CreateOrderCommand(order_id="ORD-۱۰۰", customer_id="USER-۱", items=[])
    
    with pytest.raises(OrderStateError):
        use_case.execute(command)

ماتریس مقایسه ای جامع: ارزیابی الگو های معماری نرم افزار

جدول زیر ماتریس تحلیلی کاملی برای انتخاب آگاهانه معماری در پروژه هایی گوناگون ارائه می‌دهد:

پنج خطای مهلک و ضدالگو های رایج در پیاده سازی معماری تمیز

نقشه راه ۴ مرحله ای ریفکتورینگ و مهاجرت سیستم های موروثی (Strangler Fig Strategy)

تلاش برای متوقف کردن پروژه و بازنویسی کامل آن از صفر (The Big Bang Rewrite) طبق آمار شرکت گارتنر در بیش از ۸۰٪ موارد به شکست می‌انجامد. رویکرد حرفه‌ای، استفاده از الگوی خفه‌کننده انجیر معابد (Strangler Fig Pattern) و مهاجرت فزاینده است:

1. مرحله ۱ - ایجاد پکیج دامین و استخراج قوانین تجاری: در کنار کدهای قدیمی، پوشه src/domain را بسازید. قوانین کلیدی بیزینس (محاسبات، تغییر وضعیت ها) را از دل کنترلرها یا سرویس هایی قدیمی بیرون کشیده و به صورت توابع و کلاس های خالص بدون وابستگی در این پوشه پیاده کنید. کدهای قدیمی می‌توانند این کلاس های جدید را صدا بزنند.
2. مرحله ۲ - پنهان سازی دسترسی به داده ها پشت اینترفیس ها: برای هر عملیات پایگاه داده، یک Interface در دامین تعریف کنید. در ابتدا، پیاده سازی این اینترفیس می‌تواند صرفاً کالبد کدهای قدیمی شما باشد.
3. مرحله ۳ - کپسوله سازی سناریوها در Use Case: هر زمان که باگ جدیدی گزارش شد یا نیازمندی تازه‌ای اضافه گردید، آن بخش را در قالب یک کلاس Use Case نو بنویسید و کنترلر را به جای سرویس هایی قدیمی به Use Case متصل کنید.
4. مرحله ۴ - تفکیک و ایزولاسیون کامل پکیج ها: پس از چند ماه، کدهای قدیمی به تدریج جای خود را به لایه های تمیز داده‌اند؛ بدون اینکه پروژه حتی یک دقیقه متوقف شود.

پیشنهاد مطالعه

معماری و پیاده سازی RAG در سیستم های هوش مصنوعی

چرا سیستم‌های RAG به ستون فقرات هوش مصنوعی سازمانی تبدیل شده‌اند؟ مدل‌های زبانی بزرگ (LLMs) با وجود درک زبانی شگفت‌انگیز، دو محدودیت بنیادین در محیط‌…

مشاهده مقاله ←

پرسش های متداول و عمیق مهندسان نرم افزار (FAQ)

چک لیست نهایی ممیزی سلامت معماری قبل از انتشار نهایی

• [ ] پکیج domain هیچ‌گونه وابستگی به پکیج های وب، دیتابیس، ORM یا فایل های زیرساختی ندارد.
• [ ] تمامی اعتبارسنجی های کسب‌وکار در دل کلاس های موجودیت یا Use Case کپسوله شده‌اند و کنترلرها فاقد منطق تجاری هستند.
• [ ] هیچ موجودیت دامین به طور مستقیم در پاسخ های JSON وب سرویس به کلاینت نشت نکرده است؛ از Response DTO استفاده شده است.
• [ ] برای هر عملیات I/O یا وابستگی خارجی، یک قرارداد Interface در لایه Domain یا Application وجود دارد.
• [ ] تست های واحد دامین و اپلیکیشن بدون نیاز به دیتابیس روشن و در حافظه رم با ماک های ساده اجرا می‌شوند.
• [ ] تمامی تراکنش های چند ریپازیتوری از طریق الگوی Unit of Work مدیریت می‌شوند.