اخیراً من عاشق استفاده از 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 تمام نشده است، بنابراین برای اطلاعات بیشتر در مورد نمودارهای دیگری که می توانید با استفاده از این کتابخانه خارق العاده بسازید، منتظر باشید!
