DOCS/book/300_architecture/guidelines/utility_functions.md

유틸리티 함수 설계 원칙

작성일: 2025-12-16
목적: 코드 재사용성 향상, 중복 제거, 유지보수성 개선

---

핵심 원칙

1. 중복 코드 제거 우선

• 동일한 로직이 2개 이상의 위치에 반복되면 유틸리티 함수로 추출
• 중복 코드는 버그 발생 가능성과 유지보수 비용 증가
• 유틸리티 함수로 통일하여 한 곳만 수정하면 전체 반영

2. 범용성과 재사용성

• 특정 도메인에 종속되지 않는 범용 함수로 설계
• 다양한 상황에서 사용 가능하도록 매개변수화
• 타입 안전성 지원 (타입 힌트, 타입 체크)

3. 명확한 책임 분리

• 하나의 함수는 하나의 명확한 작업만 수행
• 함수명이 기능을 명확히 표현
• 복잡한 로직은 여러 함수로 분리

---

유틸리티 함수 위치

디렉토리 구조

app/
└── utils/              # 공통 유틸리티 함수
    ├── __init__.py
    └── {domain}_extractor.py  # 예: json_extractor.py

네이밍 규칙

• 파일명: {기능}_extractor.py, {기능}_helper.py 등
• 함수명: extract_{대상}(), parse_{대상}(), format_{대상}() 등
• 명확하고 구체적인 이름 사용

---

설계 패턴

예시: JSON 추출 유틸리티

문제: LLM 응답에서 JSON을 추출하는 로직이 9개 위치에서 중복

해결: 범용 JSON 추출 함수 도입

# app/utils/json_extractor.py
def extract_json_from_text(text: str, expected_type: type = dict) -> Optional[Union[Dict, List]]:
    """다양한 형식의 LLM 응답에서 JSON 추출"""
    # 코드 블록, 설명 텍스트 등 다양한 형식 자동 처리

효과:

• 9개 위치의 중복 코드 제거 (90줄 절약)
• 한 곳만 수정하여 전체 반영 가능
• 다양한 LLM 응답 형식 자동 처리

---

재사용성 체크리스트

유틸리티 함수 생성 전 확인:

• 동일한 로직이 2개 이상의 위치에 있는가?
• 범용적으로 사용 가능한가? (도메인 종속성 없는가?)
• 함수명이 기능을 명확히 표현하는가?
• 타입 안전성을 지원하는가?
• 에러 처리가 적절한가?

---

금지 사항

• ❌ 특정 도메인에 종속된 로직을 유틸리티로 만들지 않음
• ❌ 너무 복잡한 로직 (책임 분리 필요)
• ❌ 한 곳에서만 사용되는 로직 (과도한 추상화 방지)
• ❌ 비즈니스 로직을 유틸리티에 포함 (서비스 레이어에 있어야 함)

---

참고:

• JSON 추출 유틸리티 사례: rb8001/app/utils/json_extractor.py
• 관련 troubleshooting: DOCS/journey/troubleshooting/251216_coldmail_processing_improvements.md