مخططات ميرماد هيكل المستند باللغة الماركداون دون إجراء أي انقرات

رسمك التخطيطي كان دقيقًا عندما رسمته، وكان ذلك منذ ثلاث مراحل. الآن يعيش في وثيقة جوجل مشتركة لا يُحدث فيها أي تحديث، والمهندس الذي بنى الخدمة التي يصفها قد انتقل إلى فريق آخر. هل يبدو مألوفًا؟

تُعيد ميرماد هذه المشكلة من الجهة المعاكسة. بدلًا من لوحة تفاعلية يمكن تمريرها خارج مكتبة الكود، تُكتب الرسومات كنص — بنية مارك داون بسيطة — تُوجد في ملفات الـ README، وتُتحكم بها مع الكود، وتُعرض في أي مكان يُعرض فيه مارك داون. عندما تتغير البنية، تُغيّر ملف نصي واحد. يُخبر التغيير عن كل شيء.

ما هو ميرماد (وأيهما يهم أن تكون الرسومات كودًا)

ميرماد هو لغة مفتوحة المصدر لرسم الرسومات التي تُحوّل الرسومات من نص بسيط. تُكتب مخططات التدفق في مربع نصي مُحاط؛ ثم يُحوّلها مُعدّل (أو مُعرض يدعم ميرماد) إلى مخطط SVG. لا حاجة لحسابات، لا حاجة لخطوات تصدير، ولا "لا يدعم هذا الجهاز تنسيق الرسمة".

تُحقق الطريقة "الرسومات ككود" فوائدها من طرق ملموسة كالتالي:

• التحكم في النسخ — توجد الرسومات في جيت. يمكنك مقارنة النسخ، وإعادة تعيينها، وربطها بطلب تغيير الكود الذي تصفه.
• لا توجد ارتباطات مع مزود معين — النص بسيط وقابل للنقل. يمكنك تغيير مُعدّل الرسم، أو تطوير الملف، أو تصديره إلى كونفلونس، فالمصدر دائمًا قابل للقراءة.
• مُقرب من الكود — أن يكون المخطط في نفس الملف الذي يصفه الخدمة يزيد من احتمال أن يبقى دقيقًا مقارنةً برسومات توجد في وثيقة مشتركة.
• مُناسب للتشغيل التلقائي — يمكنك إنشاء نص ميرماد من الكود (مخططات قواعد البيانات، مواصفات واجهات الخدمة، خطوط إنتاج) باستخدام سيناريوهات أو نماذج ذكاء اصطناعي.

قبل البدء في أنواع الرسومات، يمكنك معاينة أي نص ميرماد فورًا — دون الحاجة إلى تثبيت محلي — باستخدام مُعدّل ميرماد على iotools.cloud. الصق، رؤية النتيجة، واجعل التغييرات. استخدمه مع هذا الدليل لتشغيل كل مثال بشكل حي.

مخططات التدفق: المُستخدم الأساسي

تُعدّ مخططات التدفق النوع الأكثر شيوعًا من مخططات ميرماد، ولها سبب جيد — تُعالج كل شيء من أشجار القرار البسيطة إلى تدفقات متعددة الخدمات. إليك البنية التي تغطي 90% من الاستخدامات الواقعية:

flowchart TD
    A[User submits form] --> B{Validation passes?}
    B -- Yes --> C[Save to database]
    B -- No --> D[Return error to client]
    C --> E[Send confirmation email]
    E --> F([End])

أشياء مهمة يجب معرفتها حول بنية مخطط التدفق:

• اتجاه: TD (من الأعلى إلى الأسفل)، LR (من اليسار إلى اليمين)، BT (من الأسفل إلى الأعلى)، RL (من اليمين إلى اليسار)
• أشكال العقد: [rectangle], (rounded), ([stadium]), {diamond}, ((circle)), [(cylinder)]
• مُلصقات الحواف: -- label --> أو -->|label|
• مُجموعات: تُجمع العقد المرتبطة بوضوح بصري

تُستخدم مجموعات بشكل خاص لعرض حدود الخدمات:

flowchart LR
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    UI --> API
    API --> DB

مخططات التسلسل: عرض سلسلة مكالمات واجهة الخدمة

تُعدّ مخططات التسلسل الأداة المناسبة عندما تحتاج إلى عرض تسلسل التفاعلات بين الأنظمة — سلسلة مكالمة واجهة، تسلسل تحقق الهوية، تسلسل ويب سكربت. تُظهر التسلسلات وضوحًا في الوقت والمسؤولية بطريقة لا يمكن لرسم التدفق أن يفعله.

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Users DB

    Client->>API Gateway: POST /login {email, password}
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Users DB: SELECT user WHERE email=?
    Users DB-->>Auth Service: User record
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK {token}

السهام الصلبة (->>) تمثل الطلبات؛ السهام المُقطعة (-->>) تمثل الردود. تُحدد participant الإعلانات ترتيب مربعات الظهور في أعلى المخطط. يمكنك أيضًا استخدام actor لأصحاب البشر، activate/deactivate لإظهار وقت المعالجة، و loop أو alt مربعات لسلسلة شروط.

مخططات العلاقة بين الكيانات: مخططات قواعد البيانات في الوثائق

يجب أن توجد مخططات العلاقة بين الكيانات في كل وثيقة تُستخدم لقاعدة بيانات. تُغطي بنية ميرماد للعلاقة بين الكيانات بشكل نظيف وتحتوي على مفهوم الربط من البداية:

erDiagram
    USER {
        int id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

مُلاحظة الربط: || مُتَوازٍ تمامًا، o| مُتَوازٍ أو واحد، o{ مُتَوازٍ أو كثيرة، |{ مُتَوازٍ أو كثيرة. يُوضع مُلصق العلاقة ("مواقع"، "يحتوي") داخل علامة تنصيص في النهاية.

مخططات الحالة: نمذجة السلاسل والآليات

عندما يكون لديك كيان يتحرك من حالة إلى أخرى — طلب، اشتراك، مهمة إنتاجية — فإن مخطط الحالة أكثر دقة من مخطط التدفق. تُمثّل بنية ميرماد للحالة بشكل مباشر كيف تُعرف آلة الحالة في الكود:

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : payment received
    Processing --> Shipped : warehouse picks order
    Shipped --> Delivered : carrier confirms
    Shipped --> Returned : customer initiates return
    Delivered --> [*]
    Returned --> Refunded : refund processed
    Refunded --> [*]

[*] تُحدد بداية الحالة ونهايتها. تنقل الحالة الحدث الذي يُحفّزها. يمكنك تضمين حالات داخل حالات مركبة ووضع note مربعات لملصق الحالة مع سياق إضافي.

مخططات الأنواع: هيكلية موجهة للوثائق المقدمة للمهندسين

تُستخدم مخططات الأنواع بشكل أفضل عند تدريب المهندسين على مكتبة موجهة أو وصف نموذج مجال. تغطي ميرماد التوريث، الواجهات، التجميع، وتوقيعات الأطراف:

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +boolean isIndoor
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends

مُحددات الوضوح تتبع معيار UML: + عامة، - خاصة، # محمية. تغطي سهام العلاقة الترابط (-->)، التوريث (<|--)، التجميع (*--)، والانسجام (o--).

أين تُظهر ميرماد الدعم المُدمج

النقطة الأساسية لميرماد هي دعمها المدمج في الأدوات التي يستخدمها المطورون بالفعل:

• جيثب — تُعرض مربعات ميرماد المُحاطة في الـ README، والمشاكل، ووصف طلبات التحديث، والوكيتات اعتبارًا من 2022.```mermaid— الدعم المدمج لمُلفات مارك داون والوكيتات.
• جِتْلَب نوتين
• — صق مربع نص ميرماد في مربع نص مُحدد كـ "ميرماد" وستُعرض بشكل مباشر. — تم تطوير مُساعد مُعرض مارك داون لدعم ميرماد يُعرض الرسومات في لوحة التنبؤ المدمجة.
• فيديو سي --- — تُعرض ميرماد بشكل مدمج دون الحاجة إلى تثبيت.
• Obsidian دوكوساوس، مك دوكس، أسترو
• — توجد مُلحقات ميرماد لجميع المُولدات الثابتة الرئيسية. كونفلونس
• — من خلال تطبيق مخططات ميرماد لكونفلونس. إذا كُتبت الوثائق التي ستسقط في جيت هاب أو جيت لاب، فإن مخططات ميرماد تعمل بشكل مدمج دون أي تكوين.

مُشكلات ومتى يجب استخدام شيء آخر

ميرماد ليس مثاليًا في كل الظروف. هناك بعض الأمور التي يجب مراقبتها:

مخططات معقدة

• — لا تُنتج خوارزمية ترتيب ميرماد نتائج نظيفة دائمًا في الرسومات الكبيرة. إذا كان لديك 50 عقدة أو أكثر مع العديد من الحواف المتقاطعة، فقد تحتاج إلى إعادة ترتيب المخطط أو تقسيمه يدويًا. عرض ميرماد في كونفلونس
• — لا يدعم كونفلونس المُدمج ميرماد؛ تحتاج إلى تطبيق مدفوع. إذا كان فريقك يعيش في كونفلونس، فعليك تخصيص ميزانية لهذا أو استخدام دايو. أنواع مخططات غير معيارية
• — مخططات الشبكات، مخططات التوزيع، ومخططات C4 للبنية تحتاج إلى حلول أو لا تُدعم بشكل جيد. التحكم في التصميم
• — خيارات التصميم المتوفرة في ميرماد محدودة. إذا كنت بحاجة إلى مخططات مُبرمجة بونات مخصصة للون والخطوط، فستستغرق وقتًا في مواجهة مُعدّل الرسم. البدائل الرئيسية التي يجب معرفتها:

بلاينوومل

• — بنية قديمة، وصيغة مُفصّلة، لكنها تدعم مزيدًا من معايير UML وتحظى بتكامل أفضل مع كونفلونس. يتطلب تثبيت جافا أو مُعالج مُركّب. د2
• — أداة جديدة للرسومات ككود مع تحكم أفضل في التصميم وتحسين معالجة الرسومات الكبيرة. لا تمتلكها مُستوى تبني مقارنة مع ميرماد، لكنها تنمو بسرعة. دايو / إكسكاليدرا
• — أدوات بيئة لمن يحتاج إلى تحكم بصري دقيق ولا يرغب في أن يعيش المخطط خارج التحكم المُحكم. لأغلب الوثائق المُعدّة للمطورين — وثائق الخدمة، سلسلة واجهات الخدمة، دليل التدريب — تغطي ميرماد الاستخدام بشكل جيد، والدعم المدمج في جيت هاب وحده يجعلها تستحق التعلم.

معاينة ميرماد دون تثبيت أي شيء

إذا كنت تجرب مصطلحات الرسم أو ترغب في مشاركة مخطط مع شخص لا يمتلك مُعدّل مُثبت محليًا، فإن

يُقدّم لك عرضًا حيًا بدون تسجيل، بدون تثبيت، ولا تكوين. صق نص ميرماد، رؤية المخطط المُحوّل، وانسخ النتيجة. مُعدّل ميرماد على iotools.cloud مفيد لفحص بنية الرسم قبل التسجيل، مشاركة نسخة مُحوّلة في رسالة سلوك، أو تجريب مخطط سبق أن تضعه في ملف الـ README.

ابدأ بـ مخطط تدفق

إذا لم تكتب مخطط ميرماد من قبل، ابدأ بـ مخطط تدفق. اختر عملية في مكتبة الكود التي كنت ترغب في توثيقها — دورة طلب، مهمة خلفية، سلسلة تطوير — وابنِها في صيغة ميرماد خلال 10 دقائق. صقها في ملف الـ README في مربع نص مُحاط وانسخه. سينتقل جيت تلقائيًا إلى عرضه.

هذا المخطط الواحد، المُحكم بالنسخة ويبقى مجاورًا للكود الذي يصفه، يساوي أكثر من وثيقة تُعرض في مُشاركة لا يثق بها. ```mermaid أوقف واندفع به. سينتقله جيث Hub تلقائيًا.

الرسم البياني هذا، المُحكم بواسطة نظام التحكم في النسخ، ويوجد بجانب الكود الذي يصفه، يساوي أكثر من عرض تقديمي لا يُثق به.

قد يعجبك أيضاً