mermaid로 다이어그램 그려보자아~

TL;DR

거의 처음 설계를 하면서 왜 설계를 하는지에 대한 고민을 가지고 mermaid라는 툴을 통해 설계를 시도해보는 글입니다.

들어가며

지금까지 개발을 해오면서 설계를 제대로 했는지 생각해봤다.
ERD말고는 만든 기억이 없다.
그렇다고 해서 제대로 만들지는 않았던거 같다.
그려면 왜 그렇게 하지 않았을까?
그야 편하니까..
개발자의 시선이 아닌 비 개발자의 시선으로 개발자를 바라본다면 '종이'가 아닌 '코드'를 먼저 작성한다고 생각한다.
난 아직도 비 개발자의 시선으로 개발자를 바라보고 있는것이 아닌가
그래서 당연하게 먼저 IDE를 키고, 코드를 작성하는거 같다.
솔직히 아직 잘 모르겠다. 설계를 해서 직접적으로 얻은 이득은 아직 잘 와 닿지는 않는다.
그럼에도 설계를 공부하고 해보는 이유는

시도를 안 해봤기 때문에 어렵다고 얘기하는 것이다.
 - 전 야구 선수 김용수

안 해본걸 해봐야지 늘지 않을까? 내 기억으로는 루퍼스의 모 코치님도 같은 말씀을 해주신걸로 기억한다.
아마 설계의 중요성은 나중에 알아도 늦지 않지 않을까?
안 해본거라.. 설계를 도와주는 많은 도구들이 존재한다.

drow.io, erdCloud, excalidraw등등이 존재한다.
이들의 공통점은 시각적으로 설계를 해준다는것이라는 공통점을 가지고 있다.
그런데도 설계가 잘 되지 않았다.

분명 시도는 많이 해봤을텐데, ...;;
위의 툴들도 좋지만 이번에는 색다른 방식의 툴을 사용해볼려고 한다.
(excalidraw은 다른 2개와 다른 느낌이긴하지만... ;;)

그래서 내가 선택한 툴은 mermaid이다.

왜 mermaid 일까?

위에서 말했듯이 안해본 방법이라 이 방법을 선택했다. 이거같은 경우, 마크다운 형식으로 만들 수 있다는 점이다. 
즉, 마크다운만 사용할 수 있는 환경이라면 어디에서든 사용할 수 있다. 
또한 다이어그램도 다양하게 사용할 수 있는듯하다. 이는 즉, 다이어그램 마다 특화된 툴을 사용할 필요가 없다는 뜻이 된다.

자 이제 뭘해볼까?

이 툴로 할 수 있는건 굉장히 많다.
다이어그램은 다 만들 수 있는 느낌이 들었다.

시퀀스다이어그램, 클래스다이어그램, ERD 등등 여러가지 그림을 그릴 수 있다.

즉, 요구사항 정의서빼고...

다만 주의해야할점은 문법을 정확하게 입력하지 않으면, 다이어그램으로 만들어주지 않았다.
또, 문법이 다이어그램마다 조금씩 달라 그점 빼고는 나름 괜찮게썼던거 같다.

개인적인 견해로, 클래스나 ERD등등 같은 경우는 다른 툴로 사용해도 크게 불편함은 없었는데
시퀀스를 작성할때 굉장히 불편했었다.
그 이유는 Activate바 때문이었는데 어디서 어디까지 바를 선정하는것이 개인적으로는 귀찮았다.
왜냐하면, Activate를 만들기 위해서는 새로 생성해서 만들어야 한다고 생각했기때문이다.
이는 진짜 없는 거일수도 있지만, 그 툴들에 대한 이해도가 부족한게 아닌가 생각이 든다.
그에 반에,  mermaid는 다른 툴들에 비해 적응하기 어렵지 않았다.

그러면 이 툴을 통해 시퀀스, 클래스, ERD 다이어그램을 그려보자.

시퀀스 다이어그램

시퀀스는 시스템 내 객체들이 시간 순서에 따라 상호작용하는 흐름을 시각적으로 표현한 UML 입니다.
mermaid로 시퀀스를 그릴때,

sequenceDiagram

을 작성하고
하위에 이 시퀀스에서 동작하는 참여자를 작성하게 되어있다.
그럼 대략적으로 요렇게 작성할 수 있다.

sequenceDiagram
actor C as Client
participant OC as OrderController
participant OS as OrderService
participant PS as ProductService
participant PAS as PaymentService
participant POS as PointService

그럼대략적으로 사각형이 두둥실 떠다니는 그림이 될거라 생각한다.
client빼고 이거는 사람모형...
암튼 이제 메시지를 전달하는 과정을 작성하면 되는데
예를 들어, OrderController -> OrderService을 메시지가 보내야 한다면

OC -->> OS: 메시지 작성

이렇게 된다.  듣기로는 비동기로 작성하는 방법도 있고
선 종류도 생각보다 많았다. 그걸 다 이해하면 좋은데 아쉽게도 다 이해하지는 못했다.
그래서 가장 간단하것을 사용했다.

그러면 다음과 같은 그림을 만들 수 있다.

티스토리는 왜 마크다운이 안되지 ㅜㅜ
인증 객체를 전달하고 인증이 되면 상품이 존재하는지 확인하고..
근데 문제는 저 그림으로는 누군가에게 설명하는것이 쉽지 않을거 같다.
그 이유는 alt문안에 alt문이 들어가있기 때문인데 저렇게 그리면 이걸 설명하려면 헷갈리기 시작할거 같다.
일단 난 못 할거 같다.
이것을 해결하기 위해 activate바를 사용하면 좀더 가독성있게 파악을 할 수 가 있다.
그러면 다음과 같이 그릴 수 있는데

아까와 달리 인증 객체를 전달을 하고 activate바로 메시지의 범위를 표현할 수 있었다.

그와 별개로 위 그림과 같은 시나리오를 그리고 있지만 activate바로 좀더 가독성있게 변경이 되어진 느낌이다.
조금더 자연스럽게 읽히는 느낌이다.

결국 각 객체들간의 어떤 동작을 하는지 설명하는것이 시퀀스 다이어그램의 핵심이라 여겨진다.
그중에서도 activate바를 잘 사용하는것이 가독성을 올리는 길이 아닐까 생각이 들기도 한다.

내가 생각할때 시퀀스를 그리는 좋은 접근법은 참여자가 어떤것이 있는지 생각하면, 조금더 시퀀스를 그리는데 수월할꺼라 생각한다.
그리고 activate바를 적재 적소로 작성하면 생각보다 흐름을 그리는데 어렵지 않을거라 생각한다.
1) 참여자
2) activate

클래스 다이어그램

뭔가 안탁가운말이지만, 아니 당연한 말인가..
시퀀스와 문법이 다르다. 이말은 지금까지 -->> 이런거 쓰고 참여자 쓰고 이랬는데 
이것은 아닌거 같다. ㅜㅜ

이름으로 부터 알 수 있듯이 클래스를 사용하게 되어진다.
시퀀스와 달리 모든 클래스가 작성이 되어진다.

class Brand {
   
}

class Product {
   
}

일단, 요렇게 만들 수 가 있다 요렇게 만들게 되면
사각형 2개가 나오는데 요렇게만 그리면

이것만 가지고 얘들이 어떤 관계인지 어떤 속성인지 전혀 모른다.
이 클래스안에 어떤 값들이 존재하는지 알아야 하는데 그것을 작성하는 방법은

• + public
• - private
• # protected
• ~ package-private

요렇게 작성할 수 있다.

class Brand {
   - id:long
}

class Product {
    - id:long
}

코드를 잘 보면 : 이라는 게 있는데 요거는 속성값을 말한다고 한다.
즉 id는 long으로 반환한다고 할 수 있다.
또한, 메소드도 작성할 수 있는데
메소드는 이름(파라미터:속성값) : 반환값 이렇게 작성하면 된다.

그래서 이렇게만 그리면 될까?
관계를 표기를 해야 한다.
여기에서도 다양한 방법을 사용할 수 있지만 아직 잘 모르는 관계로 

Brand "1" --> "N" Product : 소유

요런식으로 작성했다.
읽어보면 브랜드 1개당 상품이 N개를 소유할 수 있다는 뜻으로 해석이 되어진다.
결론적이면 다음처럼 보여진다.

객체(클래스) 설계만 하였지만, 인터페이스를 만들고, 인터페이스에 어떤것들이 속해있는지 그런것도 할 수 있다고 한다.

ERD 다이어그램

지금까지 본걸로 예측할 수 있듯이 문법이 역시나 다르다.
클래스 다이어그램과 달리 이 다이어그램에서는 class를 사용하지 않는다.
바로 이름으로 부터 시작된다. 다음처럼 작성할 수 있다.

erDiagram
%%브랜드    
BRAND {

}

%%상품
PRODUCT {

}

그리고 나서 테이블을 만든다는 느낌으로 하나하나 값들을 채워나가면 된다.

%%브랜드    
BRAND {
 BIGINT id PK "브랜드 아이디"
 BIGINT member_id FK "계정 아이디"
 VARCHAR(50) name UK "브랜드 명"

}

sql문으로 create을 작성한다면 다음과 같이 쓸 수 있다.

CREATE TABLE BRAND (
    id BIGINT PRIMARY KEY COMMENT '브랜드 아이디',
    member_id BIGINT COMMENT '계정 아이디',
    name VARCHAR(50) UNIQUE COMMENT '브랜드 명',
    CONSTRAINT fk_brand_member FOREIGN KEY (member_id) REFERENCES MEMBER(id)
);

이거보면 알 수 있다시피 딱히 이질감은 없는듯한 느낌이 든다.
그래서 다른 다이어그램에 비해 조금더 쉽게 읽혔던거 같다. 게다가 회사 다니면서도 다른 다이어그램은 안 그려봤는데 erd는 그려본거일수도 있다.
클래스와 마찬가지로 연관관계를 그려야 하는데 다음처럼 그릴 수 있다.

BRAND ||--o{PRODUCT : has

결국 다음과 같이 그림을 볼수 있었다.

그림을 보면 브랜드 1개당 상품이 여러개를 가진다고 보여진다.

처음 그려볼때 클래스다이어그램와 같은줄알았는데, 뭔가 미묘한 다른점이 있었다.
예를들어, 클래스에서는 브랜드안에 List<Proudct>가 존재할수 있지만, erd에는 존재하지 않는다. (예시에는 없긴하다.)

근데 아마 클래스(도메인 위주) 와 테이블로 그렸기때문에 유사하다고 생각한게 아닌가 싶다.

마무리

이 이외에도 다양한 다이어그램을 그릴수 있다고 한다.
아직까지는 설계가 개발에 얼마나 도움이 되는지는 잘 모르겠다. 어쩌면 설계가 끝나고 개발이 종료가 되어도 그것을 알아채지 못할 수 있다.
설계는 귀찮은 작업이다.
설계를 안 한다고 해서 개발을 못하는건 아니다. 설계를 안 한다고 해서 커뮤니케이션을 못 하는것도 아니라고 생각한다.
말은 이해하기 쉬워도, 시간이 지나면 쉽게 잊혀지고
글은 시간이 지나도 다시 볼수 있지만, 이해하는데 시간이 걸린다고 생각한다.
하지만 그림은 시간이 지나도 다시 볼수 있고, 이해하는데도 그리 오랜 시간이 걸리지는 않는다.

말은 3일 후 기억 유지율이 약 10%에 불과하지만,
글은 이해에 시간이 더 걸리고,
그림은 3일 후 기억 유지율이 약 65%에 달하며 텍스트보다 약 80% 더 정확하게 기억된다.
- gemini

그림도 그림나름지라 이해하기 어려울수 있다. 다이어그램이라 그럴수 있다. 하지만 명심해야 하는건 개발자만 문서를 보는것은 아니라는 점이다. 개발과 상관없는 분들도 읽을수 있다. 생각보다 쉽지 않는 과제이지만, 노력해야될 문제이지 않을까?

출처: https://mermaid.js.org/