Author: 0disoft

.clinerules

@@ -19,6 +19,8 @@
   # OpenAPI / GraphQL 스펙 – 엔드포인트·스키마·에러 모델
 - .handbook/data-model.md
   # DB ERD·인덱스·제약·마이그레이션 규칙
+- .handbook/api-optimization.md
+  # API 호출 최적화 및 비용 절감 가이드라인
 
 ### 3. 확장 (대형·프로덕션)
 - .handbook/quality.md

.handbook/api-optimization.md

@@ -0,0 +1,68 @@
+# API 호출 최적화 및 비용 절감 가이드라인
+
+이 문서는 프로젝트에서 API 호출 시 비용을 절감하고 성능을 최적화하기 위한 기술 및 인공지능 코딩 지침을 제공합니다.
+
+## 1. 개요
+
+효율적인 API 호출은 사용자 경험 개선, 서버 부하 감소, 그리고 클라우드 및 API 사용 비용 절감에 필수적입니다. 특히 사용자 입력에 반응하여 API를 호출하는 기능(예: 검색 자동 완성)의 경우, 불필요한 호출을 최소화하는 것이 중요합니다.
+
+## 2. 핵심 최적화 기술 (입력 기반 API 호출 시 우선 고려)
+
+사용자 입력에 따라 발생하는 API 호출(예: 검색어 입력)의 경우, 다음 기술들을 우선적으로 고려하여 적용해야 합니다.
+
+### 2.1. 디바운싱 (Debouncing)
+
+-   **개념**: 짧은 시간 내에 이벤트가 연속적으로 발생할 때, 마지막 이벤트 발생 후 일정 시간(예: 500ms)이 지나야만 콜백 함수를 실행합니다.
+-   **효과**: 사용자가 타이핑을 멈췄을 때만 API가 호출되도록 하여 불필요한 중간 호출을 제거합니다.
+-   **적용**: 검색 입력 필드의 `input` 또는 `keyup` 이벤트에 적용합니다.
+
+### 2.2. 클라이언트 캐싱 (Client-Side Caching)
+
+-   **개념**: 이전에 가져온 API 응답 데이터를 브라우저(로컬 스토리지, 세션 스토리지, 메모리 등)에 저장해 둡니다.
+-   **효과**: 동일한 요청이 다시 발생했을 때 API 호출 없이 캐시된 데이터를 즉시 반환하여 응답 속도를 높이고 비용을 절감합니다.
+-   **적용**: 자주 검색되거나 변경이 적은 데이터에 대해 고려합니다. 로컬 스토리지를 활용할 수 있습니다.
+
+### 2.3. 요청 중복 제거 (Request Deduplication)
+
+-   **개념**: 동일한 API 요청이 짧은 시간 내에 여러 번 발생했을 때, 첫 번째 요청만 실행하고 나머지 중복 요청들은 첫 번째 요청의 결과를 공유하도록 합니다.
+-   **효과**: 사용자가 같은 검색어를 빠르게 반복 입력하는 경우 불필요한 중복 API 호출을 방지합니다.
+-   **적용**: 진행 중인 요청 목록을 관리하여 새로운 요청 전에 확인하는 로직을 추가합니다.
+
+## 3. 기타 유용한 최적화 기술
+
+다음 기술들은 특정 상황이나 아키텍처에 따라 API 호출 최적화 및 비용 절감에 기여할 수 있습니다.
+
+-   **스로틀링 (Throttling)**: 일정 시간(예: 200ms) 동안 최대 한 번만 콜백 함수를 실행하도록 제한합니다. (디바운싱과 유사하나 동작 방식이 다름)
+-   **요청 배치 (Batch Requests)**: 여러 개의 작은 API 요청을 하나의 큰 요청으로 묶어 보냅니다.
+-   **HTTP 캐싱 (HTTP Caching)**: HTTP 헤더(Cache-Control, ETag, Last-Modified 등)를 활용하여 브라우저나 CDN 레벨에서 응답을 캐싱합니다.
+-   **서비스 워커 캐싱 (Service Worker Caching)**: 서비스 워커를 사용하여 네트워크 요청을 가로채고 캐싱 전략을 구현합니다.
+-   **메모이제이션 (Memoization)**: 함수의 결과를 캐싱하여 동일 입력에 대해 계산 없이 캐시된 결과를 반환합니다. (클라이언트 캐싱과 유사)
+-   **GraphQL 쿼리 배칭 (GraphQL Query Batching)**: 여러 GraphQL 쿼리를 하나의 HTTP 요청으로 묶습니다.
+-   **사전 페치 (Prefetch)**: 사용자가 필요로 할 가능성이 있는 데이터를 미리 가져와 캐싱합니다.
+-   **레이지 로딩 (Lazy Loading)**: 당장 필요하지 않은 데이터나 컴포넌트는 나중에 로딩합니다.
+-   **페이지네이션 (Pagination)**: 대량의 데이터를 작은 페이지 단위로 나누어 가져옵니다.
+-   **증분 정적 재생성 (ISR - Incremental Static Regeneration)**: 정적 페이지와 서버 렌더링의 장점을 결합하여 동적 콘텐츠를 효율적으로 제공합니다.
+-   **CDN 활용 (CDN Usage)**: 정적 자산이나 캐싱 가능한 API 응답을 사용자에게 가까운 엣지 서버에 캐싱하여 전송 속도를 높이고 원본 서버 부하를 줄입니다.
+-   **API 게이트웨이 캐싱 (API Gateway Caching)**: API 게이트웨이 레벨에서 API 응답을 캐싱합니다.
+-   **조건부 요청 (Conditional Requests - ETag/If-Modified-Since)**: 데이터 변경이 없을 경우 서버가 전체 응답 대신 304 Not Modified 상태 코드를 반환하도록 합니다.
+-   **연결 재사용 (Keep-Alive)**: 하나의 TCP 연결을 여러 HTTP 요청에 재사용하여 연결 설정 오버헤드를 줄입니다.
+-   **페이로드 압축 (Payload Compression - Gzip/Brotli)**: 전송되는 데이터 크기를 줄여 대역폭 사용량과 전송 시간을 감소시킵니다.
+-   **델타 동기화 (Delta Sync)**: 전체 데이터를 다시 가져오는 대신 변경된 부분만 동기화합니다.
+-   **회로 차단기 패턴 (Circuit Breaker Pattern)**: 실패한 서비스에 대한 요청을 일시적으로 차단하여 시스템 장애 확산을 방지합니다.
+-   **레이트 리밋팅 (Rate Limiting)**: 특정 기간 동안 클라이언트나 사용자의 API 호출 횟수를 제한하여 과부하를 방지합니다.
+-   **지수 백오프 (Exponential Backoff)**: 실패한 요청을 재시도할 때 대기 시간을 점진적으로 늘려 서버 부하를 줄입니다.
+-   **로드 셰딩 (Load Shedding)**: 시스템이 과부하 상태일 때 일부 요청을 의도적으로 거부하여 핵심 기능의 가용성을 유지합니다.
+
+## 4. 인공지능 코딩 지침
+
+인공지능은 코드를 작성할 때 다음 지침을 참고하여 API 호출의 비용 효율성과 성능을 고려해야 합니다.
+
+-   **입력 기반 API 호출**: 검색 자동 완성 등 사용자 입력에 따라 API가 호출되는 기능을 구현할 때는 **디바운싱**을 기본적으로 적용해야 합니다. 지연 시간은 사용자 경험과 API 부하를 고려하여 적절히 설정합니다 (일반적으로 300ms ~ 500ms).
+-   **캐싱 가능성 검토**: 동일한 데이터에 대한 반복적인 API 호출이 예상되는 경우, **클라이언트 캐싱** (로컬 스토리지, 메모리 캐시 등) 적용 가능성을 적극적으로 검토합니다. 캐시 만료 정책도 함께 고려해야 합니다.
+-   **중복 요청 방지**: 사용자의 빠른 인터랙션으로 인해 동일한 API 요청이 여러 번 발생할 수 있는 시나리오에서는 **요청 중복 제거** 로직을 구현하여 불필요한 서버 부하를 방지합니다.
+-   **데이터 양 고려**: 대량의 데이터를 가져와야 하는 경우, **페이지네이션** 또는 **레이지 로딩**을 적용하여 초기 로딩 시 가져오는 데이터 양을 최소화합니다.
+-   **네트워크 효율**: 가능한 경우 **요청 배치**나 **GraphQL 쿼리 배칭**을 활용하여 HTTP 요청 횟수를 줄입니다.
+-   **오류 처리 및 재시도**: API 호출 실패 시 **지수 백오프**를 적용한 재시도 로직을 고려하여 서버에 불필요한 부하를 주지 않으면서 안정적으로 데이터를 가져오도록 합니다.
+-   **문서 참고**: 새로운 API 호출 로직을 구현하거나 기존 로직을 수정할 때, 이 문서를 참고하여 최적화 기법 적용 가능성을 항상 검토해야 합니다.
+
+이 가이드라인은 지속적으로 업데이트될 수 있습니다. 코딩 시 최신 버전을 참고하십시오.