🥇Tarmoq diagrammasi kod sifatida / Tarmoq diagrammasi kod sifatida

So'nggi ikki yil ichida men hujjatlar bilan ko'proq shug'ullana boshladim. Muayyan tizim qanday ishlashi haqida tushuntirish matnini yozish odatda juda oddiy. Barcha asosiy ob'ektlar va bu ob'ektlar orasidagi bog'lanishlarni aks ettiruvchi diagramma chizish ham juda oson.

Ammo eng muammoli jihat bu hujjatlarni yangilab turishdir. Matn esa yaxshi bo'lardi, lekin diagrammalar... Chunki... barcha hujjatlar onlayn, ya'ni. html formatida, keyin matn gif/jpeg/png rasmlari bilan birga keladi, ular aslida diagrammalarni ko'rsatadi. Diagrammalar Visio yoki la draw.io onlayn xizmatlari kabi turli dasturlarda chiziladi. Keyin diagrammani grafik formatga eksport qilasiz va uni html ga biriktirasiz. Hammasi oddiy.

Muammo nimada?

Sxemalar odatda oddiy. Aniqrog'i, unchalik murakkab emas. Ha, ob'ektlar soni o'nlab yoki ikkita, ulanishlar soni taxminan bir xil. Bundan tashqari, imzolar, ba'zi belgilar. Oddiy sxemalarni so'z bilan ta'riflash mumkin, lekin juda murakkab, ahem ... (c) "ular tushunmaydilar, ser." Ko'p sxemalar mavjud, ularga vaqti-vaqti bilan, epizodik tarzda o'zgartirishlar kiritish kerak, ya'ni. doimiy, chunki ular mahsulotimizning rivojlanishini kuzatib boradilar.

Siz xizmatning html-ni joylashtirishingiz mumkin. Siz sinab ko'rdingizmi?

Ha albatta. Masalan, menga glify.com saytidagi grafiklar yoqadi. Ammo o'zgartirishlar kiritish uchun siz uchinchi tomon xizmatiga borishingiz va u erda tahrirlashingiz kerak. Va hamkasbga tuzatishlarni topshirish qiyinroq.

Nima qilish kerak?

Yaqinda men tavsiyalarda Github-da omborga duch keldim github.com/RaoulMeyer/diagram-as-code. Kod sifatida diagramma. Bular. js da bizga kerak bo'lgan sxemani tasvirlaymiz. Biz ushbu JS ni to'g'ridan-to'g'ri boshqa hujjat matni joylashgan html-ga yozamiz.

Aytgancha, men hujjatlarni to'liq html-da yozmayman. Odatda, hujjatlar - bu markirovka matni bo'lgan fayllar to'plami bo'lib, ular keyinchalik ba'zi bir dvigatel tomonidan to'liq hujjatlashtirilgan saytga aylantiriladi, masalan, wintersmith. Yoki wiki tizimi.

Bu juda qulay bo'lib chiqdi: biz matnni yozdik, keyin skript yorlig'i ochiladi va unda sxemaning JS kodi tasvirlanadi.

Yana nima bo'ldi?

Menga ushbu ombor yoqdi, lekin bu kod yoki matn tasviri yordamida diagramma chizilgan yagona misol emas. (Maqolaning oxirida men kod sifatida mavzu diagrammasi bo'yicha Google tomonidan qidirgan loyihalar va maqolalarga havolalar bo'ladi.)

Va men hujjatlarni tahrir qiladigan yagona odam emasman. Ba'zida hamkasblar ham hissa qo'shadilar - so'zni to'g'rilash, tavsifni o'zgartirish, yangi rasmlarni kiritish.

Shuning uchun men diagrammani uzoq o'rganish egri chizig'ini talab qilmaydigan o'qiladigan, tushunarli matn formatida ko'rishni xohlayman. Va ba'zi joylarda siz yangi sxema qo'shishni tezlashtirish uchun shunchaki nusxa ko'chirishingiz va joylashtirishingiz mumkin.

Va yana bir hamkasbning ta'kidlashicha, kod, albatta, yaxshi, lekin agar siz strukturadan foydalansangiz, hamma narsa juda qattiq va ifodali bo'lishi mumkin.

Shuning uchun, men diagrammani tugunlarni, ulanishlarni, tugunlar guruhlarini, shuningdek tugunlarning joylashishini tavsiflovchi bir nechta kichik massivlar to'plami sifatida tasavvur qilishga harakat qildim. Bu, mening kamtarona fikrimcha, juda qulay bo'lib chiqdi, garchi, albatta, ta'mi va rangi ...

Bu qanday qilib massivdagi diagramma?

Har bir tugun tugunni noyob identifikatsiya qiluvchi identifikator bilan tavsiflanadi.
Shuningdek, siz tugunga belgi qo'shishingiz va yozuv qo'shishingiz mumkin.
Ikki tugun o'rtasidagi munosabatni belgilashingiz mumkin.
Diagrammada aloqa qilish uchun siz rang va yozuvni o'rnatishingiz mumkin.
Aloqa yo'nalishi manbadan maqsadga qarab belgilanadi. Va manba va maqsad tugun identifikatorlari bilan ko'rsatilgan.
Guruhga bir yoki bir nechta tugun qo'shilishi mumkin.
O'zaro munosabatlar guruhdan ham, guruhdan ham belgilanishi mumkin.

Ushbu oddiy qoidalardan foydalanib, biz quyidagi diagrammani olamiz. Shunchaki? Juda.

Va u quyidagi JS kodi bilan tavsiflanadi. Bu erda asosiy narsa elementlar ob'ektidir. Qaysi tugunlarda ko'rsatilgan - tugunlar, qirralar - ulanishlar.

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

Albatta, men sxemaning chizmasini o'zim o'ylab topmadim, lekin kutubxonadan foydalandim cytoscape.js juda kuchli vizualizatsiya vositasidir. Men yechimimda imkoniyatlarning faqat bir qismini ishlataman.

OK, bu oddiy misol. Bu murakkabroq bo'lishi mumkinmi?

Ha iltimos. Pozitsiyalarni ko'rsatish uchun biz pozitsiyalardan foydalanamiz, guruhlarni ko'rsatish uchun biz guruhlardagi guruhlar ro'yxatini ko'rsatamiz va elementlarning o'zi guruh atributiga ega.

Va bu kod:

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

Bir tomondan, bunday sxema noutbukda deyarli bir nechta kod ekranlari bo'lsa, boshqa tomondan, a la json tuzilishi barcha ma'lumotlarni analogiya bo'yicha tezda to'ldirishga imkon beradi va siz nusxa ko'chirishingiz va joylashtirishingiz mumkin.

Nima uchun pozitsiyalar tugunlardan alohida joylashtirilgan?

Bu qulayroq. Avval biz tugunlarni aniqlaymiz. Keyin biz bir nechta guruhlarni belgilashimiz va ularni tugunlarda ko'rsatishimiz mumkin. Keyin biz ulanishlarni belgilaymiz. Va shundan keyingina, asosiy ob'ektlar va ular orasidagi bog'lanishlar mavjud bo'lganda, biz diagrammada ushbu ob'ektlarning joylashishini olamiz. Yoki aksincha.

Lavozimsiz mumkinmi?

Bu lavozimlarsiz ham mumkin. Ammo u biroz g'ijimlangan bo'ladi, bu variantni misollarda ko'rishingiz mumkin. Bu sitoskap uchun tugunlarning joylashuvi algoritmi mavjudligi bilan bog'liq fcose, bu ham guruhlarning mavjudligini hisobga oladi. Joylarni ko'rsatish diagrammani yanada boshqariladigan qiladi, lekin diagrammaning birinchi loyihasi bosqichida pozitsiyalarsiz mumkin.

Lavozimlarni Battleship uslubida ham belgilash mumkin. Bular. bitta tugun a1da, ikkinchisi esa d5da joylashgan. Ayniqsa, cytoscape tuvaldagi ob'ektlarni harakatga keltirishiga yordam beradi, ya'ni. biz ularni ko'chirishimiz, turli xil tartib variantlarini ko'rishimiz va keyin kodda bizga yoqadigan elementlarning joylashishini tuzatishimiz mumkin.

Umuman olganda, bu tushunarli. Siz ham sinab ko'rishingiz mumkinmi?

Albatta, sxemalarni tezda yaratish uchun men o'zimni kichik qildim muharriri, bu o'zi sxemani yangilaydi va brauzerda so'nggi versiyani saqlaydi (localStorage-da).

Siz sinab ko'rdingizmi? Endi uni sahifangizga qo'shishingiz mumkin.

Keyin yana:

1. Skriptni ulash

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

2. HTML-ga kod qo'shing

<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. biz kodni kerakli diagrammaga o'zgartiramiz (menimcha, bu boyqush chizishdan osonroq :)

Batafsil ma'lumot saytida loyiha sahifasi github-da.

Nima oxir-oqibat?

Men maqsadlarimga erishdim - hujjatlarga inline diagrammalarni qo'shish, format juda oddiy va tushunarli. Bu super sxemalar uchun mos emas, lekin ulanishlar tuzilishini tushuntiruvchi kichik sxemalar uchun bu mutlaqo yaxshi. Siz har doim tez o'zgartirishingiz va vaqt o'tishi bilan biror narsani o'zgartirishingiz mumkin. Ha, va hamkasblar o'zlari dockda biror narsani tuzatishi mumkin, hech bo'lmaganda ob'ektlar uchun taglavhalar, maxsus tayyorgarliksiz))

Nimani yaxshilash mumkin?

Albatta, bu erda juda ko'p variantlar mavjud. Qo'shimcha piktogramma qo'shing (barcha mavjudlari skriptga qatorga qo'shiladi). Aniqroq piktogramma to'plamini tanlang. Ulanish liniyasining uslubini belgilashga imkon bering. Fon rasmini qo'shing.

Siz nima deb o'ylaysiz?

Muammolarni amalga oshirish uchun menda allaqachon bir nechta g'oyalar bor, siz o'zingiznikini sharhlarda qo'shishingiz mumkin.

Mening yechimim, shubhasiz, tor doiradagi muammolar uchun qo'llaniladi va ehtimol siz ularni oddiygina kodlash orqali diagrammalarni chizish uchun qulayroq vositani topasiz - ular aytganidek, "diagrammangizni kod sifatida ko'rsating"

Yaxshi tanlov
Ajoyib xizmat (9 turdagi diagrammalarning onlayn muharriri)
Albatta, mermaid.js
Va agar siz juda batafsil va murakkab diagrammalarni yoqtirsangiz, unda siz ushbu loyihaga qoyil qolasiz: go.drawthe.net

Manba: www.habr.com

Kod sifatida tarmoq diagrammasi / kod sifatida tarmoq diagrammasi

a Izoh qo'shish Bu savolga javob bekor