타입 정의

Result

추출 결과로, 텍스트, 메타데이터 및 미디어 정보를 포함합니다.

type Result struct {
    Text           string        `json:"text"`
    Title          string        `json:"title"`
    Images         []ImageInfo   `json:"images,omitempty"`
    Links          []LinkInfo    `json:"links,omitempty"`
    Videos         []VideoInfo   `json:"videos,omitempty"`
    Audios         []AudioInfo   `json:"audios,omitempty"`
    ProcessingTime time.Duration `json:"-"`       // 처리 소요 시간 (표준 직렬화에서 제외)
    WordCount      int           `json:"word_count"`
    ReadingTime    time.Duration `json:"-"`       // 예상 읽기 시간 (표준 직렬화에서 제외)
}

MarshalJSON

커스텀 JSON 직렬화. ProcessingTime과 ReadingTime은 json:"-" 태그가 있어 표준 직렬화에서는 건너뛰지만, 커스텀 MarshalJSON() 메서드를 통해 밀리초 단위로 출력에 포함됩니다.

func (r *Result) MarshalJSON() ([]byte, error)

경고

Result는 UnmarshalJSON을 구현하지 않습니다. MarshalJSON()의 출력을 다시 Result로 역직렬화하면 ProcessingTime, ReadingTime 같은 duration 필드가 손실됩니다 — JSON 출력의 키 이름 (processing_time_ms, reading_time_ms) 이 struct 필드 이름과 일치하지 않아 복원할 수 없습니다.

이는 의도된 설계입니다. 이 JSON 형식은 외부 소비 (API 응답, 로그, 프론트엔드 표시 등) 를 위한 것이며, 양방향 직렬화를 위해 설계되지 않았습니다.

ImageInfo

이미지 정보입니다.

type ImageInfo struct {
    URL          string `json:"url"`           // 이미지 주소
    Alt          string `json:"alt"`           // 대체 텍스트
    Title        string `json:"title"`         // 제목
    Width        string `json:"width"`         // 너비
    Height       string `json:"height"`        // 높이
    IsDecorative bool   `json:"is_decorative"` // 장식용 이미지 여부
    Position     int    `json:"position"`      // 문서 내 위치
}

필드 의미

필드	설명
`URL`	이미지의 `src` 속성값; 유효한 URL 만 포함(`IsValidURL`로 검증), 유효하지 않은 URL 의 `<img>`는 결과에 나타나지 않음
`Alt`	`alt` 속성 원문; 비어 있으면 `IsDecorative`가 `true`
`Title`	`title` 속성 원문(페이지 제목이 아님)
`Width`/`Height`	HTML 속성의 원본 문자열(예: `"640"`, `"50%"`), 숫자로 파싱되지 않음 — 페이지마다 표기가 다를 수 있음
`IsDecorative`	`Alt`가 비어 있으면 `true`, 장식용 이미지 식별 및 건너뛰기에 사용
`Position`	문서 내 1-based 순번; `PreserveImages = false`일 때 `Images` 슬라이스 전체가 비어 있음

Width/Height 는 숫자 타입이 아님

Width와 Height는 int가 아닌 string 타입이며, HTML 소스의 원본 표현을 보존합니다(단위, 백분율 등 포함 가능). 숫자가 필요할 때는 호출자가 직접 파싱해야 합니다.

LinkInfo

링크 정보입니다.

type LinkInfo struct {
    URL        string `json:"url"`         // 링크 주소
    Text       string `json:"text"`        // 링크 텍스트
    Title      string `json:"title"`       // 링크 제목
    IsExternal bool   `json:"is_external"` // 외부 링크 여부 (URL 자체가 절대 외부 URL 인지로 판정하며, BaseURL 과 비교하지 않음)
    IsNoFollow bool   `json:"is_nofollow"` // nofollow 여부
    Position   int    `json:"position"`    // 문서 내 위치
}

필드 의미

필드	설명
`URL`	`href` 속성값; 유효한 URL 만 포함(`IsValidURL`로 검증), 유효하지 않은 URL 의 `<a>`는 Position 을 소비하지만 슬라이스에 추가되지 않음
`Text`	`<a>` 태그 내 모든 텍스트 노드의 연결(재귀적 `GetTextContent`)
`Title`	`title` 속성 원문(링크 텍스트가 아님)
`IsExternal`	URL 자체가 절대 외부 주소인지로 판정, `BaseURL`과의 도메인 비교를 하지 않음 — 이는 `ExtractAllLinks`의 내/외부 링크 판정과 다름
`IsNoFollow`	`rel` 속성에 `nofollow` 포함 시(대소문자 구분 없음, ASCII 폴딩 매칭) `true`
`Position`	문서 내 1-based 순번; 유효하지 않은 `<a>`(href 가 유효하지 않거나 누락)도 순번을 소비하지만 슬라이스에 추가되지 않으므로 Position 이 불연속일 수 있음

VideoInfo

비디오 정보입니다.

type VideoInfo struct {
    URL      string `json:"url"`      // 비디오 주소
    Type     string `json:"type"`     // 비디오 유형
    Poster   string `json:"poster"`   // 썸네일 주소
    Width    string `json:"width"`    // 너비
    Height   string `json:"height"`   // 높이
    Duration string `json:"duration"` // 재생 시간
}

Type 필드값 규칙

Type 값	의미	발생 시나리오
`"embed"`	iframe 이 참조하는 비디오 페이지	YouTube, Vimeo, Youku, Bilibili 등 임베드 플레이어
MIME 타입(예: `"video/mp4"`)	비디오 파일 컨테이너	`<source type="video/mp4">` 속성값
빈 문자열	유형 미감지	`<video src="...">`로 직접 소스 지정, `<source>` 자식 요소 없음

비디오 추출의 세 출처

비디오 추출은 원본 HTML 스캔 → DOM 순회 → 정규식 폴백 순으로 실행되며, 각 단계에서 중복 제거. 자세한 내용은 미디어 추출 가이드를 참조하세요.

AudioInfo

오디오 정보입니다.

type AudioInfo struct {
    URL      string `json:"url"`      // 오디오 주소
    Type     string `json:"type"`     // 오디오 유형
    Duration string `json:"duration"` // 재생 시간
}

Type 필드값 규칙

Type 값	발생 시나리오
MIME 타입(예: `"audio/mpeg"`)	`<source type="audio/mpeg">` 속성값
빈 문자열	`<audio src="...">`로 직접 소스 지정, `<source>` 자식 요소 없음

.ogg 확장자의 이중성

OGG 컨테이너는 비디오 또는 오디오를 담을 수 있으며, .ogg URL은 Videos와 Audios에 모두 나타납니다. 오디오 전용 변형인 .oga는 Audios에만 나타납니다.

LinkResource

링크 리소스 (링크 추출 API 에 사용).

type LinkResource struct {
    URL   string // 링크 주소
    Title string // 링크 제목
    Type  string // 링크 유형
}

Statistics

처리 통계 정보입니다.

type Statistics struct {
    TotalProcessed    int64         // 총 처리 수
    CacheHits         int64         // 캐시 적중 수
    CacheMisses       int64         // 캐시 미스 수
    ErrorCount        int64         // 오류 수
    AverageProcessTime time.Duration // 평균 처리 시간
}

BatchResult

배치 처리 결과입니다.

type BatchResult struct {
    Results   []*Result // 추출 결과, 실패 또는 취소 시 nil
    Errors    []error   // 실패한 오류
    Success   int       // 성공 수량
    Failed    int       // 실패 수량
    Cancelled int       // 취소 수량
}

NodeAttr

HTML 노드 속성입니다.

type NodeAttr struct {
    Key   string // 속성명
    Value string // 속성값
}

타입 정의 ​

Result ​

MarshalJSON ​

ImageInfo ​

필드 의미 ​

LinkInfo ​

필드 의미 ​

VideoInfo ​

Type 필드값 규칙 ​

AudioInfo ​

Type 필드값 규칙 ​

LinkResource ​

Statistics ​

BatchResult ​

NodeAttr ​

타입 정의

Result

MarshalJSON

ImageInfo

필드 의미

LinkInfo

필드 의미

VideoInfo

Type 필드값 규칙

AudioInfo

Type 필드값 규칙

LinkResource

Statistics

BatchResult

NodeAttr