ApiCatcher
ApiCatcher
iOS용 HTTP(s) 패킷 캡처 및 디버깅 도구

ApiCatcher 사용 설명서

ApiCatcher는 개발자, 테스트 엔지니어 및 네트워크 문제 해결 담당자를 위해 만들어진 전문가용 iOS 네트워크 디버깅 도구입니다. 로컬에 가상 게이트웨이를 설정하여 개발 중인 앱의 HTTP/HTTPS 및 WebSocket 트래픽을 쉽게 캡처, 보기, 분석 및 디버그할 수 있도록 지원합니다.

이 설명서에서는 일일 개발 디버깅, Mock 테스트, API 자동화 분석 및 성능 문제 해결에 도움이 되는 각 기능 모듈의 구성 및 사용 방법을 자세히 설명합니다.

목차

  1. 기본 준비: 인증서 구성 및 디버그 권한 부여
  2. 트래픽 필터링: 디버깅 대상 정확한 지정
  3. API Mocking 및 수정: 재작성 규칙 (Rewrite)
  4. 고급 사용자 지정 처리: JavaScript 스크립트 (Script)
  5. 자동화 테스트: 콤보 재생 (Combo Replay)
  6. 백그라운드 모니터링: 예약된 작업 (Scheduled Tasks)
  7. 품질 및 성능 문제 해결: API 스캔 (API Scan)
  8. 유틸리티 도구: 암호화/복호화 및 데스크톱 동기화

1. 기본 준비: 인증서 구성 및 디버그 권한 부여

1.1 CA 인증서 설치 및 신뢰 (HTTPS 디버깅에 필수)

최신 애플리케이션의 데이터 통신은 일반적으로 HTTPS 프로토콜을 기반으로 암호화됩니다. 자체 앱을 개발하고 디버깅할 때 API의 일반 텍스트 요청 및 응답 데이터를 제대로 보려면 암호 해독을 허용하도록 디버깅 인증서를 구성하고 신뢰해야 합니다.

ApiCatcher는 두 가지 인증서 구성 방법을 제공합니다.

  1. 시스템에서 기본으로 생성한 CA 인증서 사용 (대부분의 시나리오 권장): 아래 지침에 따라 ApiCatcher가 자동으로 생성한 전용 CA 인증서를 설치합니다.
  2. 자체 인증서 가져오기 (엔터프라이즈 인증서): 회사 자체 서명 인증서를 사용해야 하는 경우 이 섹션을 건너뛰고 1.2 엔터프라이즈 인증서 가져오기 섹션을 읽으십시오.

기본 CA 인증서 사용 단계:

  1. 앱에서 "인증서 설치"를 클릭하면 시스템이 브라우저로 이동하여 구성 프로필을 다운로드합니다.
  2. iOS "설정" -> "일반" -> "VPN 및 기기 관리" 로 이동하여 다운로드한 ApiCatcher 프로필을 설치합니다.
  3. 중요 단계: "설정" -> "일반" -> "정보" -> "인증서 신뢰 설정" 으로 이동하여 ApiCatcher CA 로 시작하는 인증서를 찾아 스위치를 켜서 완전히 신뢰합니다.

💡 일반적인 문제 해결 가이드:

  • 디버깅 중 "연결 시간 초과" 또는 비정상적인 상태 코드가 발생하는 경우: 일반적으로 3단계에서 인증서를 "완전히 신뢰"하지 않았기 때문입니다.
  • 앱을 삭제하고 다시 설치한 경우: 기존 디버깅 인증서는 이미 무효화되었습니다. 시스템 설정에서 기존 프로필을 삭제하고 위의 과정을 다시 반복해야 합니다.

1.2 엔터프라이즈 인증서 가져오기 (기업 인트라넷 디버깅 시나리오)

사내 개발 테스트 중 일부 내부 앱은 특정 인증서 신뢰 정책(예: 사내 CA만 신뢰)을 설정할 수 있습니다.

  • 용도: 기업에서 제공하는 .pem 또는 .p12 인증서를 가져와 내부 테스트 도메인(예: *.corp.internal)과 바인딩하여 로컬 디버깅 중 합법적인 TLS 핸드셰이크를 완료합니다.
  • 참고: 가져오기 또는 설정 수정은 반드시 캡처를 중지한 상태에서 수행해야 하며, 완료 후 다시 시작해야 적용됩니다.

1.3 커스텀 인증서 사용

엔터프라이즈 인증서가 없고 ApiCatcher에서 제공하는 기본 인증서를 사용하고 싶지 않은 개인 개발자의 경우, 엔터프라이즈 인증서 기능을 사용하여 자체 인증서를 가져올 수 있습니다. 자세한 내용은 문서를 참조하세요: 커스텀 인증서 사용

2. 트래픽 필터링: 디버깅 대상 정확한 지정

개발 중 시스템 기반이나 다른 백그라운드 앱의 트래픽 간섭을 제거하기 위해 필터링 규칙을 구성하여 현재 디버깅 중인 프로젝트에만 집중하는 것이 좋습니다.

  • 차단 목록: 차단 목록에 있는 도메인은 기록되지 않습니다. 허용 목록이 비어 있으면 기본적으로 차단 목록 이외의 모든 요청이 기록됩니다.
  • 허용 목록: 허용 목록에 규칙이 포함되어 있으면 시스템은 허용 목록과 일치하는 요청만 기록하며 다른 트래픽은 디버깅 채널로 들어오지 않습니다.
  • 구성 팁: * 와일드카드를 지원합니다. 예를 들어 *.example-api.com을 입력하면 해당 메인 도메인 아래의 모든 테스트 환경 하위 도메인과 일치합니다.

💡 일반적인 문제 해결 가이드:

  • 대상 앱의 요청이 표시되지 않음: 허용 목록을 활성화했지만 대상 도메인을 입력하지 않았거나, 대상 도메인을 실수로 차단 목록에 추가하지 않았는지 확인하십시오.
  • 구문 주의: 복잡한 정규식을 작성할 필요 없이 기본 별표 일치(예: *.api.com)를 사용하십시오.

3. API Mocking 및 수정: 재작성 규칙 (Rewrite)

프론트엔드와 백엔드를 병렬로 개발할 때 백엔드 API가 아직 준비되지 않았거나 특정 예외 상태 코드를 테스트해야 하는 경우가 많습니다. 재작성 규칙을 통해 API Mocking 및 경계 테스트를 우아하게 수행할 수 있습니다.

3.1 범위 구성 (Scope)

재작성 규칙을 추가할 때 다른 관련 없는 요청에 영향을 주지 않도록 규칙이 적용될 범위를 지정해야 합니다. 시스템은 매우 쉬운 구성 방법을 제공하며 복잡한 일치 조건을 작성할 필요가 없습니다.

  • 도메인/호스트 선택 (Host): 이미 캡처된 대상 호스트의 드롭다운 목록에서 빠르게 선택하거나 수동으로 입력할 수 있습니다. 와일드카드(*.example.com 등)가 지원됩니다.
  • API 선택 (Path): Host를 선택한 후 목록에서 특정 API를 직접 선택하거나(Method와 Path가 자동으로 입력됨) 특정 경로를 수동으로 입력할 수 있습니다(/api/v1/*과 같이 경로에 * 와일드카드 일치 지원).

💡 효율성 팁: 목록에서 기존 API를 선택하면 시스템이 후속 Mock 응답 템플릿이나 Headers를 자동으로 미리 채워(Prefill) 설정 시간을 크게 절약해 줍니다!

3.2 디버깅 동작 (Rewrite Action)

  • 리디렉션 (Redirect): 요청을 다른 주소로 라우팅합니다(예: 프로덕션 트래픽을 Localhost 또는 스테이징 환경으로 리디렉션).
  • Mock 응답: 실제 네트워크 요청을 보내지 않고 미리 설정된 테스트 데이터(JSON/XML)를 직접 반환합니다. 상태 코드(404, 500 예외 시뮬레이션 등), 응답 헤더 및 응답 본문 구성을 지원합니다.
  • 삭제 (Drop):
    • 요청 삭제: 요청을 보낼 수 없는 상태 시뮬레이션(예: 네트워크 연결 끊김 시나리오).
    • 응답 삭제: 서버 무응답/시간 초과 시뮬레이션.
  • 지연 (Delay): 의도적으로 네트워크 지연을 주입하여 약한 네트워크 환경에서 앱의 Loading 상호 작용 성능을 테스트합니다.
  • 요청/응답 수정 (Modify):
    • Header 편집: 요청 헤더에 테스트 Token을 주입하거나 User-Agent를 수정하는 데 사용합니다.
    • Body 교체: 요청 본문이나 응답 본문 내용을 완전히 바꿉니다.
    • 정규식 검색 및 Body 교체: JSON의 필드를 세밀하게 바꿉니다. 예를 들어 정규식을 사용하여 "status": "pending" 을 "status": "success" 로 바꾸어 후속 논리를 테스트합니다.

💡 일반적인 문제 해결 가이드:

  • 규칙이 적용되지 않음: 우선 순위가 더 높은(최근에 추가된) 다른 규칙이 현재 규칙을 덮어쓰고 있습니다.
  • 정규식 바꾸기 실패: JSON 데이터에는 들여쓰기와 공백이 포함되는 경우가 많습니다. 정규식이 공백 문자(예: \s*)를 고려하지 않으면 일치에 실패할 수 있습니다. 내장된 "테스트" 패널을 사용하여 식을 확인하는 것이 좋습니다.

4. 고급 사용자 지정 처리: JavaScript 스크립트 (Script)

동적 계산이 필요한 복잡한 Mock 시나리오(예: 타임스탬프 서명 계산, 동적 데이터 어셈블리)의 경우 스크립트 엔진은 최고 수준의 프로그래밍 가능한 디버깅 기능을 제공합니다.

4.1 핵심 기능 패널 및 보조 도구

수동 코딩 외에도 ApiCatcher는 스크립트 작성 및 확인을 완료하는 데 도움이 되는 강력한 보조 도구를 제공합니다.

  • AI 자동 생성 스크립트: 코드를 한 줄도 작성할 필요가 없습니다. 자연어 명령어(예: "응답 본문의 price 필드 값을 9.9로 변경하고 discount_tag: true를 추가해줘")만 입력하면 내장된 AI 비서가 표준 JS 코드를 자동으로 생성하고 입력해 줍니다.
  • 로컬 테스트 환경 (Test Script): 공식적으로 저장하고 적용하기 전에 직접 클릭하여 테스트할 수 있습니다. 기록에서 실제로 캡처된 요청을 선택하여 스크립트에 전달하면 시스템이 수정 전후의 데이터 비교 결과와 오류 로그를 직관적으로 표시하여 구문이 올바른지 확인합니다.
  • 원격 스크립트 호스팅 (Remote Script): 공용 http:// 또는 https:// 스크립트 URL을 직접 입력할 수 있습니다. ApiCatcher는 로컬에서 클라우드 스크립트를 로드하고 실행하므로 팀 내에서 공통 Mock 규칙을 통합하여 배포하고 유지 관리하는 데 매우 유용합니다!

4.2 스크립트 핵심 기능

스크립트 작성 방법에 대해서는 다음 문서를 참조하십시오: APICatcher 스크립트 기능 사용 가이드

미리 정의된 수명 주기 함수만 구현하면 됩니다.

// 전송된 요청 처리
function interceptRequest(request) {
    // request.method, request.url, request.headers, request.body, request.queryParams
    if (request.path === '/api/v1/test') {
        request.headers['X-Debug-Token'] = 'test_token';
    }
    // 반환 동작: passthrough(통과), modify(수정), mock(모의), drop(삭제)
    return { action: 'modify', request: request };
}

// 수신된 응답 처리
function interceptResponse(request, response) {
    // response.statusCode, response.headers, response.body
    if (response.body) {
        var data = safeJsonParse(response.body); // 내장된 안전한 구문 분석 함수
        if (data) {
            data.mock_field = true;
            response.body = JSON.stringify(data);
            return { action: 'modify', response: response };
        }
    }
    return { action: 'passthrough' };
}

4.2 내장된 고급 API

  • localStore: 요청 간의 상태 유지에 사용됩니다. 예를 들어 로그인 API에서 인증 상태를 저장하고 이후 API에서 자동으로 주입합니다.
    • localStore.write('session_id', 'abc')
    • var t = localStore.read('session_id')
  • httpClient: 스크립트 실행 중 추가 네트워크 요청 보내기를 지원합니다(외부 상태 동기화 또는 동적 설정 가져오기에 사용).
    • var res = httpClient.get('https://api.ipify.org')

💡 일반적인 문제 해결 가이드:

  • 구문 또는 런타임 오류: 내장된 "테스트 스크립트" 버튼을 사용하여 논리를 확인합니다. console.log("...")를 사용하여 "로그(Logs)" 페이지에서 출력을 볼 수 있습니다.
  • 수명 주기 충돌: 특정 요청이 이미 우선순위가 더 높은 "재작성 규칙"에 의해 Mock 또는 Drop으로 실행된 경우 해당 요청에 대한 이후 스크립트 실행 흐름으로 들어가지 않습니다.

5. 자동화 테스트: 콤보 재생 (Combo Replay)

단일 API 테스트로는 전체 비즈니스 흐름 검증(예: 로그인 -> 권한 획득 -> 정보 조회 -> 양식 제출)을 충족할 수 없습니다. Combo Replay는 여러 관련 API의 시각적 오케스트레이션과 자동화된 회귀 테스트를 지원합니다.

5.1 구성 단계

  1. 노드 추가: 기록의 비즈니스 흐름 요청을 순서대로 캔버스에 추가합니다.
  2. 종속성 설정: 노드 간의 방향성 간선을 설정하여 요청이 종속성 순서에 따라 엄격하게 실행되도록 합니다.
  3. 매개변수 매핑 (종속성 주입): 데이터 흐름을 구성합니다. 업스트림 API 응답의 특정 필드를 다운스트림 요청에 동적으로 주입합니다.

5.2 매개변수 매핑 구성 세부 정보

  • 추출 소스: 업스트림 응답 본문(responseBody) 또는 응답 헤더(responseHeader)에서 추출할 수 있습니다.
    • 추출 경로: JSON 응답 본문인 경우 JSON Path(예: data.session.token)를 직접 사용합니다.
  • 주입 대상: 다운스트림 요청 헤더(requestHeader), URL 매개변수(queryParam) 또는 요청 본문(requestBody)에 주입할 수 있습니다.
  • 선택적 접두사 (Optional Prefix): 특정 표준의 자동 완성에 사용됩니다. 예를 들어 추출된 값이 abc이지만 표준에서 헤더에 Bearer abc를 포함해야 하는 경우 여기에 Bearer 를 입력하기만 하면 자동으로 연결됩니다.

💡 일반적인 문제 해결 가이드:

  • 매개변수가 성공적으로 추출되지 않음: 수동으로 경로를 작성하여 발생하는 형식 계층 오류를 피하려면 캔버스의 노드에 내장된 "샘플 응답 본문"의 트리 구조를 사용하여 클릭하여 선택하십시오.

6. 백그라운드 실행: 예약된 작업 (Scheduled Tasks)

VPN 프로세스를 기반으로 하는 백그라운드 상주 기능을 활용하여 "예약된 작업"을 통해 특정 요청이나 Combo Replay 규칙을 주기적으로 실행할 수 있습니다. 일반적인 적용 시나리오: 이커머스 "플래시 세일" 이벤트를 개발하거나 테스트할 때 시간 창이 매우 짧아 수동으로 클릭하여 테스트하면 순간을 놓치는 경우가 많습니다. 이때 예약된 작업을 구성하여 플래시 세일이 시작되기 전에 API가 높은 빈도로 주문 제출을 자동 요청하도록 하여 플래시 세일의 동시성 안정성과 비즈니스 로직을 충분히 검증할 수 있습니다.

6.1 일정 구성 (Schedule Type)

  • Cron 표현식: 표준 5자리 Cron 구문(예: */5 * * * *는 5분마다 실행됨을 의미)을 사용합니다. 내장 AI를 사용하여 생성할 수도 있습니다.
  • 사용자 지정 구성: 시작 시간, 간격 및 최대 실행 횟수의 세부 설정을 지원합니다.

6.2 자동 종료 조건 (Auto Terminate)

비정상적인 상황에서 의미 없는 재시도를 피하거나 목표 달성 후 자동으로 종료되도록 종료 조건을 설정합니다.

  • JSON 필드 일치: 예를 들어 "플래시 세일 테스트" 시나리오에서는 반환 결과의 code 필드를 모니터링합니다. code가 200(구매 성공)과 같거나 400(재고 없음, 이벤트 종료 의미)과 같으면 종료가 트리거됩니다.
  • 정규식 일치: 응답 본문에 대해 전체 텍스트 일치를 수행합니다. "msg": "구매 성공" 또는 "error": "이벤트 종료"와 같은 문자 특징이 일치하는 한 작업이 완전히 자동으로 중지됩니다.

💡 일반적인 문제 해결 가이드:

  • 작업을 실행할 수 없음: iOS 시스템에는 엄격한 백그라운드 관리가 있습니다. 메모리가 부족할 때 시스템이 VPN 프로세스를 회수하여 예약된 작업도 함께 일시 중지될 수 있습니다.
  • 기록 레코드 없음: 예약된 작업은 기본 엔진에서 직접 시작하는 모니터링 요청이며 기본 앱의 일반 "기록"에 기록되지 않습니다. 작업 전용 "실행 기록" 패널에서 성공률, p95 등의 보고서를 확인해야 합니다.
  • 규칙 업데이트가 반영되지 않음: 예약된 작업을 생성할 때 규칙의 스냅샷이 바인딩됩니다. 원래 "Combo Replay" 규칙이 변경된 경우 예약된 작업을 다시 생성해야 합니다.

7. 품질 및 성능 문제 해결: API 스캔 (API Scan)

로컬로 캡처된 트래픽 레코드를 기반으로 비침입적 API 품질, 보안 규정 준수 및 성능 상태 점검을 제공합니다. 모든 분석은 기기의 로컬 메모리 내에서 완전히 완료됩니다.

7.1 내장 스캔 엔진

  • 민감 정보 자가 진단: 전화번호, 주민등록번호, 이메일 및 클라우드 서비스 자격 증명(AWS Key, OpenAI API Key 등)의 일반 텍스트 전송 감지를 지원하여 프론트엔드 및 API 설계자가 데이터 비식별화 누락을 조기에 발견하도록 돕습니다.
  • 비정상적인 스택 유출: 응답 본문에서 부주의하게 반환된 Java, Python 또는 SQL 호출 스택을 식별합니다.
  • 고빈도 호출 분석: 설정된 임계값(예: 평균 요청 간격이 특정 밀리초 미만)을 기반으로 무한 루프 또는 잘못된 논리로 인한 중복 API 호출이 있는지 문제를 해결합니다.
  • 소요 시간 평가: 각 API의 p95 및 p99 지연 시간을 집계하고 계산하여 백엔드 성능 병목 현상을 식별하는 데 도움을 줍니다.

7.2 사용자 지정 품질 감지 (Custom Scan)

비즈니스에 맞춤화된 규정 준수 검사를 실행하기 위해 JS 스크립트를 작성할 수 있습니다.

  • 반환 값 규칙: 함수가 요청이 예상과 일치한다고 판단하면 null을 반환합니다. 규정 준수 위반이 감지된 경우(응답 본문이 너무 큼, 보안 헤더 누락 등) 간결한 설명(200자 이하)을 반환하면 시스템이 자동으로 스캔 보고서에 포함합니다.

💡 일반적인 문제 해결 가이드:

  • 결과가 분석되지 않음: "스캔 범위 (Host/Session)"에 순수한 정적 리소스가 아니라 유효한 JSON/API 트래픽 레코드가 실제로 포함되어 있는지 확인하십시오. 경험을 보장하기 위해 한 번의 스캔에 대한 레코드 수에 상한이 있습니다.

8. 유틸리티 도구: 암호화/복호화 및 데스크톱 동기화

8.1 개발자 도구 상자 (Decrypt/Encrypt)

메시지 암호화 전송에 대처하기 위해 일반적인 코덱 도구가 내장되어 있습니다.

  • AES 복호화: 사용자 지정 키(Key) 및 초기 벡터(IV)를 입력하여 Payload를 빠르게 복호화하고 테스트하도록 지원합니다.
  • Base64 / URL Encode / MD5 / SHA256.
  • 사용자 지정 처리: 선택한 텍스트의 데이터 변환을 실행하기 위해 한 번만 실행되는 JS 스니펫 작성을 지원합니다.

8.2 데스크톱 실시간 동기화 (Realtime Sync)

용도: PC 측에서 더 넓은 시야로 데이터를 디버깅해야 하는 경우 WebSocket 프로토콜을 사용하여 기기에서 캡처한 데이터 패킷을 ApiCatcher Desktop 애플리케이션으로 원활하게 푸시할 수 있습니다. 구성:

  • 근거리 통신망에 할당된 WebSocket 주소를 입력합니다.
  • 핸드셰이크 성공을 확인하기 위해 반드시 사전에 "연결 테스트"를 통과하십시오.
  • 문제 해결: 모바일 장치에 "로컬 네트워크" 권한이 부여되었는지, PC 방화벽에서 해당 포트가 허용되었는지, 둘 다 동일한 LAN 서브넷에 있는지 확인하십시오.