무료 · 가입 불필요 · .mmd 파일 지원

Mermaid 시퀀스 다이어그램 편집기

시퀀스 다이어그램은 누가 누구와 어떤 순서로 주고받는지를 보여줍니다. 여러 주체 사이의 메시지 교환이 핵심일 때 적합합니다. 인증, 결제, 서비스 간 연동 같은 것들입니다. 참여자가 하나뿐이고 분기가 핵심이라면 순서도가 같은 말을 더 적은 잡음으로 합니다.

편집기에서 열기 →가이드 읽기

추가 인증이 붙는 카드 결제

이 다이어그램의 값어치는 `alt` 블록에 있습니다. 추가 인증이 늘 일어나지는 않는다는 것과, 끝나는 길이 두 갈래라는 것이 드러납니다. 결제대행사가 카드사와 주고받는 동안 가맹점은 그 사실을 모른다는 점도 보세요. 시퀀스 다이어그램이 드러내고 순서도가 감추는 것이 바로 이런 부분입니다.

sequenceDiagram
    autonumber
    participant C as 고객
    participant S as 가맹점
    participant P as 결제대행사
    participant B as 카드사

    C->>S: 주문 확정
    S->>P: 승인 요청
    P->>B: 거래 전달
    B-->>P: 추가 인증 필요

    alt 카드사가 추가 인증을 요구
        P-->>C: 인증 페이지로 이동
        C->>B: 인증번호 입력
        B-->>P: 인증 성공
    else 요구하지 않음
        B-->>P: 바로 승인
    end

    P-->>S: 승인 완료
    S-->>C: 주문 확정 안내
    S->>S: 매출 기록

편집기에서 열기

예제로 익히기

1. 참여자 둘과 메시지 하나

`->>`는 채워진 화살촉으로 호출을 뜻합니다. `-->>`는 점선으로 응답을 뜻합니다. 이 한 쌍이면 대부분의 다이어그램이 됩니다.

sequenceDiagram
    고객->>API: 주문 생성
    API-->>고객: 201 Created

편집기에서 열기

2. 긴 이름에 별칭 붙이기

`participant X as 긴 이름`은 적을 때는 짧은 ID를, 읽을 때는 읽기 좋은 이름을 줍니다. 참여자를 앞에서 선언하면 그림에서의 순서도 고정됩니다. 선언하지 않으면 처음 나온 순서가 정합니다.

sequenceDiagram
    participant B as 브라우저
    participant A as 주문 API
    participant I as 재고 서비스

    B->>A: POST /orders
    A->>I: 재고 선점
    I-->>A: 선점 완료
    A-->>B: 201 Created

편집기에서 열기

3. 활성 구간과 자기 호출

`activate`와 `deactivate`는 참여자가 일하고 있음을 나타내는 막대를 그립니다. 화살표에 붙이는 `+`와 `-`는 같은 일을 더 적게 써서 합니다. 참여자에서 자기 자신으로 가는 화살표는 내부 처리를 뜻합니다.

sequenceDiagram
    participant A as API
    participant D as 데이터베이스

    고객->>+A: GET /invoice/42
    A->>+D: SELECT 청구서
    D-->>-A: 행 발견
    A->>A: 부가세 계산
    A-->>-고객: 200 OK

편집기에서 열기

4. 대안, 선택, 반복

`alt`/`else`는 배타적인 갈래, `opt`는 일어나지 않을 수도 있는 블록, `loop`는 반복입니다. 셋 다 `end`로 닫고, 그걸 빠뜨리는 것이 이 종류에서 가장 흔한 오류입니다.

sequenceDiagram
    participant C as 고객
    participant A as API
    participant M as 메일 서비스

    C->>A: 회원가입 요청
    alt 이미 가입된 메일
        A-->>C: 409 Conflict
    else 사용 가능한 메일
        A-->>C: 201 Created
        A->>M: 인증 메일 발송
        loop 최대 3회
            M->>M: 발송 실패 시 재시도
        end
    end
    opt 고객이 수신 동의
        A->>M: 수신 목록에 등록
    end

편집기에서 열기

5. 메모와 병렬 처리

`par`는 동시에 진행되는 갈래를 보여줍니다. 순서도가 암시만 하고 단언하지는 못하는 부분입니다. 메모는 메시지 레이블에 담기지 않는 세부를 적어 두기에 알맞은 자리입니다.

sequenceDiagram
    participant A as 주문 API
    participant B as 정산
    participant L as 물류

    Note over A: 주문은 이미 결제 완료 상태

    par 정산에 통보
        A->>B: 세금계산서 발행
        B-->>A: 발행 번호 2026/0431
    and 물류에 통보
        A->>L: 출고 준비
        L-->>A: 송장 생성됨
    end

    Note over B,L: 두 갈래는 각자의 속도로 진행됩니다

편집기에서 열기

시퀀스 다이어그램 문법 요약

외워야 할 것은 화살표이고, 이것들은 이 종류 전용입니다. 순서도의 `-->`는 여기서 다른 뜻이고, 여기의 `->>`는 클래스 다이어그램에서 오류입니다.

문법	뜻
sequenceDiagram	다이어그램을 시작합니다. 대소문자를 구분합니다. `sequencediagram`은 안 됩니다.
participant A	참여자를 선언하고 위치를 고정합니다.
participant A as 이름	짧은 ID에 읽기 좋은 이름.
actor A	participant와 같지만 사람 모양으로 그립니다.
A->>B: 글자	채워진 화살촉 메시지 — 호출.
A-->>B: 글자	점선 — 응답.
A-)B: 글자	열린 화살촉 — 비동기 메시지.
A->>A: 글자	참여자가 자기 자신을 호출.
activate A / deactivate A	A가 일하고 있는 구간을 표시.
A->>+B: / B-->>-A:	같은 일을 화살표 위에서 줄여서.
alt 조건 ... else ... end	배타적인 갈래.
opt 조건 ... end	일어나지 않을 수도 있는 블록.
loop 글자 ... end	반복.
par ... and ... end	동시에 진행되는 갈래.
Note over A,B: 글자	참여자 위에 메모. `Note left of`, `Note right of`도 있습니다.
autonumber	메시지에 번호를 자동으로 매깁니다.

시퀀스 다이어그램을 깨뜨리는 여섯 가지 오류

Mermaid 11.12.2에서 재현했습니다. 압도적으로 흔한 것은 첫 번째이고, 그 오류 메시지는 문제가 있는 곳을 가장 못 짚어주는 축에 듭니다.

보이는 증상

다이어그램의 마지막 줄을 가리키는 Parse error

원인

블록을 열고 닫지 않았습니다. `alt`, `opt`, `loop`, `par`은 각자의 `end`가 필요합니다. Mermaid는 입력이 끝나는 지점에서 실패를 알리므로, 줄 번호는 닫지 않은 블록이 아니라 파일의 끝을 가리킵니다. 블록이 두 겹으로 겹쳐 있으면 눈으로 찾기가 정말 어려워집니다.

해결

연 블록의 수와 적은 `end`의 수를 세어 보세요. 오류가 마지막 줄을 가리키면 거의 항상 이것입니다.

잘못된 예

sequenceDiagram
    고객->>API: 요청
    alt 정상
        API-->>고객: 200 OK

고친 예

sequenceDiagram
    고객->>API: 요청
    alt 정상
        API-->>고객: 200 OK
    end

보이는 증상

No diagram type detected matching given configuration

원인

키워드의 대소문자가 틀렸습니다. `sequenceDiagram`은 되고 `sequencediagram`과 `SequenceDiagram`은 안 됩니다. Mermaid는 모든 키워드에서 대소문자를 구분합니다.

해결

D만 대문자, 나머지는 소문자.

잘못된 예

sequencediagram
    고객->>API: 안녕

고친 예

sequenceDiagram
    고객->>API: 안녕

보이는 증상

그려지기는 하는데 메시지에 글자가 없다

원인

콜론 뒤에 텍스트가 없습니다. 실측: Mermaid는 이것을 거부하지 않고 빈 레이블로 메시지를 그리며, 화살표만 설명 없이 남습니다. 정말로 실패하는 쪽은 콜론 자체를 빼는 경우입니다. `고객->>API`만 쓰면 `Expecting 'TXT', got 'NEWLINE'`이 납니다. 즉 콜론은 필수이고 텍스트는 필수가 아닙니다. 짐작과는 정반대입니다.

해결

콜론 뒤에 한 단어라도 적으십시오. 레이블 없는 화살표가 의도인 경우는 거의 없습니다.

잘못된 예

sequenceDiagram
    고객->>API:
    API-->>고객: 200

고친 예

sequenceDiagram
    고객->>API: 주문 생성
    API-->>고객: 200

보이는 증상

조건이 긴 `alt` 뒤에서 Parse error

원인

블록의 조건 안에서 줄을 바꿨습니다. `alt`, `opt`, `loop`의 조건은 한 줄에 들어가야 하며, 줄을 나누면 뒷부분이 메시지로 해석되어 어디에도 놓이지 못합니다.

해결

조건은 한 줄로 둡니다. 너무 길면 줄이고 세부는 메모로 옮깁니다.

잘못된 예

sequenceDiagram
    alt 고객의 잔액이
    충분한 경우
        A-->>B: OK
    end

고친 예

sequenceDiagram
    alt 고객의 잔액이 충분한 경우
        A-->>B: OK
    end
    Note over A,B: 잔액은 일일 한도와 대조합니다

보이는 증상

그려지기는 하는데 선언한 적 없는 참여자가 나타난다

원인

참여자 이름에 오타가 있습니다. Mermaid는 이름을 처음 본 시점에 참여자를 만들기 때문에 `결제대행사`와 `결재대행사`는 서로 다른 두 열이 되고 아무 경고도 없습니다. 한국어에서는 특히 띄어쓰기가 원인이 됩니다. `주문 API`와 `주문API`처럼 붙였다 뗐다 하면 열이 하나 더 생깁니다.

해결

참여자를 앞에서 `participant`로 선언하세요. 오타를 막아 주지는 않지만 어떤 이름이 유효한지 드러나고, 남는 열이 바로 눈에 띕니다.

잘못된 예

sequenceDiagram
    고객->>결제대행사: 승인 요청
    결재대행사-->>고객: 승인 완료

고친 예

sequenceDiagram
    participant C as 고객
    participant P as 결제대행사
    C->>P: 승인 요청
    P-->>C: 승인 완료

보이는 증상

그려지기는 하는데 열의 순서가 의도와 다르다

원인

참여자를 선언하지 않았습니다. 선언이 없으면 각 이름이 처음 나온 순서가 배치를 정하므로, 다이어그램 앞쪽에 메시지를 하나 추가하면 열 전체가 재배치되고 화살표가 서로 엇갈립니다. 다이어그램 자체는 여전히 맞지만 읽기가 훨씬 나빠집니다.

해결

보고 싶은 순서대로 모든 참여자를 앞에서 선언합니다.

잘못된 예

sequenceDiagram
    카드사-->>결제대행사: 승인
    고객->>가맹점: 주문 확정
    가맹점->>결제대행사: 승인 요청

고친 예

sequenceDiagram
    participant 고객
    participant 가맹점
    participant 결제대행사
    participant 카드사
    고객->>가맹점: 주문 확정
    가맹점->>결제대행사: 승인 요청
    결제대행사->>카드사: 거래 전달
    카드사-->>결제대행사: 승인

렌더링에 관한 메모

이 사이트가 쓰는 Mermaid 11.12.2에서 실측했습니다. 시퀀스 다이어그램은 두 가지 점에서 다른 종류와 다르게 동작합니다.

폭은 메시지가 아니라 참여자 수가 정합니다

실측: 참여자가 둘이면 viewBox 폭이 450픽셀, 여섯이면 1250픽셀로, 메시지 내용과 무관하게 열 하나당 약 200픽셀씩 늘어납니다. 메시지는 높이만 더하며 하나당 약 46픽셀입니다. 다만 단서가 하나 있습니다. 메시지 레이블이 열의 최소 폭보다 길면 그때는 다이어그램이 실제로 넓어집니다. 같은 참여자 쌍이 메시지 글자를 늘리는 것만으로 450에서 603픽셀이 됐습니다. 한국어는 글자가 촘촘해서 영어보다 이 한계에 늦게 닿는 편입니다.

viewBox의 원점이 음수인 유일한 종류입니다

시퀀스 다이어그램은 viewBox가 `0 0`이 아니라 `-50 -10`에서 시작합니다. 결함이 아니라 Mermaid가 참여자 상자를 위해 남겨 둔 여백입니다. 직접 만든 도구로 SVG를 후처리할 때만 문제가 되는데, 원점이 0이라고 가정한 계산은 첫 열을 잘라 먹습니다.

여기서는 PNG 내보내기가 정확합니다

순서도·클래스 다이어그램·상태 다이어그램·ER 다이어그램과 달리, 시퀀스 다이어그램은 레이블을 `<foreignObject>`가 아니라 순수 SVG 텍스트로 그립니다. 그래서 그대로 래스터화할 수 있습니다. 내보낸 PNG는 중간 재렌더링 없이 화면과 일치하고 글자 배치가 어긋나지 않습니다.

선언만 하고 쓰지 않은 참여자도 그려집니다

메시지를 주지도 받지도 않는 `participant`는 빈 열로 다이어그램에 남습니다. 이 흐름에는 관여하지 않는 존재를 보여주려고 일부러 그렇게 할 수도 있지만, 어떤 참여자의 마지막 메시지를 지우고 선언을 지우는 걸 잊었을 때 남는 흔적이기도 합니다.

테마는 색만 바꾸고 배치는 바꾸지 않습니다

같은 다이어그램을 밝은 테마와 어두운 테마로 그리면 viewBox가 같아서, 테마를 바꿔도 열이 움직이거나 블록 크기가 달라지지 않습니다.

다른 다이어그램이 나은 경우

참여자가 하나뿐이라면 보여줄 시퀀스가 없습니다. 열 하나에 자기 자신으로 가는 화살표만 있는 다이어그램은 불편하게 적은 순서도입니다.

여러 주체의 대화가 아니라 어떤 것이 거치는 상태를 설명하고 싶다면 상태 다이어그램을 쓰세요. 신호는 분명합니다. 같은 메시지를 조건만 바꿔 가며 반복해서 적고 있다면, 손에 쥔 것은 상태 기계입니다.

그리고 주고받는 메시지가 열두 개를 넘어가면 나누세요. 메시지가 예순 개인 시퀀스 다이어그램은 기술적으로는 맞고 사람에게는 쓸모가 없습니다. 대개는 단계별로 세 장으로 나누고 메모로 이어 주는 편이 훨씬 잘 읽힙니다.

다른 다이어그램 종류

작성 Dominik Malsch · 마지막 업데이트: 2026년 9월 8일

편집기 열기 →