برنامه نویسی

ایجاد نمودارهای کلاس با Mermaid.js

اخیراً من عاشق استفاده از Mermaid.js برای گرفتن متن ساده و تبدیل آن به یک نمودار فنی شده ام. در این مقاله به شما نشان می‌دهم که نمودارهای کلاس Mermaid.js چگونه کار می‌کنند و چگونه می‌توانید از آنها برای برقراری ارتباط با روابط کلاس در اسناد علامت‌گذاری استفاده کنید.

نمودارهای کلاس 101

اگر با نمودارهای کلاس آشنا نیستید، آنها زیرمجموعه‌ای از Unified Markdown Language (UML) هستند که برای توصیف رابطه بین کلاس‌های مختلف با استفاده از کادرها و فلش‌ها مانند شکل زیر استفاده می‌شوند:

نمودار کلاس

در اینجا این نمودار یک کلاس Player و Monster را توصیف می کند که هر دو از یک Damageable Object انتزاعی به ارث می برند که به نوبه خود از GameObject به ارث می رسد.

این نمودار همچنین روش ها و ویژگی های هر کلاس را نشان می دهد. به عنوان مثال، در نمودار بالا، کلاس Monster دارای یک ویژگی خصوصی ThreatLevel از نوع int، یک ویژگی Color خصوصی از نوع Color و دو متد عمومی به نام‌های MakeNoise و OnKilled است که به ترتیب رشته و void را برمی‌گردانند.

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

استفاده از Mermaid.js

اکنون که نمودارهای کلاسی را توضیح دادیم، اجازه دهید به طور خلاصه به Mermaid.js بپردازیم.

Mermaid.js یک کتابخانه جاوا اسکریپت منبع باز است که نشانه گذاری های تخصصی را می گیرد و نمودارها را از آن تولید و ارائه می کند.

می‌توانید از Mermaid.js در مکان‌های مختلف، از جمله نشانه‌گذاری GitHub، نوت‌بوک‌های Polyglot و ویرایشگر پری دریایی زنده استفاده کنید.

در ادامه این مقاله، استفاده از Mermaid.js برای ارائه نمودارهای کلاس را بررسی خواهیم کرد.

تعریف کلاس

بیایید با چند کد Mermaid برای تعریف یک کلاس ساده شروع کنیم:

classDiagram
    class GameObject {
        -String Name
        -int PosX
        -int PosY
        +Despawn() void
    }
وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نمودار کلاس

خط اول به Mermaid می گوید که کدام نوع نمودار را ایجاد می کنیم.

سپس یک کلاس را به روشی نیمه آشنا با استفاده از کلمه کلیدی class، نام کلاس و { } برای نشان دادن مرزهای کلاس اعلام می کنیم.

در داخل کلاس می توانیم هر تعداد عضو را اعلام کنیم. فیلدها با استفاده از نوع داده خود به دنبال نام نوع خود تعریف می شوند، در حالی که روش ها با استفاده از نام متد، پرانتزها و در صورت تمایل فهرستی از پارامترها و سپس نوع برگشتی متد تعریف می شوند.

همچنین از + برای نشان دادن اعضای عمومی و – برای نشان دادن اعضای خصوصی استفاده می کنیم.

نحو کلاس جایگزین
نحوی که در بالا توضیح دادم، سینتکس Mermaid.js مدرن‌تر برای توصیف کلاس‌ها است. همه ابزارهایی که از Mermaid پشتیبانی می کنند از این قالب پشتیبانی نمی کنند.

برای نسخه‌های قدیمی‌تر نمودارهای کلاس Mermaid.js، ممکن است لازم باشد از نحو زیر استفاده کنید:

classDiagram
    class GameObject
    GameObject : -String Name
    GameObject : -int PosX
    GameObject : -int PosY
    GameObject : +Despawn() void
وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نتیجه نهایی همان است که قبلاً از نحو آشناتر { } استفاده کرده باشید. ترجیح شخصی من تمایل شدید به نحو قبلی است که از { } استفاده می کند، بنابراین من فقط در صورتی از این نحو قدیمی استفاده می کنم که ابزاری از نسخه ای از Mermaid.js استفاده کند که از نحو ترجیحی من پشتیبانی نمی کند.

روابط بین کلاس ها

اکثر نمودارهای کلاس بیش از یک کلاس در خود دارند، بنابراین بیایید نگاهی به رابطه بین دو کلاس بیندازیم:

classDiagram
    class GameObject {
        -String Name
        -int PosX
        -int PosY
        +Despawn() void
    }
    class DamageableObject {
        +int MaxHealth
        -int Health
        +IsDead() bool
        +TakeDamage(int damage) void
        +OnKilled() void
    }
    GameObject <|-- DamageableObject
وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نمودار کلاس

در اینجا دو کلاس تعریف می کنیم و از خط GameObject <|-- DamageableObject برای اعلام اینکه DamageableObject از GameObject ارث می برد استفاده می کنیم.

در حالی که وراثت رایج ترین نوع رابطه است، Mermaid.js از تعدادی اتصال دهنده مختلف بین کلاس ها پشتیبانی می کند، از جمله:

  • <|-- ارث
  • *– ترکیب بندی
  • o– تجمع
  • –> انجمن
  • ..> وابستگی
  • ..|> تحقق
  • — پیوند محکم
  • .. لینک شکسته

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

به عنوان مثال، بدن انسان از سلول ها تشکیل شده است در حالی که یک فروشنده فروش را تجمیع می کند.

نمودار کلاس

برای جزئیات کامل و نمونه هایی از انواع مختلف روابط، به مستندات رسمی Mermaid.js مراجعه کنید.

مستندسازی روابط

ممکن است متوجه شده باشید که نمودار بالا شامل یک جفت برچسب روی روابط آنها است.

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

classDiagram
    Human *-- Cells : composed of
    Salesperson o-- Sales : makes
    Human <|-- Salesperson : is
وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نمودار کلاس

توجه داشته باشید که Mermaid.js چگونه نمودار را با توجه به اطلاعات جدید مبنی بر اینکه فروشندگان انسان هستند، کمی تغییر داده است. این یکی از مزایای کلیدی Mermaid.js به نظر من را برجسته می کند: تمام تلاش شما به جای تلاش برای به دست آوردن طرح بندی عالی، به توصیف روابط می رود.

تعدد در روابط

گاهی اوقات شما می خواهید به جزئیات دقیق تری در مورد تعدد روابط خود بپردازید، به ویژه هنگامی که با ترکیب و تجمیع سروکار دارید.

در این موارد شاید بخواهید بگویید که هر سلول متعلق به 1 نفر خواهد بود و 1 نفر سلول های زیادی خواهد داشت.

Mermaid.js به شما امکان می دهد این کار را با مشخص کردن جزئیات چندگانه در سمت چپ و راست فلش در نقل قول به صورت زیر انجام دهید:

classDiagram
    Human "1" *-- "*" Cells : composed of
    Salesperson "1" o-- "0..*" Sales : makes
    Human <|-- Salesperson : is
وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نمودار کلاس

من اولین کسی خواهم بود که اعتراف می‌کنم که نام‌های رابطه و تعدد در کنار هم خواندن این را سخت می‌کند. خوشبختانه، این ویژگی‌ها مستقل هستند و می‌توانید این رابطه را بدون برچسب فقط انسان «1» توصیف کنید. –“سلول‌ها در صورتی که نمودار را واضح‌تر می‌کند.

قبل از اینکه به جلو برویم، یک نمودار کلاس با چندگانه بسیار شبیه به یک نمودار رابطه موجودیت (ERD) است که Mermaid.js نیز از آن پشتیبانی می کند. برای جزئیات بیشتر، مقاله من در مورد نمودارهای رابطه نهاد با Mermaid.js را بررسی کنید.

موارد ویژه برای نمودارهای کلاس Mermaid.js

کلاس های حاشیه نویسی برای رابط ها، چکیده و موارد دیگر

گاهی اوقات می خواهید بتوانید یک کلاس را به نوعی خاص معرفی کنید. برای مثال، ممکن است بخواهید یک کلاس را به‌عنوان انتزاعی، یک رابط، یک شمارش، به‌عنوان مهر و موم شده / نهایی علامت‌گذاری کنید، یا پارامترهای نوع عمومی را مشخص کنید.

به این دلایل، mermaid به ما حاشیه نویسی می دهد که می تواند در کلاس ها اعمال شود.

به عنوان مثال، کد زیر از حاشیه نویسی <> برای نشان دادن یک کلاس به عنوان انتزاعی و از نشانگر * برای نشان دادن اعضای انتزاعی منفرد استفاده می کند:

classDiagram
    class GameObject {
        -String Name
        -int PosX
        -int PosY
        +Despawn() void
    }
    class DamageableObject {
        <<abstract>>
        +int MaxHealth
        -int Health
        +IsDead() bool
        +TakeDamage(int damage) void
        +OnKilled()* void
    }
    GameObject <|-- DamageableObject
وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نمودار کلاس

سایر کاربردهای حاشیه نویسی معمولاً عبارتند از <>، <>، <>، <>، و <>، اگرچه هیچ چیزی مانع از قرار دادن هر گونه حاشیه نویسی در کلاس های خود نمی شود.

پارامترهای نوع عمومی

گاهی اوقات می خواهید کلاس های عمومی را در برنامه خود داشته باشید.

این کلاس‌ها معمولاً در کد به‌عنوان ClassName نشان داده می‌شوند که در آن T نوعی است که با آن کار می‌کنند.

به عنوان مثال، یک کلاس List لیستی است که فقط شامل اعداد صحیح است در حالی که یک صف یک صف است که فقط نمونه های درخواست را مدیریت می کند.

Mermaid.js از روش استاندارد اعلام کلاس های عمومی یا پارامترهای نوع پشتیبانی نمی کند. درعوض، باید پارامترهای نوع عمومی را با تایلدهایی مانند ~T~ احاطه کنید، همانطور که در زیر نشان داده شده است:

classDiagram
    class Queue~T~ {
        -IEnumerable~T~ items
        +Enqueue(T item) void
        +Dequeue() T
        +HasItems() bool
    }
وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نمودار کلاس

اخطار: به نظر نمی‌رسد در حال حاضر امکان تعیین چند پارامتر نوع عمومی وجود داشته باشد. برای مثال، اگر می‌خواهید یک دیکشنری را برای نگاشت از رشته‌ها به مقادیر رنگی اعلام کنید، کد C# برای آن Dictionary hexColors خواهد بود و فرض می‌کنید که کد Mermaid.js -Dictionary~string,Color~ hexColors خواهد بود.

با این حال، در زمان این نوشتن به نظر می رسد که به درستی کار نمی کند. در عوض توصیه می‌کنم به جای کاما یک زیرخط اضافه کنید و از -Dictionary~string_Color~ hexColors برای نشان دادن پارامترهای چندگانه نوع عمومی استفاده کنید.

اعضای ثابت

اعضای ثابت اعضایی هستند که به جای نمونه ای از کلاس، با خود کلاس مرتبط هستند. برای مثال، int.Parse و Console.WriteLine هر دو نمونه‌هایی از روش‌های ثابت در سی شارپ هستند.

برای نشان دادن یک متد به عنوان ثابت، یک $ پس از اعلان آن به شکل زیر اضافه کنید:

classDiagram
    class ColorManager {
        -Dictionary~string_Color~ hexColors$
        +BuildColorFromHex(string hexCode)$ Color
    }
وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نمودار کلاس

اضافه کردن یادداشت به کلاس ها

اگر می‌خواهید حاشیه‌نویسی متنی را به طور کلی به نمودار اضافه کنید، می‌توانید یک عنصر یادداشت برای سند با نحو زیر اضافه کنید:

note "This is a note for the whole diagram"

همچنین، می توانید با استفاده از نحو زیر، یک کلاس خاص را با یک یادداشت حاشیه نویسی کنید:

note for Player "This is a note on the Player class"

در اینجا این دو ویژگی در کنار هم برای یک نمودار بزرگتر آورده شده است:

classDiagram
    note "This is a note for the whole diagram"
    note for Player "This is a note on the Player class"
    class GameObject {
        +String Name
        +int PosX
        +int PosY
        +Despawn() void
    }
    class DamageableObject {
        <<abstract>>
        +int MaxHealth
        -int Health
        +IsDead() bool
        +TakeDamage(int damage) void
        +OnKilled()* void
    }
    class Player {
        -int Score
        -int LivesRemaining
        +OnKilled() void
    }
    class Monster {
        -int ThreatLevel
        -Color Color
        +MakeNoise(double decibelLevel) string
        +OnKilled() void
    }
    GameObject <|-- DamageableObject
    DamageableObject <|-- Player
    DamageableObject <|-- Monster
وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نمودار کلاس

هشدار: ویژگی یادداشت ها از زمان نگارش این مقاله نسبتاً جدید است و ممکن است در همه ویرایشگرهایی که در حال حاضر استفاده می شوند کار نکند.

مراحل بعدی

Mermaid.js دارای ویژگی های زیادی برای ایجاد نمودار کلاس است. در حالی که من شخصاً به اندازه تحصیلاتم در مقطع کارشناسی از نمودارهای کلاسی استفاده نمی کنم، ارزش این را می بینم.

به عنوان مثال، اگر شما یک کتابخانه منبع باز نگهداری می کنید، توانایی قرار دادن یک نمودار کلاسی که کلاس هایی را که از یک کلاس انتزاعی خاص به ارث می برند، قرار دهید، به سرعت به توسعه دهندگان کمک می کند تا نحوه تعامل با کد شما را به روشی بسیار بصری درک کنند.

من شما را تشویق می‌کنم که نمودارهای کلاس را در علامت‌گذاری GitHub، Polyglot Notebooks یا ویرایشگر زنده امتحان کنید و ببینید چه فکر می‌کنید.

همچنین توصیه می‌کنم اسناد Mermaid.js را برای ویژگی‌های اضافی، از جمله جزئیات سفارشی‌سازی سبک و طرح‌بندی این نمودارها، بررسی کنید.

نوشتن در مورد Mermaid.js تمام نشده است، بنابراین برای اطلاعات بیشتر در مورد نمودارهای دیگری که می توانید با استفاده از این کتابخانه خارق العاده بسازید، منتظر باشید!

نوشته های مشابه

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

دکمه بازگشت به بالا