"코드로서의 다이어그램"

우리는 previous article에서 우리의 기본 동인이 소프트웨어 문서를 도구 환경과 프로세스 관점에서 가능한 한 개발자에게 가깝게 유지하는 것임을 확인했습니다. 그러나 문서에 몇 개의 문장이 포함되어 있으면 다음과 같은 다이어그램도 많이 있습니다.


출처: https://c4model.com

화이트보드의 멋진 사진이나 작성자가 시간을 들여 모델링 도구로 그림을 전송했다면 그런 것을 가질 수 있습니다.


출처: https://sparxsystems.com

그리고 모든 경우에 jpeg 또는 png로 끝납니다. 불행히도 다이어그램은 발전할 것이고 두 jpeg를 비교하는 것은 그렇게 쉬운 일이 아닙니다 :). 코드로서의 문서화라는 동일한 접근 방식에 따라 코드로서의 다이어그램으로 이동하는 것이 자연스러웠습니다. 에서 이러한 접근 방식의 성장을 언급했습니다. 지난 2년 동안 우리가 따라온 방식이 속도를 내고 있는 것을 보는 것은 위안이 되었습니다.

다이어그램을 버전화하고 비교할 수 있도록 하기 위해 다양한 언어plantuml를 사용합니다.

Plantuml for C4 예, 우리는 모델링의 단순성과 탐색 가능성에 대한 아이디어를 좋아하기 때문에 아키텍처 문서에 C4을 사용합니다. 그때 사용한다

Plantuml for AWS 애플리케이션이 AWS에 배포되었지만

버전도 찾을 수 있습니다.

Azure 또는

GCP .

그리고 이와 같은 간단한 코드로

@startuml Basic Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(admin, "Administrator")
System_Boundary(c1, "Sample System") {
    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
}
System(twitter, "Twitter")

Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml

우리는 얻는다

모든 버전 가능

이제 우리는 모든 것을 버전화할 수 있습니다. 마지막으로 다이어그램을 비교할 수 있습니다. 말했듯이 우리는 모델링이 아니라 다이어그램을 작성하고 있으며 사실입니다. diagram as code 및 클라우드 아키텍처 방향으로 structurizr의 최신 개선 사항을 통해 이러한 모델링 도구로의 마이그레이션을 예상할 수 있습니다.

우리의 접근 방식은 더 나은 탐색을 허용하고 중복을 방지할 수 있도록 정보를 연결한다는 아이디어를 기반으로 합니다. 우리는 구성 요소의 문서 또는 코드에서 직접 이동할 수 있는 다이어그램 수준에서 동일한 경험을 원했습니다. 이를 위해 다음을 확장했습니다.

jekyll-plantuml 내장 URL이 있는 SVG를 생성하는 플러그인

plantuml for C4 Url을 자연스럽게 삽입

@startuml
!include C4/C4_Container.puml
Person(admin, Administrator, "Alice", {{site.baseurl}}/alice/)
System_Boundary(c1, "Sample System") {
    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
}
System(twitter, "Twitter")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml

확신을 가지려면 following url로 이동하여 Alice 또는 twitter를 클릭하십시오.

결론적으로 코드로서의 다이어그램은 아키텍처를 문서화하는 가벼운 방식입니다. 도구 사용이 아닌 콘텐츠에 집중할 수 있습니다. 한번 해보고 jekyll과 결합하면 완전히 탐색 가능한 문서가 됩니다.