Ցանցային դիագրամ որպես կոդ / Ցանցային դիագրամ որպես կոդ

Վերջին մի քանի տարիների ընթացքում ես ավելի շատ եմ զբաղվել փաստաթղթավորման մեջ: Բացատրական տեքստ գրելն այն մասին, թե ինչպես է գործում որոշակի համակարգը, ընդհանուր առմամբ, բավականին պարզ է: Դիագրամ գծելը, որը կցուցադրի բոլոր հիմնական օբյեկտները և այդ օբյեկտների միջև կապերը, նույնպես բավականին հեշտ է:

Բայց ամենախնդրահարույց կողմը այս փաստաթղթերի արդիականացումն է: Իսկ տեքստը լավ կլիներ, բայց դիագրամները... Որովհետև... բոլոր փաստաթղթերը առցանց են, այսինքն. html ձևաչափով, ապա տեքստին ուղեկցում են gif/jpeg/png նկարներ, որոնք իրականում ցույց են տալիս գծապատկերները։ Իսկ դիագրամները գծվում են տարբեր ծրագրերում, ինչպիսիք են Visio-ն կամ առցանց ծառայությունները a la draw.io: Այնուհետև դուք արտահանում եք դիագրամը գրաֆիկական ձևաչափի և կցում այն ​​html-ին: Դա պարզ է.

Որն է խնդիրը.

Սխեմաները սովորաբար պարզ են. Ավելի ճիշտ՝ ոչ շատ բարդ։ Այո, օբյեկտների թիվը մեկ-երկու տասնյակ է, միացումների թիվը մոտավորապես նույնն է։ Գումարած ստորագրություններ, որոշ նշանակումներ: Պարզ սխեմաները կարելի է նկարագրել բառերով, բայց չափազանց բարդ, հըմ... (գ) «չեն հասկանա, պարոն»։ Կան բազմաթիվ սխեմաներ, դրանցում պետք է փոփոխություններ կատարել պարբերաբար, էպիզոդիկ, այսինքն. անընդհատ, քանի որ նրանք հետևում են մեր արտադրանքի զարգացմանը:

Դուք կարող եք տեղադրել ծառայության html-ը: Դուք փորձե՞լ եք այն:

Այո իհարկե. Օրինակ, ինձ դուր է գալիս gliffy.com-ի գրաֆիկան: Բայց փոփոխություններ անելու համար հարկավոր է գնալ երրորդ կողմի ծառայություն և խմբագրել այնտեղ: Եվ ավելի դժվար է ուղղումներ պատվիրակել գործընկերոջը:

Ինչ անել?

Недавно на гитхабе мне попался в рекомендациях репозиторий github.com/RaoulMeyer/diagram-as-code. Դիագրամը որպես կոդ: Նրանք. մենք նկարագրում ենք մեզ անհրաժեշտ սխեման js-ում: Մենք գրում ենք այս js-ը անմիջապես նույն html-ում, որտեղ գտնվում է փաստաթղթավորման մյուս տեքստը:

Ի դեպ, փաստաթղթերը գրում եմ ոչ ամբողջությամբ html-ով։ Սովորաբար, փաստաթղթերը ֆայլերի մի շարք են, որոնց տեքստը նշում է, որն այնուհետև փոխակերպվում է ամբողջական փաստաթղթային կայքի՝ ինչ-որ շարժիչի միջոցով, օրինակ՝ ձմեռային: Կամ վիքի համակարգ։

Շատ հարմար է ստացվում՝ մենք գրել ենք տեքստը, հետո բացվում է script թեգը և դրանում նկարագրված է սխեմայի JS կոդը։

Էլի ի՞նչ կա:

Ինձ դուր եկավ այս պահոցը, բայց սա միակ օրինակը չէ, որտեղ դիագրամը գծվում է կոդով կամ տեքստային ներկայացմամբ: (Հոդվածի վերջում կլինեն հղումներ դեպի նախագծեր և հոդվածներ, որոնք ես Google-ում փնտրել եմ թեմայի դիագրամը որպես կոդ):

Եվ ես միակը չեմ, ով խմբագրում է փաստաթղթերը: Երբեմն գործընկերները նույնպես նպաստում են՝ ուղղել բառը, փոխել նկարագրությունը, տեղադրել նոր նկարներ: 

Հետևաբար, ես կցանկանայի տեսնել դիագրամը ընթեռնելի, հասկանալի տեքստի ձևաչափով, որը չի պահանջի երկար ուսուցման կոր: Եվ որոշ տեղերում դուք կարող եք նույնիսկ պարզապես պատճենել-տեղադրել՝ նոր շղթա ավելացնելն արագացնելու համար: 

Եվ մեկ այլ գործընկեր նկատեց, որ կոդը, իհարկե, լավն է, բայց եթե դուք օգտագործում եք կառուցվածքը, ամեն ինչ կարող է լինել շատ խիստ և արտահայտիչ։

Հետևաբար, ես փորձեցի պատկերացնել դիագրամը որպես մի քանի փոքր զանգվածների մի շարք, որոնք նկարագրում են հանգույցները, կապերը, հանգույցների խմբերը, ինչպես նաև հանգույցների գտնվելու վայրը: Ստացվեց, իմ համեստ կարծիքով, բավականին հարմար, չնայած, իհարկե, համն ու գույնը...

Ինչպե՞ս է սա աղյուսակը զանգվածում:

• Յուրաքանչյուր հանգույց նկարագրվում է նույնացուցիչով, որը եզակիորեն նույնականացնում է հանգույցը:
• Կարող եք նաև պատկերակ ավելացնել հանգույցին և ավելացնել մակագրություն:
• Դուք կարող եք սահմանել հարաբերություն երկու հանգույցների միջև:
• Դիագրամի վրա հաղորդակցվելու համար կարող եք սահմանել գույնը և մակագրությունը:
• Հաղորդակցության ուղղությունը սահմանվում է որպես աղբյուրից թիրախ: Իսկ աղբյուրը և թիրախը նշվում են հանգույցների նույնացուցիչներով:
• Մեկ կամ մի քանի հանգույց կարող է ավելացվել խմբին:
• Հարաբերությունները կարող են նաև ճշգրտվել ինչպես խմբից, այնպես էլ խմբից:

Օգտագործելով այս պարզ կանոնները, մենք ստանում ենք հետևյալ դիագրամը. Պարզապես? Բավականին.

Եվ դա նկարագրվում է հետևյալ 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 կառուցվածքը թույլ է տալիս արագ լրացնել բոլոր տվյալները անալոգիայի միջոցով և կարող եք պատճենել-տեղադրել:

Ինչու են դիրքերը տեղադրվում հանգույցներից առանձին:

Ավելի հարմարավետ է։ Սկզբում մենք նշում ենք հանգույցները: Այնուհետև մենք կարող ենք նշել մի քանի խումբ և նշել դրանք հանգույցներում: Այնուհետև մենք նշում ենք կապերը: Եվ միայն այն ժամանակ, երբ առկա են հիմնական առարկաները և նրանց միջև կապերը, մենք վերցնում ենք այդ օբյեկտների գտնվելու վայրը դիագրամում: Կամ հակառակը։

Հնարավո՞ր է առանց պաշտոնների։

Առանց դիրքերի հնարավոր է։ Բայց դա մի փոքր ճմրթված կլինի՝ այս տարբերակը կարող եք տեսնել օրինակներում։ Դա պայմանավորված է նրանով, որ կա cytoscape-ի համար հանգույցների տեղակայման ալգորիթմ fcose, որը նաև հաշվի է առնում խմբերի առկայությունը։ Դիրքերը նշելը դիագրամն ավելի կառավարելի է դարձնում, սակայն դիագրամի առաջին գծագրման փուլում դա հնարավոր է առանց դիրքերի։

Դիրքերը կարելի է նաև նշել Battleship ոճով: Նրանք. մի հանգույցը գտնվում է a1-ում, իսկ մյուսը՝ d5-ում: Դա հատկապես օգնում է, որ cytoscape-ը կտավի վրա գտնվող առարկաները դարձնում է շարժական, այսինքն. մենք կարող ենք դրանք տեղափոխել շուրջը, տեսնել դասավորության տարբեր տարբերակներ, այնուհետև ամրագրել այն տարրերի դասավորությունը, որոնք մեզ դուր են գալիս կոդում:

Ընդհանրապես, դա հասկանալի է. Կարող եք նաև փորձել:
 
Իհարկե, արագ սխեմաներ ստեղծելու համար ես ինքս ինձ փոքրիկ դարձրեցի խմբագիր, որն ինքնին թարմացնում է սխեման և պահում վերջին տարբերակը բրաուզերում (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

Source: www.habr.com