api-lens

🔍 API Lens – Chrome DevTools Extension

🎯 목표와 범위

프로젝트 목적

• 웹 개발자가 Chrome DevTools 안에서 API 응답(JSON/XML/Text)을 더 빠르고 가독성 있게 확인할 수 있도록 한다.
• 단순 조회를 넘어, 검색·필터·저장·복사·내보내기 등 반복적인 디버깅 과정을 자동화한다.
• 설치형 도구(Postman, Insomnia)에 비해 가볍고, DevTools 네이티브 환경에 완전히 통합된 확장을 지향한다.

범위

• Chrome Manifest V3 기반 확장 프로그램.
• DevTools 전용 패널에서 동작.
• 서버리스(IndexedDB + chrome.storage) 구조.
• 초기 버전에서는 외부 계정/동기화/클라우드 연동 없이 로컬 저장만 지원.
• UI는 다크모드/라이트모드 지원, 반응형 레이아웃 구성.

⚡ Quick Start

1. chrome://extensions에서 “압축해제된 확장 프로그램을 로드”로 이 레포지토리 디렉터리를 등록합니다.
2. 팝업이나 DevTools 패널을 처음 열 때 Chrome이 debugger 권한을 요청하면 허용합니다.
3. 사이드바에서 캡처할 탭을 체크하거나 “현재” 버튼으로 활성 탭을 즉시 추가하고, “전체”를 누르면 이후 새로 열리는 탭도 자동으로 수집됩니다.
4. 상태코드/도메인 필터와 검색을 조합해 기록을 탐색하고, 필요한 경우 JSON·CSV로 내보내거나 전체 삭제 버튼으로 정리하세요.
5. Authorization/Cookie 등 민감 헤더는 자동으로 마스킹되며 모든 데이터는 로컬 IndexedDB에 저장됩니다. 내보내기 전에 민감 값이 포함되지 않았는지 다시 확인하세요.

---

🧭 버전별 목표 기능 정의

v0.1.0 (MVP)

• DevTools 패널 생성 및 Network API 연동.
• 실시간 요청/응답 수집 및 로컬 저장.
• JSON/XML/Text 자동 포맷팅 및 보기.
• URL·메서드·상태·본문 키워드 검색.
• 복사, 다운로드, 북마크 기능.
• 최근 N개 응답 자동 관리 (FIFO 방식).
• 다크/라이트 모드 지원.

v0.2.0

• 응답 비교(diff) 기능.
• 하이라이트 규칙 설정 (예: 상태코드별 색상).
• Export 템플릿 저장.
• 간단한 설정 메뉴 (최대저장개수, spacing 등).

v0.3.0

• 응답 공유 (파일/링크).
• 팀용 프로 버전 설계 (백엔드 동기화).
• 즐겨찾기/검색 이력 클라우드 동기화.
• 고급 필터 (header 조건, 사이즈 조건 등).

---

🚀 현재 MVP 버전 개발 범위 정의 (v0.1.0)

목표

• “API 응답 포맷팅 + 검색 + 복사/저장”까지 완성된 상태로 Chrome Web Store 무료 배포.
• DevTools 네트워크 이벤트 기반으로 응답 수집하는 안정적인 코어 구축.

개발 범위

1. 기본 환경
   • MV3 manifest 설정
   • DevTools 페이지 등록 (devtools.html → panel.html)
   • 기본 아이콘, 로고, 브랜딩 에셋 추가
2. 데이터 수집
   • chrome.devtools.network.onRequestFinished 리스너 등록
   • 응답 메타데이터 (URL, 메서드, 상태, 타입) 수집
   • getContent()로 응답 Body 확보
   • IndexedDB 저장 + FIFO 삭제
3. UI/UX
   • 패널 레이아웃: 리스트(좌), 상세(우)
   • 검색바 / 필터 / 테마 토글
   • 상세뷰에 Pretty JSON / XML / Text 렌더러
   • Copy / Download / Bookmark 버튼
   • 상태바에 총 응답 수 표시
4. 저장 및 설정
   • IndexedDB에 요청 기록 저장
   • chrome.storage.local로 사용자 설정 유지
   • 북마크 상태 유지
5. 포맷팅 엔진
   • JSON 파싱 및 Pretty Print
   • XML 들여쓰기 렌더
   • 기타 MIME(text/plain 등)은 원문 출력
   • 파싱 실패 시 원본 텍스트 표시
6. 배포
   • 빌드 및 ZIP 패키징
   • Chrome Web Store 개발자 등록
   • 스크린샷, 설명, 정책 문서 업로드

---

⚙️ 기능 정의

1. 네트워크 캡처

• chrome.debugger API로 활성 탭에 Network 도메인을 attach하여 DevTools를 열지 않아도 XHR/Fetch 응답을 수집합니다.
• 텍스트/JSON/XML MIME 타입만 4만 자까지 저장하고, 초과분은 …(truncated) 처리해 메모리를 보호합니다.
• 탭 단위로 FIFO(최대 200개)로 관리하며, 중복 attach를 방지하기 위해 참조 카운트를 유지합니다.

2. 탭 모니터링 & 제어

• 사이드바에서 여러 탭을 동시에 선택하거나 전체 선택/해제를 수행할 수 있으며, “현재” 버튼으로 활성 탭을 즉시 추가할 수 있습니다.
• 탭을 닫거나 패널을 종료하면 자동으로 디버거가 분리되어 필요하지 않은 캡처가 발생하지 않습니다.
• 각 응답에는 캡처된 탭 ID가 함께 저장되며, 필터링 시 탭 단위로 데이터를 분리할 수 있습니다.

3. 검색 및 필터

• 자유 텍스트 + key:value 조건(method:POST, status:200, bookmark:true) 조합을 지원합니다.
• 상태 코드 그룹(2xx/3xx/4xx/5xx)과 도메인별 드롭다운 필터로 빠르게 그룹을 전환할 수 있습니다.
• 검색 조건은 UI에 유지되며, 필터 변경 시 즉시 리스트와 상세뷰에 반영됩니다.

4. 응답 뷰어 & 내보내기

• JSON은 prettify, XML/Text는 원문 렌더링하며 탭 정보와 응답 시간(ms)을 함께 제공합니다.
• 요청 본문과 요청/응답 헤더를 탭으로 전환하면서 확인할 수 있습니다.
• 현재 필터가 적용된 결과를 JSON 또는 CSV로 즉시 내보낼 수 있습니다.
• 사이드바 상단 카드에서 전체/2xx/4xx/5xx 통계를 한눈에 확인하고, 각 요청은 카드형 목록(메서드/상태/도메인/시간/미리보기)으로 표시됩니다.
• URL 프리뷰와 호스트 메타 정보가 리스트에 함께 노출되어 탐색 컨텍스트를 제공합니다.

5. 상세뷰 툴바

• 복사/다운로드/북마크 외에 전체 삭제, JSON 내보내기, CSV 내보내기를 지원합니다.
• 북마크 상태는 IndexedDB에 유지되어 팝업·DevTools 간에도 공유됩니다.

6. 테마 및 설정

• 다크 톤 기본값과 반응형 레이아웃을 제공하며 팝업(900×520)·새 창·DevTools 패널에서 동일한 UI를 재사용합니다.
• 추후 사용자 설정(chrome.storage.local)로 최대 보관 개수, 기본 필터 등을 확장할 수 있도록 구조화되어 있습니다.

7. 저장소 구조

• IndexedDB(api_lens.requests)에 요청/응답 본문, 헤더, 북마크, 탭 ID, duration 등을 보관합니다.
• FIFO 정책으로 최신 200개만 유지하며, Chrome 탭이 닫히면 관련 세션이 정리됩니다.

8. 권한 및 개인정보

• debugger, tabs, storage 권한을 사용하며, 사용자가 탭을 선택한 경우에만 일시적으로 attach 합니다.
• 캡처 데이터는 로컬 IndexedDB에만 저장되고 외부로 전송되지 않습니다.
• 민감 헤더(Authorization 등)는 수집 대상에서 제외하고, 필요 시 로그를 내보내기 전에 직접 검토할 수 있습니다.

---

🧱 기술 스택

코어 & 번들링

• 플랫폼: Chrome Extension (Manifest V3)
• 언어: TypeScript ("strict": true)
• 빌드 도구: Vite + @crxjs/vite-plugin (MV3 전용)
• 모듈 시스템: ES Modules

UI

• 프레임워크: React 18 (또는 Preact 대체 가능)
• 리스트 가상화: react-window
• 코드 하이라이트: highlight.js
• 상태관리: Zustand
• 스타일링: Tailwind CSS
• 테마: prefers-color-scheme + 사용자 토글
• 아이콘: Lucide-react (패널용 SVG)

데이터/저장

• 로컬 저장: IndexedDB via idb
• 설정 저장: chrome.storage.local
• 시간 처리: dayjs

파싱/포맷팅

• JSON: 기본 JSON.parse / stringify
• XML: fast-xml-parser
• MIME 판별: Content-Type 기반

검색/필터

• 커스텀 쿼리 파서 (key:value + free text)
• 필요 시 flexsearch 도입 고려

품질/빌드

• Lint/Format: ESLint + Prettier
• 테스트: Vitest + React Testing Library
• 패키징: Vite build → crxjs ZIP 산출
• CI/CD: GitHub Actions (태그 푸시 시 빌드 & zip)

권한

• debugger: 선택한 탭의 Network 이벤트를 수집하기 위해 사용되며, UI를 닫으면 자동으로 분리됩니다.
• tabs: 팝업/패널에서 열려 있는 탭 목록을 조회하고 제목·URL을 표시합니다.
• storage: 사용자 설정(향후 확장)과 로컬 응답 데이터를 유지합니다.

보안

• 민감 헤더 저장 금지
• 토큰 패턴 마스킹
• 외부 통신 없음

---

📦 주요 의존성

```json { “dependencies”: { “react”: “^18.3.1”, “react-dom”: “^18.3.1”, “zustand”: “^4.5.2”, “idb”: “^8.0.0”, “dayjs”: “^1.11.13”, “fast-xml-parser”: “^4.5.0”, “highlight.js”: “^11.10.0” }, “devDependencies”: { “typescript”: “^5.6.3”, “vite”: “^5.4.8”, “@crxjs/vite-plugin”: “^1.0.14”, “tailwindcss”: “^3.4.13”, “postcss”: “^8.4.47”, “autoprefixer”: “^10.4.20”, “eslint”: “^9.11.1”, “@typescript-eslint/eslint-plugin”: “^8.8.1”, “@typescript-eslint/parser”: “^8.8.1”, “prettier”: “^3.3.3”, “vitest”: “^2.1.4”, “@testing-library/react”: “^16.0.1” } }