시퀀스 다이어그램으로 상호작용 흐름 설계하기

호출 순서가 설계의 빈틈을 드러낼 때

시퀀스 다이어그램은 객체, 컴포넌트, 외부 액터가 시간에 따라 어떤 메시지를 주고받는지 구조화해 나타낸다. 기능 시나리오에서 누가 무엇을 호출하고 어떤 값을 반환하는지를 명확히 하므로, 요구사항 명세와 아키텍처 설계, 코드와 테스트를 같은 흐름으로 연결하는 데 쓰인다.

핵심 표기는 생명선(Lifeline), 활성 구간(Activation), 메시지, 결합 프래그먼트(alt/opt/loop/par)다. 시간과 순서가 중요한 API 설계, 마이크로서비스 오케스트레이션, SSO/OAuth 보안 플로우, 거래·결제, 장애 시나리오 분석에 적용할 수 있다.

생명선과 메시지로 실행 경로를 읽는다

생명선은 참여자의 수명을, 활성 구간은 실제 실행 시간을 표현한다. 활성 구간을 중첩하면 재진입이나 중첩 호출도 드러낼 수 있다.

메시지는 동기 호출, 비동기 호출, 응답으로 구분한다. 생성과 소멸, 신호, 반환값, 예외도 메시지에 함께 표시할 수 있다. 동기 호출은 호출자가 블로킹되므로 SLA, 타임아웃, 재시도 정책을 명시하는 편이 좋다. 비동기 호출은 콜백·이벤트·큐를 기반으로 하며, 상관관계 ID와 적어도 한 번 또는 정확히 한 번 처리의 의미를 합의해야 한다.

분기와 병렬 흐름을 한 장면에 담는 법

alt와 opt는 조건 분기와 선택 실행을 나타내며, guard 조건으로 실행 조건을 분명히 할 수 있다. loop와 par는 반복과 병렬 처리를 표현한다. par를 사용했다면 레이스와 동시성 이슈를 주석으로 남기는 것이 권장된다.

트랜잭션은 begin, commit, rollback 주석으로 경계를 표시한다. 2PC와 SAGA 보상 흐름은 ref 또는 alt로 분리할 수 있다. 행·테이블 락과 락 대기, 타임아웃도 표시하고, 일관성 수준 및 격리 레벨은 문서로 남긴다.

참여자는 Boundary, Control, Entity로 나누어 배치할 수 있다. UI·API 경계, 오케스트레이션 로직, 데이터 모델의 책임을 분리하면 설계상의 경계와 테스트 대상이 더 선명해진다.

작성 전 범위와 책임을 먼저 고정한다

시나리오는 입력에서 처리, 출력까지 정하고 성공 경로와 예외 경로를 구분한다. 이후 Actor, Boundary, Control, Entity를 식별하고 외부 시스템 인터페이스를 명시한다.

생명선은 호출 방향이 자연스럽게 보이도록 좌에서 우로 배치하며 핵심 경로는 중앙에 둔다. 메시지를 설계할 때는 동기·비동기 유형과 guard, alt·opt·loop·par를 정하고, 타임아웃·재시도·백오프를 주석으로 남긴다. 트랜잭션 경계와 락 획득·해제, 격리 수준, 보상·롤백 경로도 같은 흐름에서 확인한다.

SLA, 최대 대기시간, 큐 적체 한계, 서킷브레이커 상태 같은 비기능 조건도 필요한 위치에 표시한다. 시퀀스 번호와 API 스펙·테스트 케이스 링크를 연결하고 변경 이력을 버전 관리하면 문서가 구현과 분리되지 않는다.

로그인 흐름에 트랜잭션과 오류 경로를 표시하기

다음 예시는 로그인 요청에서 트랜잭션, 행 수준 락, 병렬 감사 로깅, 타임아웃을 함께 표현한다. Mermaid v10+ 지원 환경(GitHub, VSCode, Notion 등)을 전제로 한다.

⤢✕

이 흐름은 입력·처리·출력과 함께 예외 및 타임아웃 경로를 보여 준다. 트랜잭션 경계와 잠금, par 구문의 병렬 로깅을 한곳에서 확인할 수 있으며, traceId는 분산 추적과 연결된다.

서비스 흐름과 운영 분석에 연결하기

마이크로서비스 오케스트레이션에서는 주문에서 결제, 재고, 배송으로 이어지는 호출 순서와 SAGA 보상 흐름을 정의하고 장애 주입 테스트의 기준선으로 활용할 수 있다. 인증·인가 플로우에서는 OAuth 2.1, OIDC 하이브리드 플로우의 리다이렉트와 토큰 교환 경로, 토큰 만료·재발급 시나리오를 명세한다.

API 계약 주도 개발에서는 시퀀스 다이어그램과 OpenAPI/AsyncAPI를 양방향으로 참조하며 필수 헤더, 상관관계 ID, 오류 코드를 합의할 수 있다. 배치와 이벤트 처리에서는 비동기 큐·토픽, 재시도·백오프·중복 방지(idempotency key) 정책을 시각화한다. 장애 분석과 포스트모템에서는 타임라인을 재구성해 병목과 락 경합 구간을 식별하고 SLA 위반 원인을 추적한다.

가정 기반 예로, 요구 오해로 인한 재작업은 2040% 감소하고 리뷰·테스트 실패율은 1525% 감소할 수 있다. 이슈 트라이에지 평균 시간은 원인 경로가 명확해지면서 25~35% 단축되고, 표준화된 시나리오 문서는 신규 온보딩 리드타임을 30% 단축할 수 있다. 설계·코드·테스트 사이의 추적성과 인터페이스 계약도 강화되며, 동시성·트랜잭션 리스크를 가시화해 운영 및 보안 팀의 공통 언어를 만든다.

다른 UML 다이어그램과 선택 기준

유형	성능(작성·이해)	확장성(대규모)	일관성(UML 표준/연계)	안정성(변경 내성)	운영 편의(도구/협업)
시퀀스 다이어그램	높음	중간	높음	중간	높음
커뮤니케이션 다이어그램	중간	높음	중간	높음	중간
액티비티 다이어그램	중간	높음	높음	중간	중간

시퀀스 다이어그램은 시나리오 단위의 명료성이 좋지만 복잡도가 커지면 확장성이 낮아진다. 커뮤니케이션 다이어그램은 관계 중심이어서 구조 변경에 강하다. 액티비티 다이어그램은 분기와 병렬 표현에 강점이 있지만 시간축을 정밀하게 나타내는 데는 한계가 있다.

읽히는 문서로 유지하는 기준

기능 단위는 1~2화면 또는 1 API 수준으로 나누고, 한 장에 모든 흐름을 통합하지 않는다. 전역 시야와 가독성 사이의 선택이 필요하다. 메시지는 필수 호출만 남기고 반복 패턴은 ref로 추출한다. 간결성은 높아지지만 완전성과는 균형을 맞춰야 한다.

비동기 흐름에는 상관관계 ID, 재시도, 백오프, 데드레터 정책을 표시한다. 복원력을 얻는 대신 복잡도가 커진다. 트랜잭션 전략에서는 2PC 대신 SAGA와 보상 패턴을 우선 고려할 수 있으며, 강한 일괄 원자성과 운영 단순성·확장성 사이에 트레이드오프가 있다.

비밀값은 마스킹하고 토큰 수명과 스코프를 표기하며 위협 모델과 교차 검토한다. 상세성은 높아지지만 노출 위험도 함께 고려해야 한다. Mermaid와 PlantUML 같은 텍스트 기반 도구를 Git PR 리뷰 흐름에 통합하면 자동화 이점이 생기지만 학습 곡선이 따른다.