From 438ef71f24d760a8fe1b479ef1dbecfc58f0ae73 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Mon, 4 Aug 2025 14:02:55 +0900 Subject: [PATCH] =?UTF-8?q?Add:=20PlantUML=20=EC=8B=9C=ED=80=80=EC=8A=A4?= =?UTF-8?q?=20=EB=8B=A4=EC=9D=B4=EC=96=B4=EA=B7=B8=EB=9E=A8=20=EC=83=9D?= =?UTF-8?q?=EC=84=B1=EA=B8=B0=20=ED=8A=B8=EB=9F=AC=EB=B8=94=EC=8A=88?= =?UTF-8?q?=ED=8C=85=20=EB=AC=B8=EC=84=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...ell80_시퀀스다이어그램생성기.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 troubleshooting/250804_happybell80_시퀀스다이어그램생성기.md diff --git a/troubleshooting/250804_happybell80_시퀀스다이어그램생성기.md b/troubleshooting/250804_happybell80_시퀀스다이어그램생성기.md new file mode 100644 index 0000000..2365631 --- /dev/null +++ b/troubleshooting/250804_happybell80_시퀀스다이어그램생성기.md @@ -0,0 +1,84 @@ +# 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. **깊은 호출 체인 추적 실패** + ```python + # 예: 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개 | 핵심만 구현 | + +#### 사용법 + +```bash +# 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. 수동 호출 관계 정의 기능 \ No newline at end of file