कोड के रूप में नेटवर्क आरेख / कोड के रूप में नेटवर्क आरेख

पिछले कुछ वर्षों में मैं दस्तावेज़ीकरण में और अधिक शामिल हो गया हूँ। कोई विशेष प्रणाली कैसे काम करती है, इसके बारे में व्याख्यात्मक पाठ लिखना आम तौर पर काफी सरल है। एक आरेख बनाना जो सभी प्रमुख वस्तुओं और इन वस्तुओं के बीच के कनेक्शन को प्रदर्शित करेगा, भी काफी आसान है।

लेकिन सबसे समस्याग्रस्त पहलू इस दस्तावेज़ को अद्यतन रखना है। और पाठ ठीक होगा, लेकिन चित्र... क्योंकि... सभी दस्तावेज़ ऑनलाइन हैं, अर्थात एचटीएमएल प्रारूप में, तो पाठ के साथ gif/jpeg/png चित्र होते हैं, जो वास्तव में आरेख दिखाते हैं। और आरेख विभिन्न कार्यक्रमों जैसे Visio या ऑनलाइन सेवाओं a la duck.io में तैयार किए जाते हैं। फिर आप आरेख को ग्राफ़िक प्रारूप में निर्यात करें और इसे html से संलग्न करें। यह आसान है।

समस्या क्या है?

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

आप सेवा का HTML एम्बेड कर सकते हैं. या तुमने कोशिश की?

हाँ यकीनन। उदाहरण के लिए, मुझे gliffy.com के ग्राफ़िक्स पसंद हैं। लेकिन बदलाव करने के लिए, आपको किसी तृतीय-पक्ष सेवा पर जाना होगा और वहां संपादन करना होगा। और किसी सहकर्मी को सुधार सौंपना अधिक कठिन है।

क्या करना है?

हाल ही में मुझे जीथब पर अनुशंसाओं में एक भंडार मिला github.com/RaoulMeyer/diagram-as-code. कोड के रूप में आरेख. वे। हम जेएस में आवश्यक सर्किट का वर्णन करते हैं। हम इस जेएस को सीधे उसी HTML में लिखते हैं जहां अन्य दस्तावेज़ीकरण टेक्स्ट है।

वैसे, मैं दस्तावेज़ीकरण पूरी तरह से html में नहीं लिखता हूँ। आमतौर पर, दस्तावेज़ीकरण मार्कडाउन टेक्स्ट वाली फ़ाइलों का एक सेट होता है, जिसे बाद में कुछ इंजन, उदाहरण के लिए विंटर्समिथ द्वारा एक पूर्ण दस्तावेज़ीकरण साइट में परिवर्तित किया जाता है। या एक विकि प्रणाली.

यह बहुत सुविधाजनक हो जाता है: हमने पाठ लिखा है, फिर स्क्रिप्ट टैग खुलता है और इसमें योजना का जेएस कोड वर्णित है।

फिर क्या ग़लत है?

मुझे यह रिपॉजिटरी पसंद आई, लेकिन यह एकमात्र उदाहरण नहीं है जहां कोड या टेक्स्ट प्रस्तुतिकरण का उपयोग करके एक आरेख तैयार किया गया है। (लेख के अंत में उन परियोजनाओं और लेखों के लिंक होंगे जिन्हें मैंने विषय आरेख पर कोड के रूप में गूगल पर खोजा था।)

और मैं दस्तावेज़ीकरण का संपादन करने वाला अकेला व्यक्ति नहीं हूं। कभी-कभी सहकर्मी भी योगदान देते हैं - किसी शब्द को सही करना, विवरण बदलना, नई तस्वीरें डालना। 

इसलिए, मैं आरेख को पढ़ने योग्य, समझने योग्य पाठ प्रारूप में देखना चाहूंगा जिसके लिए लंबे समय तक सीखने की आवश्यकता नहीं होगी। और कुछ स्थानों पर आप नए सर्किट को जोड़ने में तेजी लाने के लिए बस कॉपी-पेस्ट भी कर सकते हैं। 

और एक अन्य सहकर्मी ने कहा कि बेशक, कोड अच्छा है, लेकिन यदि आप संरचना का उपयोग करते हैं, तो सब कुछ बहुत सख्त और अभिव्यंजक हो सकता है।

इसलिए, मैंने आरेख को कई छोटे सरणियों के एक सेट के रूप में कल्पना करने की कोशिश की जो नोड्स, कनेक्शन, नोड्स के समूह, साथ ही नोड्स के स्थान का वर्णन करते हैं। यह, मेरी विनम्र राय में, काफी सुविधाजनक निकला, हालाँकि, निश्चित रूप से, स्वाद और रंग...

किसी सारणी में यह चार्ट कैसा है?

• प्रत्येक नोड को एक पहचानकर्ता द्वारा वर्णित किया जाता है जो विशिष्ट रूप से नोड की पहचान करता है।
• आप नोड में एक आइकन भी जोड़ सकते हैं और एक शिलालेख भी जोड़ सकते हैं।
• आप दो नोड्स के बीच संबंध निर्दिष्ट कर सकते हैं.
• आरेख पर संचार के लिए, आप रंग और शिलालेख सेट कर सकते हैं।
• संचार की दिशा को स्रोत से लक्ष्य तक के रूप में परिभाषित किया गया है। और स्रोत और लक्ष्य नोड पहचानकर्ताओं द्वारा इंगित किए जाते हैं।
• किसी समूह में एक या अधिक नोड जोड़े जा सकते हैं.
• संबंध को समूह और समूह दोनों से भी निर्दिष्ट किया जा सकता है।

इन सरल नियमों का उपयोग करके, हमें निम्नलिखित चित्र प्राप्त होता है। अभी-अभी? अत्यंत।

और इसे निम्नलिखित जेएस कोड द्वारा वर्णित किया गया है। यहां मुख्य बात तत्व वस्तु है। जिसमें नोड्स इंगित किए जाते हैं - नोड्स, किनारे - कनेक्शन।
 

  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);

निःसंदेह, मैं स्वयं सर्किट का चित्र बनाने नहीं आया, लेकिन पुस्तकालय का उपयोग किया साइटोस्केप.जे.एस एक बहुत शक्तिशाली विज़ुअलाइज़ेशन टूल है. मैं अपने समाधान में संभावनाओं का केवल एक अंश ही उपयोग करता हूँ। 

ठीक है, यह एक सरल उदाहरण है. क्या यह और अधिक जटिल हो सकता है?

जी कहिये। पदों को इंगित करने के लिए, हम पदों का उपयोग करते हैं, समूहों को इंगित करने के लिए, हम समूहों में समूहों की एक सूची इंगित करते हैं, और तत्वों में स्वयं एक समूह विशेषता होती है।

और यह कोड है:

<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>

एक ओर, ऐसी योजना एक लैपटॉप पर कोड की लगभग कुछ स्क्रीन है, दूसरी ओर, संरचना एक ला जेसन आपको सादृश्य द्वारा सभी डेटा को जल्दी से भरने की अनुमति देती है और आप कॉपी-पेस्ट कर सकते हैं।

पदों को नोड्स से अलग क्यों रखा गया है?

यह अधिक आरामदायक है. पहले हम नोड्स निर्दिष्ट करते हैं। फिर हम कुछ समूहों को निर्दिष्ट कर सकते हैं और उन्हें नोड्स में इंगित कर सकते हैं। फिर हम कनेक्शन निर्दिष्ट करते हैं। और केवल तभी, जब मुख्य वस्तुएं और उनके बीच संबंध होते हैं, तो हम आरेख पर इन वस्तुओं का स्थान लेते हैं। या विपरीत।

क्या यह बिना पद के संभव है?

यह बिना पद के भी संभव है. लेकिन यह थोड़ा टेढ़ा-मेढ़ा होगा, इस विकल्प को आप उदाहरणों में देख सकते हैं। यह इस तथ्य के कारण है कि साइटोस्केप के लिए नोड्स के स्थान के लिए एक एल्गोरिदम है fcose, जो समूहों की उपस्थिति को भी ध्यान में रखता है। स्थिति निर्दिष्ट करना आरेख को अधिक नियंत्रणीय बनाता है, लेकिन आरेख के पहले ड्राफ्ट के चरण में यह स्थिति के बिना संभव है।

पदों को युद्धपोत शैली में भी निर्दिष्ट किया जा सकता है। वे। एक नोड a1 में स्थित है, और दूसरा d5 में। यह विशेष रूप से मदद करता है कि साइटोस्केप कैनवास पर वस्तुओं को चलने योग्य बनाता है, यानी। हम उन्हें इधर-उधर ले जा सकते हैं, विभिन्न लेआउट विकल्प देख सकते हैं, और फिर कोड में हमारे पसंदीदा तत्वों की व्यवस्था को ठीक कर सकते हैं।

सामान्य तौर पर, यह समझ में आता है। आप भी कोशिश कर सकते हैं?
 
बेशक, जल्दी से सर्किट बनाने के लिए, मैंने खुद को छोटा बना लिया संपादक, जो स्वयं स्कीमा को अपडेट करता है और नवीनतम संस्करण को ब्राउज़र में (लोकलस्टोरेज में) संग्रहीत करता है।

या तुमने कोशिश की? अब आप इसे अपने पेज पर जोड़ सकते हैं.

तो फिर:

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. हम कोड को उस आरेख में संपादित करते हैं जिसकी हमें आवश्यकता होती है (मुझे लगता है कि यह उल्लू का चित्र बनाने से आसान है :)

अधिक जानकारी यहां प्रोजेक्ट पेज जीथब पर.

नतीजा?

मैंने अपने लक्ष्य हासिल कर लिए - दस्तावेज़ में इनलाइन आरेख जोड़ने के लिए, प्रारूप काफी सरल और समझने योग्य है। यह सुपर सर्किट के लिए उपयुक्त नहीं है, लेकिन छोटे सर्किट के लिए जो कनेक्शन की संरचना की व्याख्या करता है, यह बिल्कुल ठीक है। आप हमेशा समय के साथ किसी चीज़ में तेज़ी से बदलाव कर सकते हैं। हां, और सहकर्मी स्वयं कटघरे में कुछ ठीक कर सकते हैं, कम से कम वस्तुओं के लिए कैप्शन, विशेष प्रशिक्षण के बिना))

क्या सुधार किया जा सकता है?

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

तुम क्या सोचते हो?
 
मुद्दों में कार्यान्वयन के लिए मेरे पास पहले से ही कई विचार हैं, आप टिप्पणियों में भी अपना विचार जोड़ सकते हैं।

• कोष
• उदाहरण
• ऑनलाइन संपादक

मेरा समाधान निश्चित रूप से समस्याओं की एक संकीर्ण श्रेणी में लागू होता है, और शायद आपको केवल कोड करके आरेख बनाने के लिए एक अधिक सुविधाजनक उपकरण मिल जाएगा - जैसा कि वे कहते हैं 'मुझे कोड के रूप में अपना आरेख दिखाओ'

1. अच्छा चयन
2. उत्तम सेवा (9 प्रकार के चार्ट ऑनलाइन संपादक)
3. बेशक, मरमेड.जे.एस
4. और यदि आपको अत्यधिक विस्तृत और जटिल चित्र पसंद हैं, तो आप निश्चित रूप से इस परियोजना की प्रशंसा करेंगे: go.drawthe.net

स्रोत: www.habr.com