ქსელის დიაგრამა როგორც კოდი / ქსელის დიაგრამა როგორც კოდი

ბოლო ორი წლის განმავლობაში უფრო მეტად ჩავერთე დოკუმენტაციაში. ახსნა-განმარტებითი ტექსტის დაწერა იმის შესახებ, თუ როგორ მუშაობს კონკრეტული სისტემა, ზოგადად საკმაოდ მარტივია. დიაგრამის დახატვა, რომელიც აჩვენებს ყველა ძირითად ობიექტს და ამ ობიექტებს შორის კავშირებს, ასევე საკმაოდ მარტივია.

მაგრამ ყველაზე პრობლემური ასპექტი არის ამ დოკუმენტაციის განახლება. და ტექსტი კარგი იქნებოდა, მაგრამ დიაგრამები... იმიტომ... ყველა დოკუმენტაცია არის ონლაინ, ე.ი. html ფორმატში, შემდეგ ტექსტს ახლავს gif/jpeg/png სურათები, რომლებშიც რეალურად ჩანს დიაგრამები. და დიაგრამები შედგენილია სხვადასხვა პროგრამებში, როგორიცაა Visio ან ონლაინ სერვისები a la draw.io. შემდეგ თქვენ აწარმოებთ დიაგრამას გრაფიკულ ფორმატში და ანიჭებთ მას html-ზე. Ეს მარტივია.

რა არის პრობლემა?

სქემები ჩვეულებრივ მარტივია. უფრო სწორად, არც ისე რთული. დიახ, ობიექტების რაოდენობა არის ათეული ან ორი, კავშირების რაოდენობა დაახლოებით იგივეა. პლუს ხელმოწერები, ზოგიერთი აღნიშვნა. მარტივი სქემები შეიძლება სიტყვებით იყოს აღწერილი, მაგრამ ზედმეტად რთული, აჰამ... (გ) „ვერ გაიგებენ, ბატონო“. ბევრი სქემაა, მათში ცვლილებებია საჭირო პერიოდულად, ეპიზოდურად, ე.ი. მუდმივად იმიტომ ისინი თვალყურს ადევნებენ ჩვენი პროდუქციის განვითარებას.

შეგიძლიათ ჩართოთ სერვისის html. სცადე?

Კი, რა თქმა უნდა. მაგალითად, მე მომწონს gliffy.com-ის გრაფიკა. მაგრამ ცვლილებების შესატანად, თქვენ უნდა გადახვიდეთ მესამე მხარის სერვისზე და იქ დაარედაქტიროთ. და უფრო რთულია კოლეგისთვის შესწორებების დელეგირება.

რა უნდა გავაკეთოთ?

ახლახან რეკომენდაციებში წავაწყდი Github-ზე არსებულ საცავს github.com/RaoulMeyer/diagram-as-code. დიაგრამა, როგორც კოდი. იმათ. ჩვენ აღვწერთ წრეს, რომელიც გვჭირდება js-ში. ჩვენ ვწერთ ამ js-ს პირდაპირ იმავე html-ში, სადაც არის სხვა დოკუმენტაციის ტექსტი.

სხვათა შორის, მე ვწერ დოკუმენტაციას არა მთლიანად html-ში. როგორც წესი, დოკუმენტაცია არის ფაილების ერთობლიობა მარკირებული ტექსტით, რომელიც შემდეგ გარდაიქმნება დოკუმენტაციის სრულფასოვან საიტზე ზოგიერთი ძრავის მიერ, მაგალითად, ზამთარი. ან ვიკი სისტემა.

გამოდის ძალიან მოსახერხებელი: ჩვენ დავწერეთ ტექსტი, შემდეგ იხსნება სკრიპტის ტეგი და მასში აღწერილია სქემის 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. და თუ მოგწონთ სუპერ დეტალური და რთული დიაგრამები, მაშინ აუცილებლად აღფრთოვანებული იქნებით ამ პროექტით: წადი.დახაზე.ნეტ

წყარო: www.habr.com