Mermaid 다이어그램 가이드 Part 3: Sequence Diagram
이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.
Sequence Diagram이란?#
시퀀스 다이어그램은 객체들 간의 메시지 교환을 시간 순서에 따라 보여주는 다이어그램입니다. API 호출 흐름, 인증 과정, 트랜잭션 처리 등을 문서화할 때 특히 유용합니다.
기본 문법#
sequenceDiagram
participant A as 클라이언트
participant B as 서버
A->>B: 요청
B-->>A: 응답
Participant 정의#
자동 정의#
메시지에서 처음 등장하는 이름이 자동으로 participant가 됩니다.
sequenceDiagram
Alice->>Bob: 안녕하세요!
Bob-->>Alice: 안녕하세요!
명시적 정의와 순서 지정#
participant 키워드로 명시적으로 정의하면 원하는 순서로 배치할 수 있습니다.
sequenceDiagram
participant C as Client
participant G as API Gateway
participant S as Service
participant D as Database
C->>G: HTTP Request
G->>S: Forward Request
S->>D: Query
D-->>S: Result
S-->>G: Response
G-->>C: HTTP Response
Actor 심볼#
actor 키워드를 사용하면 사람 모양 아이콘으로 표시됩니다.
sequenceDiagram
actor User as 사용자
participant App as 모바일 앱
participant Server as 백엔드 서버
User->>App: 로그인 버튼 클릭
App->>Server: 인증 요청
Server-->>App: 토큰 발급
App-->>User: 홈 화면 표시
다양한 Participant 유형 (v10+)#
sequenceDiagram
actor User as 사용자
participant App as Application
participant API as API Server
participant DB as Database
participant Cache as Redis Cache
participant Queue as Message Queue
User->>App: 요청
App->>Cache: 캐시 조회
Cache-->>App: 캐시 미스
App->>API: API 호출
API->>DB: 쿼리
DB-->>API: 결과
API->>Cache: 캐시 저장
API-->>App: 응답
App->>Queue: 이벤트 발행
메시지 유형#
화살표 종류#
sequenceDiagram
participant A
participant B
A->B: 실선, 화살표 없음
A-->B: 점선, 화살표 없음
A->>B: 실선, 화살표
A-->>B: 점선, 화살표
A-xB: 실선, X 표시 (실패/거부)
A--xB: 점선, X 표시
A-)B: 실선, 비동기 (열린 화살표)
A--)B: 점선, 비동기
| 문법 | 설명 | 용도 |
|---|---|---|
-> |
실선 | 일반 메시지 |
--> |
점선 | 응답/반환 |
->> |
실선 + 화살표 | 동기 호출 |
-->> |
점선 + 화살표 | 동기 응답 |
-x |
실선 + X | 실패/거부 |
-) |
실선 + 열린 화살표 | 비동기 메시지 |
양방향 화살표 (v11.0.0+)#
sequenceDiagram
participant A
participant B
A<<->>B: 양방향 실선
A<<-->>B: 양방향 점선
Activation (활성화 박스)#
객체가 활성 상태임을 나타내는 박스를 표시합니다.
명시적 활성화#
sequenceDiagram
participant C as Client
participant S as Server
C->>S: 요청
activate S
S->>S: 처리 중...
S-->>C: 응답
deactivate S
축약 문법 (+/-)#
+와 -를 화살표 끝에 붙여 간단하게 표현할 수 있습니다.
sequenceDiagram
participant C as Client
participant S as Server
participant D as Database
C->>+S: 요청
S->>+D: 쿼리
D-->>-S: 결과
S-->>-C: 응답
중첩 활성화#
sequenceDiagram
participant C as Client
participant S as Server
C->>+S: 외부 요청
S->>+S: 내부 처리 1
S->>+S: 내부 처리 2
S-->>-S: 완료 2
S-->>-S: 완료 1
S-->>-C: 응답
Notes (노트)#
기본 노트#
sequenceDiagram
participant A
participant B
Note left of A: 왼쪽 노트
A->>B: 메시지
Note right of B: 오른쪽 노트
Note over A: A 위 노트
Note over A,B: A와 B 사이 노트
실전 활용#
sequenceDiagram
participant Client
participant Auth as Auth Server
participant API as API Server
Note over Client,API: OAuth 2.0 인증 흐름
Client->>Auth: 인증 요청 (client_id, redirect_uri)
Note right of Auth: 사용자 인증 처리
Auth-->>Client: Authorization Code
Client->>Auth: Token 요청 (code, client_secret)
Auth-->>Client: Access Token + Refresh Token
Note over Client: 토큰 저장
Client->>API: API 요청 (Bearer Token)
API-->>Client: 응답 데이터
제어 구조#
Loop (반복)#
sequenceDiagram
participant Client
participant Server
participant DB
Client->>Server: 배치 처리 요청
loop 각 아이템에 대해
Server->>DB: 아이템 처리
DB-->>Server: 결과
end
Server-->>Client: 완료
Alt/Else (조건 분기)#
sequenceDiagram
participant User
participant App
participant Auth
User->>App: 로그인 시도
App->>Auth: 인증 확인
alt 인증 성공
Auth-->>App: 토큰 발급
App-->>User: 홈 화면
else 비밀번호 오류
Auth-->>App: 401 Unauthorized
App-->>User: 비밀번호 오류 메시지
else 계정 잠금
Auth-->>App: 403 Forbidden
App-->>User: 계정 잠금 메시지
end
Opt (선택적)#
조건이 참일 때만 실행되는 블록입니다.
sequenceDiagram
participant App
participant Cache
participant DB
App->>Cache: 캐시 조회
opt 캐시 미스
App->>DB: DB 조회
DB-->>App: 데이터
App->>Cache: 캐시 저장
end
Cache-->>App: 데이터 반환
Par (병렬 처리)#
sequenceDiagram
participant Client
participant OrderSvc as Order Service
participant PaymentSvc as Payment Service
participant InventorySvc as Inventory Service
participant NotifySvc as Notification
Client->>OrderSvc: 주문 생성
par 결제 처리
OrderSvc->>PaymentSvc: 결제 요청
PaymentSvc-->>OrderSvc: 결제 완료
and 재고 처리
OrderSvc->>InventorySvc: 재고 차감
InventorySvc-->>OrderSvc: 차감 완료
and 알림 발송
OrderSvc->>NotifySvc: 알림 요청
NotifySvc-->>OrderSvc: 발송 완료
end
OrderSvc-->>Client: 주문 완료
Critical (크리티컬 섹션)#
반드시 실행되어야 하는 중요 작업을 표시합니다.
sequenceDiagram
participant App
participant Payment
participant DB
App->>Payment: 결제 시작
critical 트랜잭션 영역
Payment->>DB: 잔액 차감
Payment->>DB: 결제 기록 저장
option 네트워크 오류
Payment-->>App: 재시도 요청
option DB 오류
Payment-->>App: 롤백 완료
end
Payment-->>App: 결제 완료
Break (중단)#
예외 상황에서 흐름이 중단됨을 표현합니다.
sequenceDiagram
participant Client
participant Server
participant Auth
Client->>Server: API 요청
Server->>Auth: 토큰 검증
break 토큰 만료
Auth-->>Server: 401 Token Expired
Server-->>Client: 재로그인 필요
end
Auth-->>Server: 토큰 유효
Server-->>Client: 응답 데이터
배경 하이라이트#
rect로 특정 영역에 배경색을 지정할 수 있습니다.
sequenceDiagram
participant Client
participant Gateway
participant Service
participant DB
rect rgb(191, 223, 255)
Note over Client,Gateway: 인증 단계
Client->>Gateway: 요청 + Token
Gateway->>Gateway: Token 검증
end
rect rgb(200, 255, 200)
Note over Gateway,DB: 비즈니스 로직
Gateway->>Service: 요청 전달
Service->>DB: 쿼리
DB-->>Service: 결과
Service-->>Gateway: 응답
end
Gateway-->>Client: 최종 응답
Actor 생성과 소멸 (v10.3.0+)#
동적으로 객체가 생성되고 소멸되는 것을 표현할 수 있습니다.
sequenceDiagram
participant Main
Main->>+Worker: 작업 요청
create participant TempProcess
Worker->>TempProcess: 임시 프로세스 생성
TempProcess->>TempProcess: 작업 수행
TempProcess-->>Worker: 결과 반환
destroy TempProcess
Worker-->>-Main: 완료
Box (그룹핑)#
관련된 participant들을 박스로 그룹화할 수 있습니다.
sequenceDiagram
box Blue 클라이언트 영역
actor User
participant App
end
box Green 서버 영역
participant API
participant Auth
participant DB
end
User->>App: 로그인 요청
App->>API: 인증 요청
API->>Auth: 토큰 발급
Auth->>DB: 사용자 조회
DB-->>Auth: 사용자 정보
Auth-->>API: 토큰
API-->>App: 응답
App-->>User: 로그인 완료
시퀀스 번호#
메시지에 자동으로 번호를 매길 수 있습니다.
sequenceDiagram
autonumber
participant Client
participant Server
participant DB
Client->>Server: 요청 1
Server->>DB: 쿼리
DB-->>Server: 결과
Server-->>Client: 응답 1
Client->>Server: 요청 2
Server-->>Client: 응답 2
줄바꿈#
메시지와 노트에서 <br/>로 줄바꿈할 수 있습니다.
sequenceDiagram
participant A
participant B
A->>B: 첫 번째 줄<br/>두 번째 줄
Note over B: 긴 설명을<br/>여러 줄로<br/>작성할 수 있습니다
실전 예제: JWT 인증 흐름#
sequenceDiagram
autonumber
actor User as 사용자
participant App as 클라이언트
participant Auth as 인증 서버
participant API as API 서버
participant DB as 데이터베이스
Note over User,DB: 로그인 프로세스
User->>App: 로그인 (email, password)
App->>+Auth: POST /auth/login
Auth->>DB: 사용자 조회
DB-->>Auth: 사용자 정보
alt 인증 성공
Auth->>Auth: JWT 토큰 생성
Note right of Auth: Access Token: 15분<br/>Refresh Token: 7일
Auth-->>-App: 200 OK + Tokens
App->>App: 토큰 저장 (메모리/스토리지)
App-->>User: 로그인 성공
else 인증 실패
Auth-->>App: 401 Unauthorized
App-->>User: 로그인 실패
end
Note over User,DB: API 호출
User->>App: 데이터 요청
App->>+API: GET /api/data (Bearer Token)
API->>API: 토큰 검증
alt 토큰 유효
API->>DB: 데이터 조회
DB-->>API: 데이터
API-->>-App: 200 OK + Data
App-->>User: 데이터 표시
else 토큰 만료
API-->>App: 401 Token Expired
rect rgb(255, 240, 200)
Note over App,Auth: 토큰 갱신
App->>Auth: POST /auth/refresh
Auth-->>App: 새 Access Token
end
App->>API: 재요청 (새 Token)
API-->>App: 200 OK + Data
App-->>User: 데이터 표시
end
실전 예제: 결제 처리#
sequenceDiagram
autonumber
participant Client
participant OrderSvc as Order Service
participant PaymentSvc as Payment Service
participant PG as Payment Gateway
participant EventBus as Event Bus
Client->>+OrderSvc: 주문 생성 요청
OrderSvc->>OrderSvc: 주문 검증
OrderSvc-->>Client: 주문 ID 반환
Client->>+PaymentSvc: 결제 요청 (주문 ID)
critical 결제 트랜잭션
PaymentSvc->>+PG: 결제 승인 요청
alt 결제 성공
PG-->>-PaymentSvc: 승인 완료
PaymentSvc->>EventBus: PaymentCompleted 이벤트
PaymentSvc-->>-Client: 결제 성공
par 후처리
EventBus-)OrderSvc: 주문 상태 업데이트
and
EventBus-)Client: 결제 완료 알림
end
else 결제 실패
PG-->>PaymentSvc: 승인 거절
PaymentSvc->>EventBus: PaymentFailed 이벤트
PaymentSvc-->>Client: 결제 실패
end
end
deactivate OrderSvc
Read other posts