DOCS/journey/troubleshooting/250804_happybell80_시퀀스다이어그램생성기.md

2025년 8월 4일 - PlantUML 시퀀스 다이어그램 자동 생성기 개발

오후 2시 1분

PlantUML 기반 시퀀스 다이어그램 자동 생성기 구현

배경

• FastAPI 프로젝트의 API 호출 흐름을 자동으로 분석하여 PlantUML 시퀀스 다이어그램 생성
• 로빙 프로젝트의 복잡한 호출 관계를 시각화하기 위한 도구 필요

구현 내용

1. AST 기반 Python 코드 분석기

   • FastAPI 라우터 자동 탐지
   • 함수 호출 관계 추적
   • import alias 매핑 지원

2. PlantUML 생성기

   • 분석된 호출 흐름을 PlantUML 형식으로 변환
   • 참여자 자동 식별 및 메시지 흐름 생성

3. 개선 사항

   • 불필요한 호출 필터링 (1109개 → 388개로 감소)
   • 무의미한 참여자 제거 (json, logger, data 등)
   • 파일명에 프로젝트명 포함으로 구분 명확화

문제점과 한계

1. AST 정적 분석의 한계

   • 함수 내부의 로컬 import 처리 불가
   • 인스턴스 메서드 호출 추적 어려움
   • 동적으로 생성되는 라우트 감지 불가

2. 깊은 호출 체인 추적 실패

   # 예: slack_service._process_message() 내부의 
   # RobeingBrain.process_request() 호출을 추적하지 못함
   

3. 프레임워크별 차이

   • rb10408: Slack Bolt 데코레이터 기반 라우팅 인식 못함
   • 각 프로젝트의 구조적 차이로 인한 분석 정확도 차이

프로젝트별 분석 결과

프로젝트	라우트 수	함수 호출 수	특징
rb8001	14개	388개	원본 구조, 많은 서비스
rb10408_test	14개	127개	Slack Bolt, 가장 경량
rb10508_test	16개	443개	가장 복잡, 테스트 기능
rb10508_micro	12개	169개	핵심만 구현

사용법

# uv로 실행 (Python 패키지 관리)
uv run python main.py --path ../rb8001 --list-routes
uv run python main.py --path ../rb8001 --route /events --output generated

교훈

1. 정적 분석 vs 동적 분석

   • 정적 분석만으로는 실제 런타임 동작을 완벽히 파악하기 어려움
   • 동적 트레이싱이나 프로파일링 도구와 병행 필요

2. 도메인 지식의 중요성

   • 프로젝트 구조를 알면 휴리스틱으로 정확도 향상 가능
   • 범용 도구보다 특화된 도구가 더 실용적일 수 있음

3. uv 패키지 매니저 활용

   • pip 대체로 빠른 속도와 자동 의존성 관리
   • uv run 명령으로 가상환경 자동 관리

4. 완벽보다는 실용성

   • 100% 정확한 분석보다 80% 수준의 유용한 결과가 더 가치있음
   • 기본적인 호출 흐름 파악만으로도 프로젝트 이해에 도움

향후 개선 방향

1. 동적 분석 도구 통합
2. 프레임워크별 특화 분석기 개발
3. 실행 시점 트레이싱 기능 추가
4. 수동 호출 관계 정의 기능