코드로 보는 네트워크 다이어그램 / 코드로 보는 네트워크 다이어그램

지난 몇 년 동안 나는 문서화 작업에 더 많이 참여하게 되었습니다. 이 시스템이나 저 시스템이 어떻게 작동하는지에 대한 설명 텍스트를 작성하는 것은 일반적으로 매우 간단합니다. 모든 주요 개체와 이러한 개체 간의 연결을 표시하는 다이어그램을 그리는 것도 매우 쉽습니다.

그러나 가장 문제가 되는 측면은 이 문서를 최신 상태로 유지하는 것입니다. 텍스트는 괜찮겠지만 다이어그램은... 왜냐면... 모든 문서는 온라인에 있습니다. html 형식의 경우 텍스트에는 실제로 다이어그램을 표시하는 gif/jpeg/png 그림이 함께 제공됩니다. 그리고 다이어그램은 Visio나 온라인 서비스 a la draw.io와 같은 다양한 프로그램에서 그려집니다. 그런 다음 다이어그램을 그래픽 형식으로 내보내고 HTML에 첨부합니다. 간단 해.

문제가 무엇입니까?

계획은 일반적으로 간단합니다. 더 정확하게는 그다지 복잡하지 않습니다. 예, 개체 수는 XNUMX개 또는 XNUMX개이며 연결 수는 거의 같습니다. 플러스 서명, 일부 지정. 간단한 계획은 말로 설명할 수 있지만 너무 복잡한 계획은 에헴... (c) "그들은 이해하지 못할 것입니다, 선생님." 많은 계획이 있으므로 정기적으로, 간헐적으로 변경해야 합니다. 끊임없이 왜냐하면 그들은 우리 제품의 개발을 따릅니다.

서비스의 HTML을 삽입할 수 있습니다. 시도해 보셨나요?

물론이지. 예를 들어, 나는 gliffy.com의 그래픽을 좋아합니다. 하지만 변경하려면 타사 서비스로 이동하여 편집해야 합니다. 그리고 동료에게 수정 사항을 위임하는 것이 더 어렵습니다.

무엇을해야 하는가?

최근에 권장 사항에서 Github의 저장소를 발견했습니다. github.com/RaoulMeyer/diagram-as-code. 코드로서의 다이어그램. 저것들. 우리는 js에서 필요한 회로를 설명합니다. 우리는 이 js를 다른 문서 텍스트가 있는 동일한 HTML에 직접 작성합니다.

그건 그렇고, 나는 문서 전체를 HTML로 작성하지 않습니다. 일반적으로 문서는 마크다운 텍스트가 포함된 파일 세트이며, 이는 Wintersmith와 같은 일부 엔진에 의해 본격적인 문서 사이트로 변환됩니다. 아니면 위키 시스템.

매우 편리하다는 것이 밝혀졌습니다. 텍스트를 작성한 다음 스크립트 태그가 열리고 구성표의 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);

물론 회로도를 직접 그린 것은 아니고 라이브러리를 이용했습니다. 사이토스케이프.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 구조를 사용하면 유사하게 모든 데이터를 빠르게 채울 수 있으며 복사하여 붙여넣을 수 있습니다.

위치가 노드와 별도로 배치되는 이유는 무엇입니까?

더 편안합니다. 먼저 노드를 지정합니다. 그런 다음 몇 개의 그룹을 지정하고 이를 노드에 표시할 수 있습니다. 그런 다음 연결을 지정합니다. 그런 다음 주요 개체와 개체 간의 연결이 있을 때만 다이어그램에서 이러한 개체의 위치를 ​​취합니다. 혹은 그 반대로도.

포지션 없이 가능한가요?

포지션 없이도 가능합니다. 하지만 약간 구겨질 수 있으므로 예제에서 이 옵션을 볼 수 있습니다. 이는 세포경관의 노드 위치에 대한 알고리즘이 있기 때문입니다. 프코즈, 이는 그룹의 존재도 고려합니다. 위치를 지정하면 다이어그램을 더 쉽게 제어할 수 있지만 다이어그램의 첫 번째 초안 단계에서는 위치 없이도 가능합니다.

전함 스타일에서도 위치를 지정할 수 있습니다. 저것들. 한 노드는 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. 매우 상세하고 복잡한 다이어그램을 좋아한다면 이 프로젝트에 확실히 감탄하게 될 것입니다. go.drawthe.net

출처 : habr.com