🥇 कोडको रूपमा नेटवर्क रेखाचित्र / कोडको रूपमा नेटवर्क रेखाचित्र

В последние пару лет стал больше заниматься документацией. Написать поясняющий текст о том, как работает та или иная система — в целом, это достаточно просто. Нарисовать схему, на которой будут отображены все ключевые объекты, связи между этими объектами, тоже вполне легко.

तर सबैभन्दा समस्याग्रस्त पक्ष भनेको यो कागजातलाई अद्यावधिक राख्नु हो। र पाठ राम्रो हुनेछ, तर रेखाचित्र ... किनभने ... सबै कागजातहरू अनलाइन छन्, अर्थात् html ढाँचामा, त्यसपछि पाठसँग gif/jpeg/png चित्रहरू छन्, जसले वास्तवमा रेखाचित्रहरू देखाउँदछ। र रेखाचित्रहरू भिजियो वा अनलाइन सेवाहरू a la draw.io जस्ता विभिन्न कार्यक्रमहरूमा कोरिएका छन्। त्यसपछि तपाइँ रेखाचित्र ग्राफिक ढाँचामा निर्यात गर्नुहोस् र यसलाई html मा संलग्न गर्नुहोस्। यो सरल छ।

समस्या के हो?

योजनाहरू सामान्यतया सरल छन्। थप स्पष्ट रूपमा, धेरै जटिल छैन। हो, वस्तुहरूको संख्या एक दर्जन वा दुई हो, जडानहरूको संख्या लगभग समान छ। प्लस हस्ताक्षर, केही पदनामहरू। सरल योजनाहरू शब्दहरूमा वर्णन गर्न सकिन्छ, तर धेरै जटिल, अहेम... (ग) "तिनीहरूले बुझ्दैनन्, सर।" त्यहाँ धेरै योजनाहरू छन्, तिनीहरूलाई आवधिक रूपमा परिवर्तन गर्न आवश्यक छ, एपिसोडिक रूपमा, अर्थात्। लगातार, किनभने तिनीहरूले हाम्रा उत्पादनहरूको विकासलाई पछ्याउँछन्।

तपाईं सेवाको html इम्बेड गर्न सक्नुहुन्छ। तपाईंले यो प्रयास गर्नुभयो?

हो, पक्का। उदाहरण को लागी, मलाई gliffy.com बाट ग्राफिक्स मन पर्छ। तर परिवर्तनहरू गर्न, तपाईंले तेस्रो-पक्ष सेवामा जानु पर्छ र त्यहाँ सम्पादन गर्नुपर्छ। र सहकर्मीलाई सुधारहरू सुम्पन अझ गाह्रो छ।

मैले के गर्नु पर्छ?

भर्खरै मैले सिफारिसहरूमा Github मा एक भण्डार भेटें github.com/RaoulMeyer/diagram-as-code। कोडको रूपमा रेखाचित्र। ती। हामीले js मा चाहिने सर्किटको वर्णन गर्छौं। हामी यो js सिधै उही html मा लेख्छौं जहाँ अन्य कागजात पाठ छ।

वैसे, म html मा पुरा तरिकाले कागजात लेख्दैन। सामान्यतया, कागजात भनेको मार्कडाउन टेक्स्ट भएका फाइलहरूको सेट हो, जसलाई केही इन्जिनहरू, उदाहरणका लागि विन्टरस्मिथद्वारा पूर्ण-विकसित कागजात साइटमा रूपान्तरण गरिन्छ। वा विकि प्रणाली।

Получается очень удобно: вот мы написали текст, затем открывается тег script и в нем описан js код схемы.

फेरि के बिग्रियो ?

मलाई यो भण्डार मन पर्यो, तर यो एक मात्र उदाहरण होइन जहाँ कोड वा पाठ प्रतिनिधित्व प्रयोग गरेर रेखाचित्र कोरिएको छ। (लेखको अन्त्यमा मैले कोडको रूपमा विषय रेखाचित्रमा गुगल गरेको प्रोजेक्टहरू र लेखहरूको लिङ्कहरू हुनेछन्।)

र कागजात सम्पादन गर्ने म मात्र होइन। कहिलेकाहीँ सहकर्मीहरूले पनि योगदान गर्छन् - शब्द सच्याउनुहोस्, विवरण परिवर्तन गर्नुहोस्, नयाँ चित्रहरू घुसाउनुहोस्।

त्यसकारण, म रेखाचित्रलाई पढ्न सकिने, बुझ्न सकिने पाठ ढाँचामा हेर्न चाहन्छु जसलाई लामो सिकाइ कर्भको आवश्यकता पर्दैन। र केहि स्थानहरूमा तपाईले नयाँ सर्किट थप्नको लागि सजिलै प्रतिलिपि टाँस्न सक्नुहुन्छ।

र अर्को सहकर्मीले नोट गरे कि कोड पक्कै पनि राम्रो छ, तर यदि तपाइँ संरचना प्रयोग गर्नुहुन्छ भने, सबै कुरा धेरै कडा र अभिव्यक्त हुन सक्छ।

त्यसकारण, मैले नोडहरू, जडानहरू, नोडहरूको समूहहरू, साथै नोडहरूको स्थान वर्णन गर्ने धेरै साना एरेहरूको सेटको रूपमा रेखाचित्र कल्पना गर्ने प्रयास गरें। यो बाहिर निस्कियो, मेरो नम्र राय मा, धेरै सुविधाजनक, यद्यपि, निस्सन्देह, स्वाद र रंग ...

एरेमा यो चार्ट कसरी हुन्छ?

प्रत्येक नोड एक पहिचानकर्ता द्वारा वर्णन गरिएको छ जसले नोडलाई अद्वितीय रूपमा पहिचान गर्दछ।
तपाईं नोडमा प्रतिमा थप्न र शिलालेख थप्न सक्नुहुन्छ।
तपाईंले दुई नोडहरू बीचको सम्बन्ध निर्दिष्ट गर्न सक्नुहुन्छ।
रेखाचित्रमा सञ्चारको लागि, तपाइँ रङ र शिलालेख सेट गर्न सक्नुहुन्छ।
संचार को दिशा स्रोत देखि लक्ष्य को रूप मा परिभाषित गरिएको छ। र स्रोत र लक्ष्य नोड पहिचानकर्ता द्वारा संकेत गरिएको छ।
समूहमा एक वा बढी नोडहरू थप्न सकिन्छ।
Связь также можно указать и от группы, и к группе.

Пользуясь этими простыми правилами получается вот такая схема. Просто? Вполне.

А описывается она следующим js-кодом. Основное здесь — это объект elements. В котором указаны nodes — узлы, edges — связи.

  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>

एकातिर, यस्तो योजना भनेको ल्यापटपमा कोडको लगभग दुईवटा स्क्रिनहरू हो, अर्कोतर्फ, la json संरचनाले तपाईंलाई सबै डाटा एनालोजीद्वारा छिटो भर्न अनुमति दिन्छ, र तपाईं प्रतिलिपि टाँस्न सक्नुहुन्छ।

А почему positions вынесены отдельно от узлов?

यो थप सहज छ। पहिले हामी नोडहरू निर्दिष्ट गर्छौं। त्यसपछि हामी समूहहरूको एक जोडी निर्दिष्ट गर्न सक्छौं र तिनीहरूलाई नोडहरूमा संकेत गर्न सक्छौं। त्यसपछि हामी जडानहरू नामित गर्छौं। र तब मात्र, जब मुख्य वस्तुहरू र तिनीहरू बीचको जडानहरू छन्, हामी रेखाचित्रमा यी वस्तुहरूको स्थान लिन्छौं। वा उल्टो।

पद बिना यो सम्भव छ?

पद बिना यो सम्भव छ। तर यो एक सानो टुक्रा हुनेछ; तपाईं उदाहरणहरूमा यो विकल्प देख्न सक्नुहुन्छ। यो साइटोस्केप को लागी नोड को स्थान को लागी एक एल्गोरिथ्म छ भन्ने तथ्य को कारण हो 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. हामी कोडलाई हामीलाई चाहिने रेखाचित्रमा सम्पादन गर्छौं (मलाई लाग्छ कि यो उल्लू कोर्न भन्दा सजिलो छ :)

Еще подробнее на परियोजना पृष्ठ на гитхабе.

अन्तमा के भयो?

Своих целей я достиг — сделать добавление схем inline в документацию, формат достаточно простой и понятный. Для суперсхем не подойдет, а для небольших схем, поясняющих структуру связей — очень даже ничего. Всегда можно быстро подправить и что-то с течением времени поменять. Да, и коллеги могут в доке сами что-то подправить, как минимум подписи к объектам без особого обучения ))

के सुधार गर्न सकिन्छ?

निस्सन्देह, यहाँ धेरै विकल्पहरू छन्। अतिरिक्त आइकनहरू थप्नुहोस् (सबै अवस्थितहरू लिपिमा इनलाइन थपिएका छन्)। आइकनहरूको थप अभिव्यक्त सेट छनौट गर्नुहोस्। जडान लाइनको शैली निर्दिष्ट गर्न सम्भव बनाउनुहोस्। पृष्ठभूमि छवि थप्नुहोस्।

तिम्रो के बिचार छ?

मसँग पहिले नै मुद्दाहरूमा कार्यान्वयनको लागि धेरै विचारहरू छन्, तपाईं टिप्पणीहरूमा पनि थप्न सक्नुहुन्छ।

मेरो समाधान निश्चित रूपमा समस्याहरूको एक साँघुरो दायरामा लागू हुन्छ, र सायद तपाईंले केवल कोडिङ गरेर रेखाचित्रहरू कोर्नको लागि थप सुविधाजनक उपकरण पाउनुहुनेछ - जसरी तिनीहरू भन्छन् 'मलाई कोडको रूपमा तपाईंको रेखाचित्र देखाउनुहोस्'।

राम्रो छनोट
Шикарный сервис (नौ प्रकारका चार्ट अनलाइन सम्पादक)
अवश्य पनि, mermaid.js
र यदि तपाइँ सुपर विस्तृत र जटिल रेखाचित्रहरू मनपर्छ भने, तपाइँ निश्चित रूपमा यो परियोजनाको प्रशंसा गर्नुहुनेछ: go.drawthe.net

स्रोत: www.habr.com

कोडको रूपमा नेटवर्क रेखाचित्र / कोडको रूपमा नेटवर्क रेखाचित्र

एक टिप्पणी थप्न Отменить ответ