아키텍처 다이어그램은(는) 무엇을 하나요?
다이어그램은 그것이 보여주는 내용이 독자가 이미 알고 있는 것과 연결될 때 이해됩니다. 시니어 개발자는 다이어그램에서 최상위 흐름과 **시임(seam)**을 읽습니다. **블록(block)**은 블랙박스입니다: 그 디자인 패턴, 책임, 소유자, 그리고 내부는 숨겨집니다. 한 블록이 시임을 통해 다른 블록에 제공하는 것은 **인터페이스(interface)**입니다: 매개변수와 반환 타입, 오류, 그리고 그 경계를 넘나드는 데이터 타입과 필드, 그리고 정확히 무엇이 어떻게 교차하는지에 대한 예시입니다. 전송 방식(REST, OPC UA, 프로세스 시작)은 인터페이스의 속성일 뿐이며, 이를 대체할 수 없습니다.
그리기 전에 EXAMPLE.md를 읽으십시오: 하나의 변경 사항을 두 형식 모두로 완전하게 표현한 예시입니다.
단계
1. 독자의 언어
새로운 용어는 아무것에도 연결되지 않습니다. 다른 모든 작업보다 먼저, 독자가 이미 가지고 있는 단어를 수집하십시오: 이 대화의 메시지, 그들이 작성한 문서(프로젝트 지침, 아키텍처 페이지, 용어집, 명명법 표), 그리고 다이어그램이 비교되는 모든 모델로부터 수집합니다. **단어 목록(word list)**을 작성하십시오: 대상, 그 대상에 대한 독자의 단어, 다이어그램을 읽을 다른 당사자의 단어, 코드 내 이름, 그리고 다이어그램에서 사용할 단어.
- 모든 블록과 인터페이스에는 독자의 단어로 레이블을 붙이고, 코드 이름은 그 옆에 표기합니다.
- 두 단어가 충돌하거나, 단어가 잘못된 대상에 사용된 경우 하나를 선택하고, 단어 목록에서 그 이유를 설명하며, 다른 단어는 옆에 한 번만 표기합니다.
- 새로 만들지 마십시오. 코드에 이름이 없는 인터페이스는 두 끝점으로 부릅니다:
프론트엔드 -> 백엔드. - 독자가 이미 가지고 있는 그림, 즉 그들만의 수준과 이름이 있는 다이어그램에서 시작하여, 새로운 것을 그 안에 배치합니다.
다이어그램의 모든 레이블이 단어 목록에서 비롯되고, 독자에게 새로운 모든 용어가 용어집에서 그 용어가 속한 알려진 단어 옆에 있을 때 완료됩니다.
2. 질문
독자의 질문을 각각 한 줄씩 작성하십시오. 그들이 뷰를 선택합니다.
| 질문 | 뷰 |
|---|---|
| 구성 요소는 무엇이며, 각각의 책임은 무엇이고, 누가 소유하며, 누가 누구를 호출합니까? | 빌딩 블록 뷰 |
| 두 구성 요소를 연결하는 인터페이스는 무엇이며, 정확히 무엇이 그 경계를 넘나듭니까? | 인터페이스, 그 데이터 타입 및 모든 시임의 예시 |
| 중요한 시나리오에서 어떤 순서로 어떤 일이 발생합니까? | 런타임 뷰: 하나의 시퀀스 |
| 각 구성 요소는 어디에서 실행됩니까? | 모든 블록의 host:; 네트워크 또는 신뢰 경계가 질문일 때는 배포 뷰 |
| 변경 사항은 어떤 영향을 미치며, 두 설계는 어떻게 다릅니까? | 동일한 형식의 모든 상태(state), 그 다음 차이점 |
모든 뷰가 자신의 질문을 가지고 있으며, 그 질문이 뷰 위에 캡션으로 있을 때 완료됩니다.
3. 카탈로그
그리기 전에 출처에서 다음 네 가지 목록을 채우십시오.
- 블록(Blocks): 독자의 단어와 코드 내 이름, 스테레오타입, 한 문장의 책임, 소유자, 호스트.
- 인터페이스(Interfaces), 시임 당 하나: 제공자, 소비자, 모든 연산을 시그니처
name(param: Type) -> Type로, 오류, 전송 방식. - 데이터 타입(Data types): 시그니처가 명명하는 모든 타입과 그 필드, 단위 및 기본값.
- 예시(Examples), 인터페이스 당 하나: 메시지가 교차되는 형태, 호출과 응답을 실제 형식으로: 명령줄과 출력, JSON 본문, 테이블 행. 실행 결과, 녹화, 픽스처 또는 데이터에서 가져옵니다. 코드에서 조합한 예시는 첫 줄에 그렇게 명시합니다.
모든 항목은 출처를 명시합니다: 코드 참조 path:line, 또는 태그(아래 참조). 다른 사람이 그린 상태, 모델 파일 또는 스케치는 그대로 재현하며 자신의 단어를 사용합니다; 누락된 부분은 [undefined]로 태그하고, 추가하는 내용은 별도의 상태로 만듭니다.
모든 블록에 문장이 있고, 모든 시임에 코드에서 복사하거나 태그된 시그니처가 있는 인터페이스가 있고, 시그니처의 모든 타입에 필드가 있고, 모든 인터페이스에 예시가 있고, 모든 항목에 참조 또는 태그가 있을 때 완료됩니다.
4. 수준
하나의 상태에 있는 블록들은 동등합니다: 자체적으로 배포, 소유 또는 교체되는 단위이며, 5~9개입니다. 파일, 함수 및 블록 내부 단계는 그 내부입니다. **확대(zoom)**는 한 수준 아래의 추가 다이어그램으로, 질문의 대상이 되는 하나의 블록에 대해 그려집니다.
어떤 상태의 블록도 다른 블록 안에 있지 않고, 모든 확대 다이어그램이 그 비용을 지불하는 질문을 명명할 때 완료됩니다.
5. 형식
- 채팅 형식(Chat form), 최대 78열: 모든 가장자리에 인터페이스 이름과 주요 시그니처가 있는 빌딩 블록 뷰, 그 다음 테이블 형태의 카탈로그와 코드 블록 형태의 예시. 하나의 상태 또는 작은 변경에 적합합니다.
- 캔버스 형식(Canvas form), 필요한 만큼 넓은 텍스트 다이어그램의 정적 HTML 페이지: 모든 가장자리 옆에 전체 인터페이스, 예시, 필드가 있는 데이터 타입. 여러 상태 또는 세 개 이상의 시임이 전체로 표시될 때 사용합니다. 페이지는 함께 제공되는 생성기 스크립트에 의해 빌드됩니다; 채팅 응답은 파일 이름을 명시하고, 비교 결과를 몇 문장으로 설명하며, 미해결 결정 사항을 나열합니다.
- C4 형식(C4 form), 상태별 탭, 클릭 및 확대 가능한 상자가 있는 페이지에 LikeC4로 그려진 동일한 모델. 텍스트 다이어그램이 그 프로토타입 역할을 합니다: 먼저 단어, 블록, 인터페이스, 예시를 거기서 확정한 후 렌더링합니다. 다른 사람이 열어볼 결과물에 사용합니다. LIKEC4.md를 읽으십시오.
6. 그리기
이 폴더에 있는 세 개의 파일을 사용하여 그립니다. 상자가 정렬되고 어떤 행도 캔버스보다 넓지 않도록 합니다. 각 파일의 독스트링이 매뉴얼이며, 실행하면 데모를 출력합니다.
| 파일 | 제공 |
|---|---|
grid.py | Grid (구획, 선, 화살표가 있는 상자), sequence (런타임 뷰), table |
canvas.py | glance (모든 상태를 한 줄에), overview (상태를 나란히, 수준별 한 행), panel (하나의 상태: 블록, 예시가 있는 인터페이스, 데이터 타입) |
page.py | html_page: 다이어그램 주변 페이지, 색상 및 ID 간 링크 포함 |
likec4/ | C4 형식용: template.c4, build.sh, tabs.js가 포함된 탭 페이지 index.html, 그리고 clicktest.py |
페이지는 10초 만에 보는 그림에서 세부 사항까지 이어집니다: 한눈에 보기, 단어 목록, 읽기 가이드, 개요, 상태별 패널, 시임별 차이점 표, 미해결 결정 사항, 용어집, 출처.
7. 확인
- 모든 상자는 카탈로그의 블록이고, 모든 가장자리는 인터페이스이며, 모든 타입 상자는 데이터 타입입니다; 다이어그램에서 누락된 항목은 의도적으로 누락된 것입니다.
- 모든 코드 참조가 확인됩니다: 파일이 존재하고, 해당 줄에 이름이 표시됩니다.
- 동일한 블록은 모든 상태에서 동일한 위치에 있습니다. 어떤 상태에 없는 블록은 점선 상자로 표시됩니다.
- 전체 페이지 스크린샷을 타일별로 읽습니다: 경계가 일치하고, 잘린 부분이 없으며, 색상이 그 의미를 전달합니다.
- 출처는 읽은 내용, 커밋, 실제 예시, 그리고 읽지 않은 내용을 명시합니다.
상태
상태는 현재 코드, 누군가가 그린 목표, 또는 제안입니다. 상태를 위치별로 비교하십시오: glance의 동일한 열과 overview의 동일한 행에 있는 동일한 블록은 두 상태의 차이점이 서로를 보완하는 지점을 보여줍니다.
시임에는 상태의 문자와 숫자로 구성된 ID가 있습니다: (I4). 한 시임에서 정의된 인터페이스 또는 데이터 타입은 다른 모든 곳에서 해당 ID로 참조되며, 필드는 한 번만 작성됩니다.
차이점 표는 시임당 한 행, 상태당 한 열로 구성됩니다. 미해결 결정 사항 표는 질문, 옵션, 결정자를 포함합니다.
태그 및 스테레오타입
| 태그 | 의미 |
|---|---|
[code] | 코드에 존재함; 참조가 옆에 표시됨 |
출처 태그, 예: [c4] | 소스 모델에 명시됨; 읽기 가이드에서 태그 이름을 명시 |
[proposed] | 여기서 제안됨, 아직 어디에도 존재하지 않음 |
[new] [changed] [moved] | as-is와 to-be만 있을 때, 변경이 무엇을 하는지 표시 |
[undefined] | 상태가 미정으로 남겨둠 |
[?1] | 미해결 결정, 번호와 함께 나열 |
스테레오타입은 블록이 수행하는 디자인 패턴을 명명합니다: <<ui>>, <<client>>, <<gateway>>, <<facade>>, <<service>>, <<port>>, <<adapter>>, <<repository>>, <<external>>. 코드가 해당 역할을 수행하는 경우에만 사용하십시오; 스테레오타입이 없는 블록이 잘못된 스테레오타입이 있는 블록보다 낫습니다. 포트는 소비자가 소유하고 제공자가 구현하는 인터페이스입니다: <<port>>는 인터페이스에, <<adapter>>는 이를 구현하는 블록에 위치합니다. 소스 모델의 자체 종류는 작성된 그대로 인용합니다.
설명 장치
각각은 독자가 그렇지 않으면 질문해야 할 내용에 답함으로써 그 자리를 얻습니다. 절약해서 사용하십시오.
- 읽기 가이드(Reading guide): 패널을 읽는 방법과 태그를 보여주는 하나의 작은 다이어그램.
- 코드 참조(Code references): 모든 인터페이스와 데이터 타입에 대해, 독자가 찾아볼 수 있도록.
- 짧은 텍스트(Short texts): 상태 위에 한 문단으로 그 상태에서 볼 하나의 내용을 설명; 독자가 이유를 물을 인터페이스 상자 내부에 참고 사항 추가.
- 용어집(Glossary): 단어 목록에서 다루지 않는 용어, 각각 한 줄.
- 색상(Colour): 태그, ID, 그리고 모든 상태에서 동일하게 유지되는 한두 개의
key이름에만 사용. 색상은 상태가 공유하는 것과 차이점을 표시합니다; 다른 것은 색칠되지 않습니다.
프로세 텍스트는 대화의 언어로 작성됩니다. 코드 및 소스 모델의 이름은 그대로 사용합니다.