Mermaid 순서도 편집기
순서도는 처리가 어떻게 흘러가는지 보여줍니다. 어떤 단계가 있고, 어디서 갈라지며, 갈라진 길이 어디서 다시 만나는지. 판단의 순서 자체가 핵심일 때 적합합니다. 배포 파이프라인, 요청의 경로, 결재 흐름 같은 것들입니다. 누가 언제 누구와 주고받는지가 핵심이라면 시퀀스 다이어그램이 낫습니다.
실패 경로가 두 개인 배포 파이프라인
이 사이트의 순서도는 대개 이 형태에서 시작합니다. 하나의 정상 경로가 곧게 뻗고, 거기서 판단 마름모가 갈라져 나가는 모양입니다. 마지막에서 두 번째 노드의 따옴표를 보세요. 레이블 안의 괄호는 반드시 따옴표로 감싸야 하며, 이것이 가장 흔한 오류입니다.
flowchart TD
Push[main에 푸시] --> Lint[정적 분석과 타입 검사]
Lint --> Test{테스트를 통과했는가}
Test -->|아니오| Alert[커밋 작성자에게 알림]
Test -->|예| Build[컨테이너 이미지 빌드]
Build --> Scan{취약점 스캔이 깨끗한가}
Scan -->|아니오| Block["릴리스 중단 (수동 검토 필요)"]
Scan -->|예| Deploy[운영에 배포]
Deploy --> Smoke[스모크 테스트 실행]
Smoke --> Done[릴리스 완료]예제로 익히기
1. 가장 단순한 순서도
노드 두 개와 화살표 하나. `TD`는 위에서 아래로, `LR`은 왼쪽에서 오른쪽으로입니다. 세로보다 가로가 긴 그림은 대개 `LR`이 읽기 좋습니다.
flowchart TD
수신[요청 수신] --> 응답[응답 전송]2. 레이블이 붙은 분기
중괄호는 마름모가 됩니다. 세로줄 사이에 들어간 글자는 노드가 아니라 간선에 붙습니다. 이 구분은 뒤의 오류 절에서 다시 나옵니다.
flowchart TD
시작[요청 수신] --> 인증{토큰이 유효한가}
인증 -->|예| 처리[핸들러 실행]
인증 -->|아니오| 거부[401 반환]
처리 --> 완료[200 반환]3. 모양에 의미 담기
모양은 순서도에 정보를 더하는 가장 값싼 방법입니다. 둥근 끝은 시작과 끝, 마름모는 판단, 원기둥은 데이터 저장소를 뜻합니다.
flowchart LR
시작([작업 시작]) --> 조회[(Postgres에서 읽기)]
조회 --> 판단{새 행이 있는가}
판단 -->|없음| 종료([변경 없이 종료])
판단 -->|있음| 변환[/데이터 변환/]
변환 --> 기록[(S3에 기록)]
기록 --> 종료4. 서브그래프로 담당자별 묶기
서브그래프는 관련된 노드를 테두리로 묶습니다. 가장 값어치가 나오는 건 단계별이 아니라 담당별로 묶을 때입니다. 어느 팀, 어느 서비스가 무엇을 맡는지 보이면 인계 지점이 드러납니다.
flowchart TD
subgraph client [브라우저]
UI[폼 제출]
end
subgraph api [주문 서비스]
검증[입력 검증]
저장[주문 저장]
end
subgraph async [백그라운드 처리]
메일[확인 메일 발송]
정산[정산 내역 생성]
end
UI --> 검증
검증 --> 저장
저장 --> 메일
저장 --> 정산5. 상한이 있는 재시도 루프
순서도는 순환을 잘 다룹니다. 재시도 루프는 그 진가가 드러나는 곳으로, 그 루프에 정말 출구가 있는지가 그림으로 한눈에 보입니다.
flowchart TD
전송[웹훅 전송] --> 결과{2xx가 왔는가}
결과 -->|예| 완료[전달됨으로 기록]
결과 -->|아니오| 횟수{시도가 5회 미만인가}
횟수 -->|예| 대기[지수 백오프]
대기 --> 전송
횟수 -->|아니오| 보관[데드레터 큐로]순서도 문법 요약
여기 있는 것은 모두 순서도 전용입니다. 특히 화살표는 다른 종류로 가져갈 수 없습니다. 시퀀스 다이어그램의 `->>`는 여기서 문법 오류입니다.
| 문법 | 뜻 |
|---|---|
| flowchart TD | 위에서 아래로. TB도 같습니다. 처리를 읽는 기본 방향. |
| flowchart LR | 왼쪽에서 오른쪽으로. RL도 있습니다. 옆으로 넓고 얕은 흐름에. |
| A[글자] | 사각형 — 보통의 단계. |
| A(글자) | 모서리가 둥근 사각형. |
| A([글자]) | 스타디움 모양 — 관례상 시작이나 끝. |
| A[(글자)] | 원기둥 — 데이터 저장소. |
| A{글자} | 마름모 — 판단. |
| A[/글자/] | 평행사변형 — 입력 또는 출력. |
| A --> B | 화살표. |
| A --- B | 화살촉 없는 선. |
| A -.-> B | 점선 화살표 — 관례상 비동기 또는 선택. |
| A ==> B | 굵은 화살표 — 관례상 주 경로. |
| A -->|글자| B | 레이블이 붙은 간선. 괄호가 들어가면 따옴표가 필요합니다. |
| A["글자 (괄호 포함)"] | 따옴표 레이블 — 괄호, 따옴표 등 모양 문법으로 읽히는 문자에 필요. |
| subgraph 이름 [제목] ... end | 노드를 테두리로 묶습니다. `end`로 닫습니다. |
| %% 주석 | 주석 행. 그려지지 않습니다. |
순서도를 실제로 깨뜨리는 여섯 가지 오류
모두 이 사이트가 실제로 쓰는 렌더러(Mermaid 11.12.2)에서 재현한 것입니다. 잘못된 쪽을 편집기에 붙여 넣으면 적힌 그대로의 오류가 납니다. 고친 쪽은 그려집니다. Mermaid 오류는 끝부분을 읽는 것이 가장 빠릅니다. `got` 뒤에 파서가 걸려 넘어진 토큰이 나옵니다.
보이는 증상
Parse error, 끝부분: got 'PS'
원인
대괄호 레이블 안에 여는 소괄호가 있습니다. 소괄호는 모양 문법이라 `A(글자)`는 둥근 노드를 뜻하고, 그래서 대괄호 안의 맨 괄호는 새 모양의 시작으로 읽힙니다.
해결
레이블 전체를 큰따옴표로 감쌉니다. 따옴표 안은 모두 글자로 취급됩니다.
flowchart TD
A[재시도 (최대 5회)] --> B[완료]flowchart TD
A["재시도 (최대 5회)"] --> B[완료]보이는 증상
Parse error, 끝부분: got 'STR'
원인
레이블 중간에 큰따옴표가 있습니다. 파서는 그것을 문자열의 시작으로 보고, 닫는 따옴표를 기대한 자리에서 닫는 대괄호를 만납니다.
해결
레이블 전체를 큰따옴표로 감싸고 안에서는 작은따옴표나 낫표를 쓰거나, 문자를 `#quot;`로 적습니다.
flowchart TD
A[상태는 "보류"] --> B[완료]flowchart TD
A["상태는 '보류'"] --> B[완료]보이는 증상
노드 이름을 적은 줄에서 Parse error
원인
노드 ID에 띄어쓰기가 들어갔습니다. 한국어에서 특히 자주 생기는데, 중국어나 일본어와 달리 한국어는 단어를 띄어 쓰기 때문입니다. 자연스러운 이름은 대부분 두 어절 이상입니다. ID는 화살표 앞의 토큰이라 공백이 그것을 끊고, 놓을 데 없는 단어가 하나 남습니다.
해결
ID는 붙여 쓴 한 덩어리로 하고, 읽을 글자는 레이블에 넣습니다. 한글 자체는 ID로 아무 문제 없이 쓸 수 있습니다. 문제는 오직 공백입니다.
flowchart TD
인증 서비스 --> 사용자 데이터베이스flowchart TD
인증[인증 서비스] --> db[(사용자 데이터베이스)]보이는 증상
Parse error, 끝부분: got 'end'
원인
`end`를 노드 ID로 썼습니다. 소문자 `end`는 서브그래프를 닫으므로, 노드가 있어야 할 자리에 블록의 끝이 나타난 셈입니다. 영어 예제를 따라가다 보면 나머지가 한국어인데도 마지막 노드 이름만 `end`가 되는 일이 꽤 자주 생깁니다.
해결
첫 글자를 대문자로 하거나, 다른 ID를 주고 그 단어를 레이블에 넣습니다. `종료`는 아무 문제 없습니다.
flowchart TD
시작[시작] --> endflowchart TD
시작[시작] --> 종료[완료]보이는 증상
세로줄 사이 간선 레이블에서 Parse error
원인
간선 레이블 안에 괄호가 있습니다. `|…|` 안에도 노드 레이블과 같은 제약이 걸려서, 거기서도 괄호는 글자가 아니라 문법입니다.
해결
간선 레이블도 따옴표로 감쌉니다.
flowchart TD
A -->|예 (항상)| Bflowchart TD
A -->|"예 (항상)"| B보이는 증상
Lexical error on line 1. Unrecognized text.
원인
방향 지정이 잘못됐습니다. 순서도가 받는 것은 TB, TD, BT, LR, RL 뿐이고, 그 밖의 것은 노드를 읽기도 전에 어휘 분석에서 실패합니다. 그래서 오류가 1행을 가리키고 실제 오타 위치를 가리키지 않습니다.
해결
다섯 개 중 하나를 씁니다. TD와 LR이면 거의 다 됩니다.
flowchart 위아래
A --> Bflowchart TD
A --> B렌더링에 관한 메모
문서에서 옮겨 적은 것이 아니라 이 사이트가 쓰는 Mermaid 11.12.2에서 직접 측정한 값들입니다. 순서도가 장난감을 넘어설 때 의미가 생기는 동작들입니다.
한국어는 CJK의 폭과 서구식 띄어쓰기를 동시에 가집니다
여섯 종류를 통틀어 한국어에만 해당하는 성질이고, 실측하면 분명하게 갈립니다. 폭으로 보면 한국어는 중국어·일본어와 같은 편입니다. 같은 뜻의 `A[Payment received] --> B[Ship the order]`는 viewBox 폭이 204픽셀인데 `A[결제 완료] --> B[주문 발송]`은 144픽셀이었습니다. 글자 하나가 넓은 대신 담는 뜻이 많아서 영어보다 좁게 나옵니다. 그런데 띄어쓰기에서는 중국어·일본어와 갈라집니다. 저 둘은 단어를 띄어 쓰지 않으니 ID에 공백이 섞일 일이 아예 없지만, 한국어는 띄어 씁니다. 그래서 한국어로 쓸 때는 CJK의 이점을 누리면서 서구 언어의 공백 함정을 그대로 밟게 됩니다.
레이블 줄바꿈은 공백에서만 일어납니다
실측: 노드 레이블은 viewBox 폭 276픽셀을 상한으로 넓어지다가, 그 뒤로는 줄을 바꾸며 한 줄당 약 24픽셀씩 높아집니다. 한국어는 폭이 좁아 이 상한에 늦게 닿습니다. `A[결제가 완료되었습니다]`처럼 제법 긴 문장도 240픽셀로 한 줄에 들어갔습니다. 다만 줄바꿈이 공백에서만 일어난다는 점은 알아둘 만합니다. 띄어쓰기 없이 길게 이어 붙인 한 덩어리는 절대 줄바꿈되지 않고 노드를 그대로 늘립니다.
높이는 노드당 약 105픽셀 늘고 폭은 거의 그대로입니다
위에서 아래로 흐르는 순서도에서 노드 3개일 때 viewBox는 대략 126×278입니다. 40개에서는 135×4126이 됩니다. 폭은 9픽셀 늘었는데 높이는 열다섯 배가 됐습니다. 긴 순서도는 어느 화면에도 들어가지 않는 가느다란 띠가 됩니다. 미리보기의 가운데 맞춤 버튼이 그래서 있습니다. 너무 길어졌을 때 `flowchart LR`로 바꾸면 세로가로 비율이 절반 가까이 줄어드는 일이 흔합니다.
레이블이 HTML이라 예전에는 PNG 내보내기가 깨졌습니다
순서도의 레이블은 SVG의 `<foreignObject>` 안에 진짜 HTML로 그려집니다. 레이블에서 `<br>`이나 간단한 마크다운이 되는 이유입니다. 동시에 브라우저가 그 SVG를 캔버스에 그리기를 거부하기 때문에, 이 사이트의 PNG 내보내기는 오랫동안 조용히 SVG 파일을 돌려주고 있었습니다. 지금은 내보낼 때 SVG 텍스트 레이블로 다시 그리므로 PNG가 제대로 나옵니다. 대신 내보낸 PNG의 글자 배치가 화면과 아주 미세하게 다릅니다.
테마는 색만 바꾸고 배치는 바꾸지 않습니다
같은 순서도를 밝은 테마와 어두운 테마로 그리면 viewBox가 완전히 같습니다. 테마를 바꿨다고 그림이 다시 짜이거나 레이블이 상자 밖으로 넘치는 일은 없습니다. 어두운 테마에서 이상해 보이는 것은 밝은 테마에서도 똑같이 이상합니다.
다른 다이어그램이 나은 경우
그림의 요점이 누가 누구에게 무엇을 보내는지이고 분기보다 시간 순서가 중요하다면, 시퀀스 다이어그램이 더 잘 읽히고 규모가 커져도 계속 잘 읽힙니다. 여섯 명의 참여자를 노드 이름으로 적어 넣은 순서도는 아직 그 사실을 인정하지 않은 시퀀스 다이어그램입니다.
절차가 아니라 어떤 것이 거치는 상태를 설명하고 있다면 상태 다이어그램을 쓰세요. 구별은 쉽습니다. 노드 레이블이 「주문 대기」, 「주문 발송됨」 같은 상태라면 상태 기계이고, 「입력 검증」, 「메일 발송」 같은 동작이라면 순서도입니다.
그리고 노드가 마흔 개를 넘어가면 솔직히 어떤 다이어그램으로도 구할 수 없습니다. 입구를 공유하는 여러 그림으로 나누거나, 설명하려는 것이 한 장에 담기에는 너무 복잡하다는 사실을 받아들이는 수밖에 없습니다. 그 자체로도 쓸모 있는 정보입니다.
다른 다이어그램 종류
작성 Dominik Malsch · 마지막 업데이트: