از دید کلی تا کد: راهنمایی برای مبتدیان در تصویرسازی معماری نرمافزار با مدل C4

مقدمه

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

ورود بهمدل C4—رویکردی ساده و سلسله مراتبی برای تصویرسازی معماری نرمافزار که توسط سیمون براون ایجاد شده است. به آن به عنوان نقشه‌های گوگل برای نرمافزار خود فکر کنید: شما با دید جهانی شروع می‌کنید و به تدریج به سمت داخل زوم می‌کنید تا به خیابان‌ها و ساختمان‌های فردی برسید.

این آموزش به شما کمک می‌کند تا از هر چهار سطح مدل C4 با مثال‌های عملی، قطعات کد PlantUML و راهنمایی در مورد استفاده از ابزارهای مدرن مانند Visual Paradigm برای ایجاد دیاگرام‌های معماری حرفه‌ای که واقعاً به تیم شما کمک می‌کنند، عبور کنید.

🎯 درک مدل C4 از طریق یک مثال واقعی

بیایید مستندات برای«PayQuick»—یک پلتفرم پرداخت آنلاین مدرن که به کاربران اجازه می‌دهد پول بفرستند، قبض پرداخت کنند و کارت‌ها را مدیریت کنند. ما دیاگرام‌هایی برای هر سطح C4 ایجاد خواهیم کرد.

🗺️ سطح 1: دیاگرام زمینه سیستم

چه چیزی نشان می‌دهد

نگاه ۳۰٬۰۰۰ فوتی از سیستم شما در محیط آن.

مثال PayQuick

اعمال:

• مشتری شخصی

• فروشنده

• سیستم‌های بانکی

• درگاه پیامک

رابطه‌ها:

• مشتریان پول ارسال می‌کنند

• فروشندگان پرداخت‌ها را دریافت می‌کنند

• سیستم با بانک‌های خارجی ادغام می‌شود

• سیستم اعلان‌های پیامکی ارسال می‌کند

کد C4-PlantUML

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

title PayQuick - دیاگرام زمینه سیستم

Person(customer, "مشتری شخصی", "از اپلیکیشن برای ارسال پول و پرداخت قبض استفاده می‌کند")
Person(merchant, "فروشنده", "پرداخت‌ها را از مشتریان دریافت می‌کند")

System_Boundary(payquick, "پلتفرم PayQuick") {
    System(payquick_system, "PayQuick", "به مشتریان اجازه می‌دهد تا پرداخت‌ها و انتقال‌ها انجام دهند")
}

System_Ext(bank_system, "شبکه بانکی", "انتقال‌های بین بانکی را پردازش می‌کند", $tags="external")
System_Ext(sms_gateway, "Twilio SMS", "اعلان‌های تراکنش را ارسال می‌کند", $tags="external")
System_Ext(email_service, "SendGrid", "صورتحساب‌های ایمیلی را ارسال می‌کند", $tags="external")

Rel(customer, payquick_system, "پول ارسال می‌کند، قبض پرداخت می‌کند، تراکنش‌ها را مشاهده می‌کند")
Rel(merchant, payquick_system, "پرداخت‌ها را دریافت می‌کند، بازپرداخت‌ها را صادر می‌کند")
Rel(payquick_system, bank_system, "انتقال‌ها را از طریق", "API")
Rel(payquick_system, sms_gateway, "OTP و اعلان‌ها را از طریق", "HTTPS")
Rel(payquick_system, email_service, "صورتحساب‌ها را از طریق", "SMTP")

LAYOUT_WITH_LEGEND()
@enduml

نکته Visual Paradigm

در Visual Paradigm، از دستیار هوش مصنوعی برای ایجاد نمودارهای اولیه متناظر سیستم با توصیف سیستم شما به زبان طبیعی: «یک نمودار متناظر سیستم برای یک پلتفرم پرداخت با مشتریان، فروشندگان و ادغام با بانک‌ها ایجاد کن.»

📦 سطح 2: نمودار کانتینر

چه چیزی نشان می‌دهد

انتخاب‌های اصلی فناوری و نحوه تعامل آن‌ها.

مثال PayQuick

کانتینرها:

• اپلیکیشن موبایل (iOS/Android)

• اپلیکیشن وب (React)

• اپلیکیشن API (Spring Boot)

• پایگاه داده (PostgreSQL)

• صف پیام (RabbitMQ)

• کش (Redis)

کد C4-PlantUML

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

title PayQuick - نمودار کانتینر

Person(customer, "مشتری", "از اپلیکیشن موبایل یا رابط وب استفاده می‌کند")
Person(merchant, "فروشنده", "از داشبورد وب استفاده می‌کند")

System_Boundary(payquick, "پلتفرم PayQuick") {
    Container(mobile_app, "اپلیکیشن موبایل", "React Native, TypeScript", "رابط کاربری برای مشتریان ارائه می‌دهد")
    Container(web_app, "اپلیکیشن وب", "React, TypeScript", "داشبورد مدیریت و فروشندگان ارائه می‌دهد")
    
    Container_Boundary(api, "اپلیکیشن API") {
        Container(api_gateway, "گیت‌وی API", "Node.js, Express", "مسیریابی، احراز هویت و محدودیت نرخ را مدیریت می‌کند")
        Container(payment_service, "سرویس پرداخت", "Spring Boot, Java", "پردازش پرداخت‌ها و انتقال‌ها را انجام می‌دهد")
        Container(notification_service, "سرویس اطلاع‌رسانی", "Python, FastAPI", "اعلان‌های پیامکی و ایمیلی ارسال می‌کند")
    }
    
    ContainerDb(database, "پایگاه داده", "PostgreSQL", "حساب‌های کاربری، تراکنش‌ها و موجودی‌ها را ذخیره می‌کند")
    ContainerDb(cache, "کش", "Redis", "داده‌های جلسه و رکوردهای مورد استفاده مکرر را ذخیره می‌کند")
    ContainerQueue(queue, "صف پیام", "RabbitMQ", "پردازش غیرهمزمان اطلاع‌رسانی‌ها را مدیریت می‌کند")
}

System_Ext(bank_api, "API بانکی", "ادغام خارجی با بانک")
System_Ext(sms_provider, "API پیامک Twilio")

Rel(customer, mobile_app, "استفاده می‌کند", "HTTPS")
Rel(merchant, web_app, "استفاده می‌کند", "HTTPS")
Rel(mobile_app, api_gateway, "تماس API به انجام می‌دهد", "HTTPS/JSON")
Rel(web_app, api_gateway, "تماس API به انجام می‌دهد", "HTTPS/JSON")
Rel(api_gateway, payment_service, "درخواست‌ها را به سمت می‌فرستد", "gRPC")
Rel(api_gateway, notification_service, "درخواست‌ها را به سمت می‌فرستد", "gRPC")
Rel(payment_service, database, "داده‌ها را خوانده/نوشته می‌شود", "JDBC")
Rel(payment_service, cache, "داده‌های مکرر را در کش ذخیره می‌کند", "پروتکل Redis")
Rel(notification_service, queue, "رویدادها را منتشر می‌کند", "AMQP")
Rel(notification_service, sms_provider, "پیامک‌ها را از طریق ارسال می‌کند", "API REST")
Rel(payment_service, bank_api, "انتقال‌ها را از طریق انجام می‌دهد", "HTTPS")
@enduml

ویژگی هوش مصنوعی Visual Paradigm

از اتصال‌دهنده هوشمند با پیشنهادات هوش مصنوعی برای تشخیص خودکار و پیشنهاد روابط بین کانتینرها بر اساس نوع و مسئولیت‌های آن‌ها.

سطح 3: نمودار مؤلفه

چه چیزی نشان می‌دهد

ساختار داخلی یک کانتینر واحد.

مثال PayQuick

بیایید به سمت سرویس پرداختکانتینر برای دیدن اجزای آن:

اجزاء:

• کنترلر پرداخت

• مدیر تراکنش

• سرویس تشخیص تقلب

• ماشین حساب موجودی

• لایه ذخیره‌سازی

کد C4-PlantUML

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml

title PayQuick - نمودار مؤلفه سرویس پرداخت

!define C4ShapeInRow 4
!define C4BoundaryInRow 1

Container_Boundary(payment_service, "سرویس پرداخت") {
    Component(payment_controller, "کنترلر پرداخت", "کنترلر REST Spring", "مدیریت درخواست‌های ورودی پرداخت")
    Component(transaction_manager, "مدیر تراکنش", "سرویس Spring", "هماهنگ‌کننده جریان‌های پرداخت")
    Component(fraud_detector, "سرویس تشخیص تقلب", "سرویس Spring", "اعتبارسنجی تراکنش‌ها برای تقلب")
    Component(balance_calculator, "ماشین حساب موجودی", "سرویس Spring", "محاسبه و به‌روزرسانی موجودی حساب‌ها")
    Component(validation_service, "سرویس اعتبارسنجی", "سرویس Spring", "اعتبارسنجی داده‌های پرداخت و قوانین کسب‌وکار")
    
    ComponentDb(transaction_repo, "ذخیره‌سازی تراکنش", "Spring Data JPA", "ذخیره‌سازی رکوردهای تراکنش")
    ComponentDb(account_repo, "ذخیره‌سازی حساب", "Spring Data JPA", "مدیریت داده‌های حساب")
    ComponentDb(fraud_repo, "ذخیره‌سازی قوانین تقلب", "Spring Data JPA", "ذخیره‌سازی قوانین تشخیص تقلب")
    
    Component(notification_client, "کلاینت اطلاع‌رسانی", "کلاینت Feign", "تماس با سرویس اطلاع‌رسانی")
    Component(bank_client, "کلاینت بانکی", "کلاینت Feign", "یکپارچه‌سازی با API بانکی خارجی")
}

Rel(payment_controller, transaction_manager, "ارسال درخواست‌های پرداخت به")
Rel(transaction_manager, fraud_detector, "اعتبارسنجی تراکنش با")
Rel(transaction_manager, validation_service, "اعتبارسنجی داده‌ها با")
Rel(transaction_manager, balance_calculator, "به‌روزرسانی موجودی از طریق")
Rel(transaction_manager, transaction_repo, "ذخیره تراکنش‌ها در")
Rel(balance_calculator, account_repo, "خواندن/نوشتن داده‌های حساب به")
Rel(fraud_detector, fraud_repo, "بررسی قوانین در مقابل")
Rel(transaction_manager, notification_client, "ارسال اطلاع‌رسانی‌ها از طریق")
Rel(transaction_manager, bank_client, "پردازش انتقالات خارجی از طریق")

@enduml

نکته Visual Paradigm

از الگوهای نمودار مؤلفهدر Visual Paradigm برای سریع‌تر ساختار مؤلفه‌ها استفاده کنید. هوش مصنوعی می‌تواند الگوهای رایجی مانند ذخیره‌سازی، لایه سرویس و کنترلر را بر اساس نوع کانتینر شما پیشنهاد دهد.

💻 سطح ۴: نمودار کد (اختیاری)

آن چه نشان می‌دهد

کلاس‌ها، رابط‌ها و روش‌های واقعی.

مثال: کلاس FraudDetectionService

@startuml
title سرویس تشخیص تقلب - نمودار کلاس

class FraudDetectionService {
    - FraudRulesRepository fraudRepo
    - TransactionRepository txnRepo
    + checkFraud(txn: Transaction): FraudResult
    - evaluateRules(txn: Transaction): List<Rule>
    - calculateRiskScore(txn: Transaction): Double
    - isVelocityExceeded(userId: String): Boolean
}

class FraudResult {
    + isBlocked: boolean
    + riskScore: double
    + blockedRules: List<String>
    + getRiskLevel(): RiskLevel
}

class FraudRule {
    + id: Long
    + ruleName: String
    + threshold: Double
    + isEnabled: boolean
    + evaluate(txn: Transaction): boolean
}

class Transaction {
    + id: String
    + amount: BigDecimal
    + userId: String
    + timestamp: DateTime
    + merchantId: String
}

FraudDetectionService --> FraudResult : بازگرداندن
FraudDetectionService --> FraudRule : استفاده می‌کند
FraudDetectionService --> Transaction : اعتبارسنجی می‌کند
FraudResult ..> FraudRule : شامل است

@enduml

یادداشت:نمودارهای سطح ۴ بهتر است از کد به صورت خودکار با استفاده از ابزارهایی مانند:

• ویژگی‌های مهندسی کد Visual Paradigmویژگی‌ها

• ابزار تولید نمودار داخلی IntelliJ IDEA

• Swagger/OpenAPI برای مستندسازی API

🛠️ ابزارهای پیشنهادی: Visual Paradigm + ویژگیهای هوش مصنوعی

چرا Visual Paradigm؟

Visual Paradigm ابزاری جامع برای مدلسازی است که به طور طبیعی از نمودارهای C4 پشتیبانی میکند و ویژگیهای قدرتمند کمکی هوش مصنوعی ارائه میدهد:

ویژگیهای کلیدی برای مدلسازی C4:

1. تولید نمودار با قدرت هوش مصنوعی

   • سیستم خود را به زبان انگلیسی ساده توصیف کنید

   • هوش مصنوعی نمودارهای مناسب سطح C4 را پیشنهاد میکند

   • ساختار اولیه را به صورت خودکار تولید میکند

2. موتور چیدمان هوشمند

   • چیدمان خودکار اجزا

   • مسیریابی هوشمند اتصالات

   • سبک یکسان در سراسر نمودارها

3. مهندسی کد

   • معکوس سازی کد به نمودارها (سطح 4)

   • مهندسی پیش روی نمودارها به استخوانهای کد

   • نمودارها را همگام با پایگاه کد نگه دارید

4. ویژگیهای همکاری

   • همکاری تیمی در زمان واقعی

   • یکپارچه سازی با کنترل نسخه

   • صدور به چندین فرمت (PNG، PDF، SVG)

5. قالب‌های مدل C4

   • قالب‌های آماده برای هر سطح C4

   • مثال‌های مخصوص صنعت

   • راهنمایی‌های بهترین روش‌ها درون‌سازی شده

شروع کار با Visual Paradigm:

1. دانلودنسخه جامعه (رایگان) یا نسخه شرکتی

2. نصبپلاگین مدل C4 از بازار کار

3. ایجاد کنیداولین نمودار خود را با استفاده از راهنما ایجاد کنید

4. از کمک‌کار هوش مصنوعی استفاده کنیدبا کلیک روی آیکون میخ ج magiک

5. صدورو با تیم خود به اشتراک بگذارید

🚀 بهترین روش‌ها برای مبتدیان

1. از سادگی شروع کنید، سپس تکرار کنید

• با سطح 1 شروع کنید، حتی اگر احساس کنید خیلی ساده است

• قبل از پیش رفتن بیشتر، رضایت ذینفعان را کسب کنید

• جزئیات را به تدریج و مطابق نیاز اضافه کنید

2. نمودارها را به‌روز نگه دارید

• نمودارهای سطح 1-2 را با هر انتشار اصلی به‌روز کنید

• در صورت امکان، تولید سطح 4 را خودکار کنید

• نمودارهای منقضی را ذخیره کنید، حذف نکنید

3. اشیاء را به‌وضوح نام‌گذاری کنید

از فرمت زیر استفاده کنید: نام [فناوری] – توضیحات

✅ خوب: سرویس پرداخت [Spring Boot] - تراکنش‌های پرداخت را پردازش می‌کند
❌ بد: PaymentServiceیاچیز پرداخت

4. سطح مناسب را برای مخاطب خود انتخاب کنید

5. از زبان بصری یکدست استفاده کنید

• به قوانین رنگی C4 پایبند باشید

• از شکل‌های یکدست برای عناصر مشابه استفاده کنید

• سبک‌های فلش را برای انواع روابط حفظ کنید

📊 مثال کامل: نقشه‌برداری مسیر کاربر در سطوح مختلف

بیایید یک را دنبال کنیم«ارسال پول» ویژگی در تمام سطوح C4:

سطح 1 (محل وقوع): مشتری → PayQuick → شبکه بانکی

سطح 2 (محل‌های ذخیره‌سازی): اپلیکیشن موبایل → دروازه API → سرویس پرداخت → پایگاه داده → API بانک

سطح 3 (اجزاء): کنترلر پرداخت → مدیر تراکنش → تشخیص تقلب → ماشین حساب موجودی → ذخیره‌سازی تراکنش

سطح 4 (کد): PaymentController.transfer() → TransactionManager.process() → FraudDetection.checkFraud()

این رویکرد سلسله مراتبی به اعضای مختلف تیم کمک می‌کند تا سیستم را در سطح مناسب جزئیات درک کنند.

🎓 نتیجه‌گیری

مدل C4 معماری نرم‌افزار را از یک مفهوم ترسناک و مبهم به یک نقشه عملی و قابل دسترس تبدیل می‌کند. با شروع از تصویر کلی و پیشبرد تدریجی به سمت جزئیات، مستنداتی ایجاد می‌کنید که از مدیران فنی تا توسعه‌دهندگان تازه‌کار، همه را پوشش می‌دهد.

نکات کلیدی:

✅ سطح 1 زمینه‌سازی می‌کند — حتی برای مخاطبان فنی هم آن را نباید نادیده گرفت
✅ سطح 2 ستک فناوری و استراتژی انتشار شما را آشکار می‌کند
✅ سطح 3 نشان می‌دهد که کد شما درون سرویس‌ها چگونه سازمان‌دهی شده است
✅ سطح 4 اختیاری است — در صورت امکان آن را خودکار کنید
✅ Visual Paradigm و ابزارهای مشابه با ویژگی‌های هوش مصنوعی می‌توانند سرعت ایجاد نمودارها را تا ۵۰ تا ۷۰ درصد افزایش دهند
✅ مستندات زنده بهتر از مستندات کامل است — به صورت تکراری به‌روزرسانی کنید

به یاد داشته باشید: هدف این نیست که نمودارهای زیبا برای خودشان بسازید. هدف، تسهیل ارتباط، کاهش زمان آشنایی کاربران جدید و اتخاذ تصمیمات معماری بهتر است. امروز شروع کنید با یک نمودار ساده متناظر سیستم و ببینید چگونه درک تیم شما و بهره‌وری آن رشد می‌کند.

مراحل بعدی شما:

1. یکی از پروژه‌های فعلی خود را انتخاب کنید

2. یک نمودار سطح ۱ را روی کاغذ یا تخته سیاه طراحی کنید

3. آن را به C4-PlantUML یا Visual Paradigm ترجمه کنید

4. آن را با یک ذینفع غیرفنی به اشتراک بگذارید تا بازخورد دریافت کنید

5. جزئیات سطح 2 را به تدریج و هنگام لزوم اضافه کنید

به رسم نمودار لذت ببرید! 🎨