대규모 트래픽이 예상되는 서비스에서 사용자의 지리적 위치를 파악해야 할 때, IP 주소를 기반으로 한 지역 정보 조회는 필수적인 기능입니다. 특히 이벤트 기반의 바이럴 마케팅 시스템처럼 순간적으로 유입량이 급증하는 환경에서는 조회 성능이 매우 중요해집니다. 이를 위해 Node.js 기반에서 QQWry 데이터 포맷을 활용한 경량 IP 조회 솔루션을 살펴봅니다.
해당 모듈은 QQWry.dat 형식의 순수 IP 데이터베이스를 직접 파싱하며, GBK 인코딩 변환을 위해 외부 의존성 없이 내장된 코드 테이블을 사용합니다. 초기 버전 대비 수십 배에 달하는 성능 개선을 거쳐, 현재는 마이크로초 단위의 초고속 응답을 제공합니다.
핵심 기능
- 단일 IP 또는 숫자 형태의 IP 값으로 지리 정보 검색
- 특정 범위 내 IP 대역에 대한 일괄 조회
- 점 표기법(IPv4 문자열)과 32비트 정수 간 상호 변환
설치 방법
npm install lib-qqwry기본 사용법
모듈 임포트 및 초기화 (일반 환경에서 약 70ms 소요):
const ipLocator = require('lib-qqwry').info();특정 IP의 위치 정보 확인:
const location = ipLocator.searchIP("202.103.102.10");IP 구간으로 범위 검색:
const rangeResult = ipLocator.searchIPScope("0.0.0.0", "1.0.0.0");API 상세
| 메서드 | 설명 | 매개변수 |
|---|---|---|
info(dataPath) |
데이터베이스 초기화 | dat 파일 경로 (선택, 기본값: __dirname + "/data/qqwry.dat") |
infoAsync(dataPath, callback) |
비동기 초기화 | 경로, 초기화 완료 후 실행할 콜백 |
unInfo() |
메모리 리소스 해제 | - |
searchIP(ip) |
단일 IP 조회 | IPv4 문자열 또는 숫자 값 |
searchIPScope(start, end) |
범위 조회 | 시작 IP, 종료 IP |
searchIPScopeAsync(s, e, cb) |
비동기 범위 조회 | 시작 IP, 종료 IP, 결과 콜백 |
DBUG(flag) |
디버깅 모드 전환 | 불리언 값 |
ipToInt(ip) |
문자열 IP → 32비트 정수 | IPv4 문자열 |
intToIP(num) |
32비트 정수 → 문자열 IP | 숫자 값 |
ipEndianChange(val) |
바이트 순서 교환 | 32비트 정수 (Little/Big-Endian 변환용) |
유틸리티 메서드 활용 예시
IP 문자열을 숫자로 변환:
const numericVal = ipLocator.ipToInt("255.255.255.255");
// 결과: 4294967295숫자를 IP 문자열로 복원:
const dotted = ipLocator.intToIP(4294967295);
// 결과: '255.255.255.255'호스트 바이트 순서 교환 (클라우드 환경에서 유용):
const swapped = ipLocator.ipEndianChange(0x010000FF);
// 결과: 4278190081 (0xFF000001)디버깅 모드 활성화
문제 해결 시 내부 동작을 추적하려면:
const tracker = require('lib-qqwry').DBUG(true).info();
// 비활성화
tracker.DBUG(false);고성능 서버 환경에서 IP 기반 지역 분석이 필요하다면, 본 모듈의 경량 설계와 빠른 초기화 특성을 고려해볼 만합니다.