نمودار به عنوان کد: نمودارهای توالی UML با PlantUML و VPasCode

یک UML نمودار توالینشان می‌دهد که شرکت‌کنندگان چگونه در طول زمان با یکدیگر تعامل دارند. این برای مستندسازی یک مورد استفاده، جریان API، فرآیند کسب‌وکار، یا سناریوی سیستم. زمان معمولاً از بالا به پایین حرکت می‌کند؛ قرارگیری افقی نشان می‌دهد که چه کسی مشارکت دارد، نه یک اندازه‌گیری دقیق از زمان سپری‌شده.

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

۱. ساختار پایه

یک نمودار توالی PlantUMLبا @startuml و با @enduml شرکت‌کنندگان معمولاً قبل از پیام‌ها فهرست می‌شوند تا بتوانید نام و ترتیب آن‌ها را کنترل کنید.

@startuml
نقش مشتری
شرکت‌کننده مرورگر
شرکت‌کننده «API سفارش» به عنوان API
پایگاه داده «پایگاه داده سفارش» به عنوان DB

مشتری -> مرورگر: ثبت سفارش
مرورگر -> API: POST /orders
API -> DB: ذخیره سفارش
DB --> API: شناسه سفارش
API --> مرورگر: 201 Created
مرورگر -> مشتری: نمایش تأیید
@enduml

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

۲. خواندن پیام‌ها و زمان

هر پیام به صورت یک فرستنده، یک پیکان، یک گیرنده و یک برچسب نوشته می‌شود. ترتیب خطوط پیام، ترتیب عمودی آن‌ها را در نمودار تعیین می‌کند.

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

• --> یک پیکان خط‌چین است که اغلب برای پاسخ یا بازگشت استفاده می‌شود.

• ->> و -->> در سبک‌های رایج PlantUML از سرپیکان‌های باز استفاده می‌کنند.

• : متن برچسب پیام را اضافه می‌کند.

یک قرارداد ثابت برای فراخوانی‌ها و پاسخ‌ها انتخاب کنید. نمودارهای UML یک تعامل را بیان می‌کنند؛ آن‌ها به‌طور خودکار تضمین نمی‌کنند که پیاده‌سازی از پروتکل به تصویر کشیده شده پیروی می‌کند.

۳. فعال‌سازی‌ها و عمر شرکت‌کنندگان

فعال‌سازی‌ها می‌توانند نشان دهند که یک شرکت‌کننده چه زمانی در حال انجام کار است. از activate و غیرفعال‌سازی، یا شکل کوتاه‌شده‌ی++ و -- روی پیکان‌های پیام.

@startuml
actor User
participant "Login API" as API
database Users

User -> API: Submit credentials
activate API
API -> Users: Find account
activate Users
Users --> API: Account record
deactivate Users
API --> User: Login result
deactivate API
@enduml

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

۴. شرایط، گزینه‌ها و تکرار

برای نمایش جریان کنترل از قطعات ترکیبی استفاده کنید. کلمه کلیدی fragment بلوک را آغاز می‌کند، else گزینه‌ها را در موارد قابل‌اجرا جدا می‌کند و end آن را می‌بندد. شرایط گارد در کروشه‌ی مربعی قرار می‌گیرند.

مسیرهای جایگزین: alt و else

@startuml
actor کاربر
participant "API ورود" به عنوان API
database کاربران

کاربر -> API: ارسال نام کاربری و رمز عبور
API -> کاربران: بررسی اعتبارها
کاربران --> API: نتیجه تطبیق

alt [اعتبارها معتبر]
  API --> کاربر: بازگرداندن توکن نشست
else [اعتبارها نامعتبر]
  API --> کاربر: بازگرداندن خطای احراز هویت
end
@enduml

altمناسب است زمانی که مسیرها متقابل‌الاستثنا هستند. از برچسب‌هایی استفاده کنید که شرایط را شفاف سازند.

رفتار اختیاری: opt

@startuml
actor مشتری
participant پرداخت
participant "سرویس ایمیل" به عنوان Email

مشتری -> پرداخت: تکمیل خرید
پرداخت --> مشتری: تأیید سفارش

opt [مشتری در ایمیل ثبت‌نام کرده است]
  پرداخت -> Email: ارسال رسید
  Email --> پرداخت: پذیرفته شد
end
@enduml

تکرار: حلقه

@startuml
participant "کار دسته‌ای" به عنوان Job
participant "API پرداخت" به عنوان API

loop [برای هر پرداخت در انتظار]
  Job -> API: ارسال پرداخت
  API --> Job: نتیجه پرداخت
end
@enduml

عمل تکراری را درون قطعه قرار دهید و شرط یا محدوده حلقه را به وضوح بیان کنید.

۵. تعاملات موازی و گروهی

از par زمانی که تعاملات به صورت همزمان رخ می‌دهند یا ترتیب آن‌ها اهمیت ندارد. از group برای برچسب‌گذاری مجموعه‌ای از پیام‌ها بدون اشاره به ساختار خاصی از جریان کنترل استفاده کنید.

@startuml
participant "Order Service" as Orders
participant "Inventory Service" as Inventory
participant "Notification Service" as Notify

Orders -> Orders: Order accepted

par Reserve stock
  Orders -> Inventory: Reserve items
  Inventory --> Orders: Reservation result
else Notify customer
  Orders -> Notify: Send order update
  Notify --> Orders: Accepted
end
@enduml

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

۶. یادداشت‌ها، ارجاعات و گروه‌بندی بصری

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

@startuml
actor Customer
participant "Checkout UI" as UI
participant "Payment Service" as Pay
participant "Fraud Check" as Fraud

Customer -> UI: Pay for order
UI -> Pay: Authorize payment
Pay -> Fraud: Assess transaction

note right of Fraud
  Risk rules are maintained
  outside this interaction.
end note

Fraud --> Pay: Risk result
Pay --> UI: Authorization result
UI --> Customer: Show result
@enduml

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

۷. ایجاد و اصلاح نمودارها در VPasCode

VPasCode ویرایش PlantUML با نمایش زنده را پشتیبانی می‌کند، همچنین تولید نمودار با کمک هوش مصنوعی، اصلاح کد و اصلاح نحو. رابط دقیق و در دسترس بودن ویژگی‌های آن ممکن است تغییر کند، اما گردش کار کلی به این صورت است:

1. VPasCode را باز کنید و PlantUML را انتخاب یا وارد کنید.

2. تعامل را توصیف کنید یا یک پیش‌نویس PlantUML را در ویرایشگر پیست کنید.

3. در حالی که منبع را اصلاح می‌کنید، پیش‌نمایش رندر شده را بررسی کنید.

4. از هوش مصنوعی بخواهید تغییر خاصی انجام دهد، مانند «اضافه کردن مسیری برای اعتبارنامه‌های نامعتبر با استفاده از alt.”

5. کد و نمودار حاصل را از نظر نحو و صحت سیستم بررسی کنید.

6. نمودار نهایی را با استفاده از گزینه‌های موجود در ویرایشگر صادر یا به اشتراک بگذارید.

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

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

کد تولید شده را به عنوان یک پیش‌نویس در نظر بگیرید. بررسی کنید که بازیگران، فلش‌ها، شرایط و مسیرهای خطا بازتاب‌دهنده سیستم واقعی باشند—نه صرفاً یک جریان منطقی به نظر رسیده.

۸. یک مثال کامل‌تر: پرداخت با شکست پرداخت

این مثال ترکیبی از نام‌های مستعار بازیگران، فعال‌سازی‌ها و یک مسیر جایگزین است.

@startuml
عنوان: تسویه حساب و مجوز پرداخت

نقش مشتری
مرز "رابط کاربری تسویه حساب" به عنوان UI
کنترل "سرویس سفارش" به عنوان Orders
شرکت‌کننده "درگاه پرداخت" به عنوان Pay
پایگاه داده "پایگاه داده سفارش" به عنوان DB

مشتری -> UI: ارسال تسویه حساب
UI -> Orders: ایجاد سفارش در انتظار
فعال‌سازی Orders

Orders -> DB: ذخیره سفارش در انتظار
DB --> Orders: شناسه سفارش

Orders -> Pay: مجوز پرداخت
فعال‌سازی Pay

alt [پرداخت تأیید شد]
  Pay --> Orders: کد مجوز
  غیرفعال‌سازی Pay

  Orders -> DB: علامت‌گذاری سفارش به عنوان تأیید شده
  DB --> Orders: به‌روزرسانی
  Orders --> UI: سفارش تأیید شد
  UI --> مشتری: نمایش تأیید
else [پرداخت رد شد]
  Pay --> Orders: دلیل رد
  غیرفعال‌سازی Pay

  Orders -> DB: علامت‌گذاری سفارش به عنوان ناموفق
  DB --> Orders: به‌روزرسانی
  Orders --> UI: پرداخت رد شد
  UI --> مشتری: نمایش گزینه تلاش مجدد
end

غیرفعال‌سازی Orders
@enduml

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

۹. راهنمای عملی مدل‌سازی

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

• شرکت‌کنندگان را بر اساس مسئولیت نام‌گذاری کنید.ترجیحاً از برچسب‌هایی مانند “”سرویس سفارش" یا “”درگاه پرداخت"به جای برچسب‌های مبهم مانند “”سیستم".

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

• از برچسب‌های پیام واضح استفاده کنید. یک عملیات، رویداد یا نتیجه مهم را شامل کنید؛ از برچسب‌هایی که صرفاً «فرآیند» را بیان می‌کنند، پرهیز کنید.

• مسیرهای شکست مهم را مدل‌سازی کنید.هنگامی که زمان‌بندی‌های مرتبط، رد شدن‌ها، تلاش‌های مجدد یا شکست‌های اعتبارسنجی بر سناریو تأثیر می‌گذارند، آن‌ها را شامل کنید.

• از قطعات به‌طور دقیق استفاده کنید. altبه معنای مسیرهای جایگزین است، optبه معنای رفتار اختیاری است، loopبه معنای تکرار است و parبه معنای رفتار موازی است.

• از نویزهای پیاده‌سازی پرهیز کنید.مگر اینکه مخاطبان به آن نیاز داشته باشند، هرگز هر روش getter، روش داخلی یا جزئیات سطح پایین را نموداری نکنید.

• منبع را قابل نگهداری نگه دارید.برای نام‌های طولانی از نام‌های مستعار استفاده کنید، از نام‌گذاری یکسان بهره ببرید و برای فرضیات مهم از توضیحات یا یادداشت‌های کوتاه استفاده کنید.

۱۰. خطاهای رایج و چک‌لیست بازبینی

اگر نمودار به درستی نمایش داده نشد، بررسی کنید که @startuml و @enduml وجود دارند، بلوک‌های شکلی دارای end دستورات، از نام‌های مستعار به‌صورت یکسان استفاده شده و تمام نقاط پایان پیام به شرکت‌کنندگان تعریف‌شده اشاره می‌کنند. همچنین بررسی کنید که آیا به‌طور تصادفی سینتکس از یک زبان نموداری دیگر در سورس PlantUML پیست شده است یا خیر.

قبل از اشتراک‌گذاری، دو مورد را بررسی کنید:

• سینتکس:آیا نمودار رندر می‌شود؟ آیا بلوک‌های شکلی بسته شده‌اند؟ آیا شرکت‌کنندگان و نام‌های مستعار یکسان هستند؟

• معنا:آیا شرکت‌کنندگان و جهت پیام‌ها صحیح هستند؟ آیا مسیرهای خطای مهم گنجانده شده‌اند؟ آیا سیستم‌های خارجی و انبارهای داده به‌دقت نمایش داده شده‌اند؟

قوی‌ترین روند نمودار-به‌عنوان-کدمنبع قابل‌خواندن، بازخورد بصری سریع و بررسی دامنه را ترکیب می‌کند. PlantUML کنترل صریحی بر نمادگذاری تعامل ارائه می‌دهد، در حالی که VPasCodeمی‌تواند سرعت پیش‌نویس و تکرار را افزایش دهد؛ اما مرجع نهایی در مورد دقت نمودار، همچنان رفتار سیستمی است که قرار است توصیف کند.

This post is also available in Deutsch, English, Español, Français, Bahasa Indonesia, 日本語, Polski, Portuguese, Ру́сский, Việt Nam, 简体中文 and 繁體中文.