Growthman

로컬 개발용 Mock API 서버입니다. 웹 UI에서 Mock 엔드포인트를 등록하고 테스트할 수 있습니다.

주요 기능

• 웹 UI로 Mock API 엔드포인트 등록/수정/삭제
• OpenAPI 스펙 파일 임포트 (자동으로 Mock 엔드포인트 생성)
• Express 스타일 경로 파라미터 지원 (:id 등)
• 내장 API 테스트 기능
• Base URL 복사 기능
• SQLite 기반 데이터 영속화 (~/.growthman/data.db)

설치 및 실행

npx로 바로 실행 (권장)

npx @kurly-growth/growthman

실행하면 자동으로 브라우저가 열립니다. 데이터는 ~/.growthman/ 디렉토리에 저장됩니다.

# 포트 지정
PORT=8080 npx @kurly-growth/growthman

전역 설치

npm install -g @kurly-growth/growthman
growthman

사용법

1. http://localhost:3100 접속
2. "+ New Endpoint" 버튼으로 Mock API 등록
   • Path: /v1/users/:id (Express 스타일 경로 지원)
   • Method: GET, POST, PUT, DELETE 등
   • Status Code: 200, 400, 500 등
   • Response Body: JSON 응답
3. http://localhost:3100/api/mock/{등록한 경로}로 요청
4. "Import OpenAPI" 버튼으로 OpenAPI 스펙 파일 일괄 임포트

프록시 기능

각 Mock 엔드포인트에는 isMockEnabled 플래그가 있으며, 이 값에 따라 Mock 응답과 프록시 동작이 결정됩니다.

동작 알고리즘

요청 수신
  │
  ├─ 매칭되는 엔드포인트 있음
  │   ├─ isMockEnabled = true  → Mock 응답 반환
  │   └─ isMockEnabled = false
  │       ├─ X-Growthman-Target 헤더 있음 → 대상 서버로 프록시
  │       └─ X-Growthman-Target 헤더 없음 → Mock 응답 반환 (fallback)
  │
  └─ 매칭되는 엔드포인트 없음
      ├─ X-Growthman-Target 헤더 있음 → 대상 서버로 프록시
      └─ X-Growthman-Target 헤더 없음 → 404 반환

• Mock 모드 (isMockEnabled = true): 항상 저장된 Mock 응답을 반환합니다.
• 프록시 모드 (isMockEnabled = false): X-Growthman-Target 헤더에 지정된 서버로 요청을 프록시합니다. 헤더가 없으면 Mock 응답으로 fallback합니다.
• 프록시된 응답에는 X-Growthman-Proxied: true 헤더가 추가됩니다.

로컬 네트워크 서비스 등록 (DNS-SD)

서버 시작 시 macOS 환경에서 dns-sd를 사용하여 로컬 네트워크에 서비스를 자동 등록합니다. 같은 네트워크의 다른 기기(모바일 등)에서 별도 IP 설정 없이 Growthman 서버에 접근할 수 있습니다.

# 등록되는 서비스 정보
# 서비스명: growthman-{사용자명} (CLI 최초 실행 시 입력)
# 타입: _http._tcp
# 포트: 3100 (또는 PORT 환경변수 값)

서비스 이름 설정

CLI(growthman) 최초 실행 시 서비스 이름을 입력받으며, 이후 실행에서는 저장된 이름을 자동으로 사용합니다. 같은 네트워크에서 여러 개발자가 서비스를 구분할 수 있습니다.

# 서비스 이름 재설정 (다음 실행 시 다시 입력 프롬프트 표시)
growthman --rename

로컬 개발(pnpm dev)에서는 .env 파일의 GROWTHMAN_SERVICE_NAME으로 설정합니다.

# .env
GROWTHMAN_SERVICE_NAME=growthman-myname

다른 기기에서 dns-sd -B _http._tcp local 명령으로 서비스를 검색하거나, Bonjour 브라우저 앱으로 확인할 수 있습니다. 서버가 종료되면 서비스 등록이 자동으로 해제됩니다.

로그 레벨

--log-level 플래그로 프록시 로깅 상세도를 인터랙티브하게 선택할 수 있습니다.

growthman --log-level

Log level:
  ❯ info    Request/response summary (default)
    error   Proxy failures only
    warn    + 4xx/5xx responses
    debug   + Response body (pretty-printed)
    trace   + Request headers

화살표 키(↑↓)로 이동, Enter로 선택합니다. 로그는 상태코드에 따라 색상이 다르게 출력됩니다 (2xx 초록, 3xx 시안, 4xx 노랑, 5xx 빨강).

환경변수로도 설정할 수 있습니다.

GROWTHMAN_LOG_LEVEL=debug npx @kurly-growth/growthman

| 레벨 | 출력 내용 | |------|-----------| | error | 프록시 실패(502)만 | | warn | error + 4xx/5xx 응답 | | info (기본값) | 요청/응답 한 줄 요약 (method, url, status, duration) | | debug | info + 응답 바디 (JSON pretty-print) | | trace | debug + 요청 헤더 |

로컬 개발

pnpm install
cp .env.example .env
pnpm db:reset     # DB 스키마 생성 + 시드 데이터
pnpm dev          # http://localhost:3100

기타 명령어

pnpm dev          # 개발 서버 실행 (DB 초기화 없이)
pnpm build        # 프로덕션 빌드
pnpm db:reset     # DB 초기화 (마이그레이션 + 시드)
pnpm db:seed      # 시드 데이터만 추가

배포 (npm publish)

pnpm release          # patch 버전 업 (0.1.19 → 0.1.20)
pnpm release:minor    # minor 버전 업 (0.1.19 → 0.2.0)
pnpm release:major    # major 버전 업 (0.1.19 → 1.0.0)