Mermaid 다이어그램 가이드 Part 3: Sequence Diagram
이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.
Sequence Diagram이란?#
시퀀스 다이어그램은 객체들 간의 메시지 교환을 시간 순서에 따라 보여주는 다이어그램입니다. API 호출 흐름, 인증 과정, 트랜잭션 처리 등을 문서화할 때 특히 유용합니다.
기본 문법#
sequenceDiagram
participant A as 클라이언트
participant B as 서버
A->>B: 요청
B-->>A: 응답
sequenceDiagram
participant A as 클라이언트
participant B as 서버
A->>B: 요청
B-->>A: 응답
Participant 정의#
자동 정의#
메시지에서 처음 등장하는 이름이 자동으로 participant가 됩니다.
sequenceDiagram
Alice->>Bob: 안녕하세요!
Bob-->>Alice: 안녕하세요!
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
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: 홈 화면 표시
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
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: 점선, 비동기
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: 양방향 점선
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
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
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: 응답
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 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: 응답 데이터
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: 완료
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
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: 데이터 반환
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: 주문 완료
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: 결제 완료
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: 응답 데이터
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: 최종 응답
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: 완료
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
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
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/>작성할 수 있습니다
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
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
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