דיאגרמת רשת כקוד / דיאגרמת רשת כקוד

בשנתיים האחרונות התעסקתי יותר בתיעוד. כתיבת טקסט הסבר על אופן הפעולה של מערכת זו או אחרת היא בדרך כלל די פשוטה. ציור דיאגרמה שתציג את כל האובייקטים המרכזיים ואת הקשרים בין האובייקטים הללו הוא גם די קל.

אבל ההיבט הבעייתי ביותר הוא שמירה על התיעוד הזה מעודכן. והטקסט יהיה בסדר, אבל התרשימים... כי... כל התיעוד מקוון, כלומר. בפורמט html, אז הטקסט מלווה בתמונות gif/jpeg/png, המציגות למעשה את הדיאגרמות. ודיאגרמות מצוירות בתוכניות שונות כגון Visio או שירותים מקוונים a la draw.io. לאחר מכן אתה מייצא את התרשים לפורמט גרפי ומצרף אותו ל-html. זה פשוט.

מה הבעיה?

התוכניות בדרך כלל פשוטות. ליתר דיוק, לא מאוד מסובך. כן, מספר האובייקטים הוא תריסר או שניים, מספר החיבורים זהה בערך. בתוספת חתימות, כמה ייעודים. אפשר לתאר תוכניות פשוטות במילים, אבל מורכבות מדי, אהממ... (ג) "הם לא יבינו, אדוני." ישנן תוכניות רבות, יש לבצע בהן שינויים מעת לעת, אפיזודית, כלומר. כל הזמן, כי הם עוקבים אחר הפיתוח של המוצרים שלנו.

אתה יכול להטמיע את ה-html של השירות. ניסית את זה?

כן בטח. לדוגמה, אני אוהב את הגרפיקה של gliffy.com. אבל כדי לבצע שינויים, אתה צריך ללכת לשירות של צד שלישי ולערוך שם. וקשה יותר להאציל תיקונים לעמית.

מה לעשות?

לאחרונה נתקלתי במאגר ב-Github בהמלצות github.com/RaoulMeyer/diagram-as-code. תרשים כקוד. הָהֵן. אנו מתארים את המעגל שאנו צריכים ב-js. אנו כותבים את ה-js הזה ישירות באותו html שבו נמצא טקסט התיעוד האחר.

אגב, אני כותב תיעוד לא לגמרי ב-html. בדרך כלל, תיעוד הוא קבוצה של קבצים עם טקסט סימון, אשר מומר לאחר מכן לאתר תיעוד מלא על ידי מנוע כלשהו, ​​למשל Wintersmith. או מערכת ויקי.

זה יוצא מאוד נוח: כתבנו את הטקסט, ואז תג הסקריפט נפתח ומתואר בו קוד JS של הסכמה.

מה לא בסדר שוב?

אהבתי את המאגר הזה, אבל זו לא הדוגמה היחידה שבה מציירים דיאגרמה באמצעות קוד או ייצוג טקסט. (בסוף המאמר יהיו קישורים לפרויקטים ומאמרים שבדקתי בגוגל על ​​דיאגרמת הנושא כקוד).

ואני לא היחיד שעורך את התיעוד. לפעמים גם עמיתים תורמים - לתקן מילה, לשנות תיאור, להכניס תמונות חדשות. 

לכן, הייתי רוצה לראות את התרשים בפורמט טקסט קריא ומובן שלא ידרוש עקומת למידה ארוכה. ובמקומות מסוימים אתה יכול אפילו פשוט להעתיק-הדבק כדי לזרז הוספת מעגל חדש. 

ועמית אחר ציין שקוד הוא, כמובן, טוב, אבל אם אתה משתמש במבנה, הכל יכול להיות מאוד קפדני ואקספרסיבי.

לכן, ניסיתי לדמיין את הדיאגרמה כקבוצה של מספר מערכים קטנים המתארים צמתים, חיבורים, קבוצות של צמתים, כמו גם את מיקומם של צמתים. יצא, לעניות דעתי, די נוח, אם כי, כמובן, הטעם והצבע...

איך זה תרשים במערך?

• כל צומת מתואר על ידי מזהה שמזהה את הצומת באופן ייחודי.
• ניתן גם להוסיף סמל לצומת ולהוסיף כיתוב.
• אתה יכול לציין קשר בין שני צמתים.
• לתקשורת בתרשים, אתה יכול להגדיר את הצבע והכיתוב.
• כיוון התקשורת מוגדר ממקור ליעד. והמקור והמטרה מסומנים על ידי מזהי צומת.
• ניתן להוסיף צמתים אחד או יותר לקבוצה.
• ניתן גם לציין את הקשר הן מהקבוצה והן לקבוצה.

באמצעות הכללים הפשוטים הללו, אנו מקבלים את הדיאגרמה הבאה. רַק? דַי.

וזה מתואר על ידי קוד js הבא. העיקר כאן הוא אובייקט האלמנטים. בהם מצוינים צמתים - צמתים, קצוות - חיבורים.
 

  const elements = {
    nodes: [       // описываем узлы
      { id: 'client', type: 'smartphone', label: 'Mobile App'},
      { id: 'server', type: 'server', label: 'Main Server'},
      { id: 'db1', type: 'database', label: 'DB 1'},
      { id: 'db2', type: 'database', label: 'DB 2'},
    ],
    edges: [       // указываем связи
      { source: 'client', target: 'server', label: 'request' },
      { source: 'server', target: 'db1', label: 'request' },
      { source: 'server', target: 'db2', label: 'request' },
    ],
  };
  Diagram('scheme1', elements);

כמובן, לא המצאתי את ציור המעגל בעצמי, אלא השתמשתי בספרייה cytoscape.js הוא כלי הדמיה חזק מאוד. אני משתמש רק בחלק מהאפשרויות בפתרון שלי. 

אוקיי, זו דוגמה פשוטה. האם זה יכול להיות יותר מסובך?

כן בבקשה. לציון עמדות אנו משתמשים בעמדות, לציון קבוצות אנו מציינים רשימה של קבוצות בקבוצות, ולאלמנטים עצמם יש תכונה קבוצתית.

וזה הקוד:

<div id="scheme5" style="height:500px;width:800px;"></div>
<script>
  const elements5 = {
    groups: [
      { id: 'g1', label: 'Группа сервисов 1'},
      { id: 'g2', label: 'Группа сервисов 2'},
    ],
    nodes: [
      { id: 'man1', type: 'person', label: 'Человек'},
      { id: 'client', type: 'smartphone', label: 'Смартфон'},
      { id: 'agent-backend', type: 'server', group: 'g1', label: 'agent-backend'},
      { id: 'web', type: 'server', group: 'g1', label: 'Приложение admin'},
      { id: 'www', type: 'server', group: 'g1', label: 'страница загрузки'},
      { id: 'mongodb1', type: 'database', group: 'g1', label: 'Mongo DB 1'},
      { id: 'mongodb2', type: 'database', group: 'g1', label: 'Mongo DB 2'},
      { id: 'runner-integration1', type: 'worker', group: 'g1', label: 'отправка'},
      { id: 'runner-integration2', type: 'worker', group: 'g1', label: 'отправка'},
      { id: 'api', type: 'server', group: 'g1', label: 'API'},
      { id: 'server2', type: 'server', group:'g2', label: 'сервер'},
      { id: 'otherServer', type: 'server', group:'g2', label: 'сервер'},
      { id: 'firebase', type: 'cloud', label: 'Google Firebase'},
    ],
    edges: [
      { source: 'client', target: 'agent-backend', label: 'json', color: 'red' },
      { source: 'agent-backend', target: 'mongodb1', color: 'red' },
      { source: 'agent-backend', target: 'mongodb2',  color: 'red' },
      { source: 'mongodb1', target: 'runner-integration1', label: 'данные' },
      { source: 'mongodb2', target: 'runner-integration2', label: 'данные' },
      { source: 'mongodb1', target: 'web', label: 'данные для отображения' },
      { source: 'runner-integration1', target: 'server2', label: 'данные' },
      { source: 'runner-integration2', target: 'otherServer', label: 'данные' },
      { source: 'api', target: 'firebase', label: 'запросы', color: 'blue', },
      { source: 'firebase', target: 'client', label: 'push', color: 'blue'},
      { source: 'server2', target: 'api', label: 'уведомления', color: 'blue'},
      { source: 'man1', target: 'client', },
    ],
    positions: [
      { id: 'client', row: 2, col: 1,},
      { id: 'agent-backend', row: 2, col: 3,},
      { id: 'web', row: 6, col: 3,},
      { id: 'www', row: 1, col: 3,},
      { id: 'mongodb1', row: 1, col: 4,},
      { id: 'mongodb2', row: 2, col: 5,},
      { id: 'runner-integration1', row: 3, col: 3,},
      { id: 'runner-integration2', row: 4, col: 3,},
      { id: 'api', row: 5, col: 3,},
      { id: 'server2', row: 6, col: 7,},
      { id: 'otherServer', row: 4, col: 7,},
      { id: 'firebase', row: 5, col: 1,},
      { id: 'logger', row: 2, col: 7,},
      { id: 'crm', row: 5, col: 8,},
    ],
};
  Diagram('scheme5', elements5, {layout: 'grid'});
</script>

מצד אחד, סכמה כזו היא כמעט כמה מסכי קוד במחשב נייד, מצד שני, המבנה a la json מאפשר לך למלא את כל הנתונים באנלוגיה, במהירות ותוכל להעתיק-הדבק.

מדוע ממוקמים עמדות בנפרד מצמתים?

זה יותר נוח. ראשית אנו מציינים צמתים. לאחר מכן נוכל לציין כמה קבוצות ולציין אותן בצמתים. לאחר מכן אנו מייעדים את החיבורים. ורק אז, כאשר האובייקטים העיקריים והקשרים ביניהם נמצאים שם, אנו לוקחים על עצמנו את מיקומם של האובייקטים הללו בתרשים. או להפך.

אפשר בלי עמדות?

אפשר בלי עמדות. אבל זה יהיה קצת מקומט; אתה יכול לראות את האפשרות הזו בדוגמאות. זה נובע מהעובדה שיש אלגוריתם למיקום הצמתים עבור ציטוסקייפ fcose, שלוקח בחשבון גם נוכחות של קבוצות. ציון מיקומים הופך את הדיאגרמה לניתנת לשליטה, אך בשלב הטיוטה הראשונה של התרשים אפשר ללא מיקומים.

ניתן לציין מיקומים גם בסגנון ספינת הקרב. הָהֵן. צומת אחד ממוקם ב-a1, והשני ב-d5. זה עוזר במיוחד שציטוסקייפ הופך את האובייקטים על הבד לניידים, כלומר. אנחנו יכולים להזיז אותם, לראות אפשרויות פריסה שונות, ואז לתקן את סידור האלמנטים שאנחנו אוהבים בקוד.

באופן כללי, זה מובן. אפשר גם לנסות?
 
כמובן, כדי ליצור במהירות מעגלים, עשיתי לעצמי קטן редактор, שבעצמו מעדכן את הסכימה ומאחסן את הגרסה העדכנית ביותר בדפדפן (ב-localStorage).

ניסית את זה? כעת תוכל להוסיף אותו לדף שלך.

ואז שוב:

1. חיבור התסריט

<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>

2. הוסף קוד ל-html

<div id="scheme1" style="height:300px;width:800px;"></div>
<script>      
  const elements = {    
    nodes: [
      { id: 'client', type: 'smartphone', label: 'Mobile App'},
      { id: 'server', type: 'server', label: 'Main Server'},
      { id: 'db1', type: 'database', label: 'DB 1'},
      { id: 'db2', type: 'database', label: 'DB 2'},
    ],
    edges: [
      { source: 'client', target: 'server', label: 'request' },
      { source: 'server', target: 'db1', label: 'request' },
      { source: 'server', target: 'db2', label: 'request' },
    ],
  };
  Diagram('scheme1', elements);
</script>

3. אנחנו עורכים את הקוד לתרשים שאנחנו צריכים (אני חושב שזה קל יותר מאשר לצייר ינשוף :)

פרטים נוספים ב עמוד הפרויקט ב-github.

התוצאה?

השגתי את המטרות שלי - להוסיף דיאגרמות מוטבעות לתיעוד, הפורמט די פשוט ומובן. זה לא מתאים למעגלי על, אבל למעגלים קטנים שמסבירים את מבנה החיבורים זה בסדר גמור. אתה תמיד יכול לצבוט ולשנות משהו במהירות לאורך זמן. כן, ועמיתים יכולים לתקן משהו ברציף בעצמם, לפחות כיתובים לחפצים, ללא הכשרה מיוחדת))

מה ניתן לשפר?

יש כאן, כמובן, הרבה אפשרויות. הוסף אייקונים נוספים (כל הקיימים מתווספים בשורה לסקריפט). בחר קבוצה אקספרסיבית יותר של סמלים. אפשר לציין את סגנון קו החיבור. הוסף תמונת רקע.

מה אתה חושב?
 
יש לי כבר כמה רעיונות ליישום בנושאים, אתה יכול גם להוסיף את שלך בתגובות.

• מאגר
• דוגמאות
• עורך מקוון

הפתרון שלי בהחלט ישים בטווח צר של בעיות, ואולי תמצא כלי נוח יותר לציור דיאגרמות על ידי קידוד פשוט - כמו שאומרים 'הראה לי את הדיאגרמה שלך כקוד'

1. מבחר טוב
2. שירות נהדר (9 סוגים של עורך תרשימים מקוונים)
3. כמובן, mermaid.js
4. ואם אתה אוהב דיאגרמות סופר מפורטות ומורכבות, אז אתה בהחלט תתפעל מהפרויקט הזה: go.drawthe.net

מקור: www.habr.com