15-crawler-patterns

웹 크롤링 파이프라인 패턴 라이브러리. 멀티소스 데이터 수집 → 정규화 → 중복제거 → 검증 → 저장의 5단계 파이프라인을 제공합니다.

출처

아키텍처

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   1. 수집    │ →  │  2. 정규화   │ →  │ 3. 중복제거  │ →  │   4. 검증   │ →  │   5. 저장   │
│  (Sources)   │    │ (Normalizer) │    │(Deduplicator)│    │ (Validator) │    │ (DB Writer) │
└──────┬───────┘    └──────┬───────┘    └──────┬───────┘    └──────┬───────┘    └──────┬───────┘
       │                   │                   │                   │                   │
  BaseSource          korean-text         deduplicator          Zod 스키마       AbstractDbWriter
  BaseApiSource       global-text        cross-source-dedup                     InMemoryDbWriter
  fetcher             currency-converter  completeness

핵심 패턴

• 소스 어댑터 패턴: BaseSource (HTML) / BaseApiSource (REST API) 추상 클래스
• 파이프라인 패턴: 5단계 순차 처리 (run-pipeline.ts)
• 교차 소스 중복제거: 5계층 (키 → DB → URL → 제목유사도 → 지문)
• 의존성 주입: 소스 팩토리, DB Writer, 정규화 옵션 모두 외부 주입

파일 인덱스

의존성

선택적 환경변수:

• OPEN_EXCHANGE_RATES_APP_ID: 실시간 환율 API 키 (미설정 시 고정 환율 사용)

사용 예시

1. 소스 어댑터 구현

import { BaseSource } from './15-crawler-patterns/sources/base-source';
import type { RawItem } from './15-crawler-patterns/types';
import type { SourceConfig } from './15-crawler-patterns/config';

const MY_SOURCE_CONFIG: SourceConfig = {
  id: 'my-source',
  name: '내 소스',
  baseUrl: 'https://example.com',
  listUrl: (page) => `https://example.com/items?page=${page}`,
  detailUrl: (id) => `https://example.com/items/${id}`,
  delay: 1500,
  itemsPerPage: 20,
  categories: {},
};

class MySource extends BaseSource {
  constructor() {
    super(MY_SOURCE_CONFIG);
  }

  async fetchList(page: number): Promise<RawItem[]> {
    // HTML 파싱 로직 구현
    return [];
  }

  async fetchDetail(item: RawItem): Promise<RawItem> {
    // 상세 페이지 파싱 로직 구현
    return item;
  }
}

2. 파이프라인 실행

import { executePipeline } from './15-crawler-patterns/pipeline/run-pipeline';

const result = await executePipeline({
  sourceId: 'my-source',
  crawlOptions: { maxPages: 3, fetchDetails: true },
  sourceFactory: (id) => new MySource(),
  writeFn: async (items) => {
    // DB 저장 로직
    return { inserted: items.length, updated: 0, skipped: 0, errors: [] };
  },
  dryRun: false,
});

console.log(`수집: ${result.totalFound}, 저장: ${result.inserted}`);

3. CLI 실행

import { runCli } from './15-crawler-patterns/cli';

runCli({
  sourceConfigs: { 'my-source': MY_SOURCE_CONFIG },
  implementedSources: ['my-source'],
  sourceFactory: (id) => new MySource(),
  writeFn: myWriteFn,
  projectName: '내 프로젝트 크롤러',
});

4. 텍스트 파서 단독 사용

import { parseKoreanDate, parsePrizeAmount } from './15-crawler-patterns/pipeline/korean-text';
import { parseEnglishDate, parseGlobalPrizeAmount } from './15-crawler-patterns/pipeline/global-text';

parseKoreanDate('2026년 4월 15일');  // Date
parsePrizeAmount('대상 1,000만원');   // 10000000
parseEnglishDate('March 15, 2026');   // Date
parseGlobalPrizeAmount('$50,000');    // { currency: 'USD', amount: 50000 }

커스터마이즈 포인트