프로젝트 개요

관련 소스 파일

이 페이지의 내용은 다음 소스 파일을 기반으로 생성되었습니다:

• README.md
• README-EN.md
• main.go
• wails.json
• go.mod
• frontend/src/main.ts
• frontend/src/router/index.ts
• frontend/src/stores/index.ts
• frontend/package.json
• frontend/wailsjs/runtime/package.json

res-downloader는 Go 언어와 Wails 프레임워크를 기반으로 구축된 크로스 플랫폼 리소스 다운로더이다. 이 프로젝트는 로컬 프록시를 통해 네트워크 트래픽을 캡처하고, 다양한 플랫폼에서 비디오, 오디오, 이미지, m3u8, 라이브 스트림 등의 리소스를 필터링하여 다운로드할 수 있도록 설계되었다. Fiddler나 Charles와 유사한 원리로 동작하지만, 일반 사용자도 쉽게 사용할 수 있도록 직관적인 UI와 향상된 필터링 기능을 제공한다 (README-EN.md:1-104).

이 애플리케이션은 Windows, macOS, Linux를 지원하며, 위챗 채널, 미니 프로그램, Douyin, Kuaishou, Xiaohongshu, KuGou Music, QQ Music 등 다양한 플랫폼과 호환된다. 사용자는 프록시를 시작한 후 대상 콘텐츠를 열면, 애플리케이션이 자동으로 리소스를 감지하여 목록으로 표시한다 (README.md:1-32).

핵심 모듈

Go 백엔드 진입점 모듈

职责边界: Go 백엔드 진입점은 Wails 애플리케이션의 초기화, 윈도우 설정, 메뉴 구성, 에셋 서버 설정을 담당한다. 비즈니스 로직이나 데이터 처리는 core 패키지에 위임한다.

入口与关键 API: main 함수가 애플리케이션의 진입점이며, core.GetApp()과 core.NewBind()를 통해 앱 인스턴스와 바인딩 객체를 생성한다 (main.go:29-32).

go
1func main() {
2    app := core.GetApp(assets, wailsJson)
3    bind := core.NewBind()
4    isMac := runtime.GOOS == "darwin"
5    // ...
6}

关键数据结构: options.App 구조체는 윈도우 크기(1280x800), 최소 크기(960x600), 프레임리스 모드, 배경색 등의 UI 설정을 포함한다. macOS에서만 시스템 메뉴를 활성화하는 플랫폼별 분기 처리가 존재한다 (main.go:43-56).

关键调用链:

1. main() → core.GetApp() → 앱 메타데이터 로드
2. wails.Run() → 에셋 서버 및 미들웨어 초기화
3. OnStartup 콜백 → app.Startup(ctx) 호출

错误处理与边界条件: Wails 런타임 에러는 err := wails.Run()의 반환값으로 처리되며, macOS 여부에 따라 프레임리스 모드(!isMac)가 결정된다 (main.go:49).

Vue 프론트엔드 진입점 모듈

职责边界: Vue 애플리케이션의 부트스트랩을 담당하며, 라우터, 상태 관리, i18n을 통합한다. UI 컴포넌트 렌더링은 App.vue와 하위 컴포넌트에 위임한다.

入口与关键 API: createApp(App)이 Vue 인스턴스를 생성하며, .use(router), .use(i18n), .use(createPinia()) 체인으로 플러그인을 등록한다 (frontend/src/main.ts:10-14).

typescript
1createApp(App)
2    .use(router)
3    .use(i18n)
4    .use(createPinia())
5    .mount('#app')

关键数据结构: Pinia 스토어는 appType.App과 appType.Config 타입의 반응형 상태를 관리한다. globalConfig는 프록시 설정(Host, Port), 테마, 로케일, 다운로드 디렉토리 등을 포함한다 (frontend/src/stores/index.ts:17-36).

关键调用链:

1. createApp() → Vue 인스턴스 생성
2. .use(createPinia()) → 상태 관리 초기화
3. .mount('#app') → DOM 마운트

错误处理与边界条件: Wails 런타임 환경은 Environment 함수를 통해 확인하며, Go 백엔드와의 통신은 bind 모듈을 통해 수행된다 (frontend/src/stores/index.ts:5-7).

라우팅 모듈

职责边界: SPA(Single Page Application)의 네비게이션을 관리하며, 해시 기반 라우팅을 사용한다. 페이지 컴포넌트의 지연 로딩을 통해 초기 번들 크기를 최적화한다.

入口与关键 API: createRouter()와 createWebHashHistory()를 사용하여 라우터 인스턴스를 생성한다 (frontend/src/router/index.ts:26-29).

关键数据结构: routes 배열은 계층적 라우트 구조를 정의한다. 루트 경로 /는 layout 컴포넌트로 리다이렉트되며, /index와 /setting이 하위 라우트로 존재한다 (frontend/src/router/index.ts:3-24).

typescript
1const routes = [
2  {
3    path: "/",
4    name: "layout",
5    component: () => import("@/components/layout/Index.vue"),
6    redirect: "/index",
7    children: [
8      { path: "/index", name: "index", meta: {keepAlive: true}, ... },
9      { path: "/setting", name: "setting", meta: {keepAlive: false}, ... }
10    ]
11  }
12]

关键调用链:

1. URL 변경 감지 → 라우트 매칭
2. keepAlive 메타 확인 → 컴포넌트 캐싱 여부 결정
3. 지연 import → 컴포넌트 로드

错误处理与边界条件: keepAlive: true 설정은 인덱스 페이지의 상태를 유지하며, 설정 페이지는 keepAlive: false로 매번 새로 로드된다 (frontend/src/router/index.ts:13-20).

상태 관리 모듈

职责边界: 애플리케이션 전역 상태를 중앙 집중식으로 관리한다. 앱 정보, 글로벌 설정, MIME 타입 매핑 등의 상태를 제공한다.

入口与关键 API: defineStore("index-store", ...)로 Pinia 스토어를 정의하며, Composition API 스타일의 팩토리 함수를 사용한다 (frontend/src/stores/index.ts:9).

关键数据结构:

• appInfo: AppName, Version, Description, Copyright 포함
• globalConfig: Host(0.0.0.0), Port(8899), Theme, Locale, SaveDirectory, UpstreamProxy, TaskNumber(8), DownNumber(3) 등 (frontend/src/stores/index.ts:10-36)

关键调用链:

1. 컴포넌트 → useIndexStore() 호출
2. 스토어 인스턴스 → appApi를 통해 Go 백엔드와 통신
3. globalConfig 변경 → 반응형 UI 업데이트

错误处理与边界条件: MimeMap은 동적 MIME 타입 매핑을 지원하며, InsertTail 플래그는 다운로드 시 데이터 끝에 추가 데이터를 삽입할지 여부를 제어한다 (frontend/src/stores/index.ts:35).

기술 스택 및 아키텍처

백엔드 기술 스택

Go 백엔드는 다음과 같은 핵심 의존성을 사용한다:

(go.mod:1-42)

goproxy 라이브러리는 로컬 프록시 서버(기본 포트 8899)를 구현하는 데 사용되며, 이를 통해 네트워크 트래픽을 가로채고 리소스 URL을 추출한다. zerolog는 JSON 형식의 구조화된 로그를 출력하여 디버깅과 모니터링을 지원한다.

프론트엔드 기술 스택

Vue 3 기반 프론트엔드는 다음 의존성을 사용한다:

(frontend/package.json:11-21)

naive-ui는 Vue 3용 고품질 컴포넌트 라이브러리로, 깔끔한 UI를 제공한다. video.js와 flv.js는 캡처된 비디오 리소스의 미리보기 기능을 지원한다.

Wails 프레임워크 구성

Wails는 Go 백엔드와 웹 프론트엔드를 통합하여 네이티브 데스크톱 애플리케이션을 생성한다. wails.json 설정 파일은 다음과 같다:

json
1{
2  "name": "res-downloader",
3  "outputfilename": "res-downloader",
4  "frontend:install": "npm install",
5  "frontend:build": "npm run build",
6  "frontend:dev:watcher": "npm run dev",
7  "frontend:dev:serverUrl": "auto",
8  "info": {
9    "productVersion": "3.1.3",
10    "copyright": "Copyright © 2023"
11  }
12}

(wails.json:1-20)

이 구성은 프론트엔드 빌드 파이프라인과 개발 서버 URL을 자동으로 관리한다. productVersion: 3.1.3은 현재 버전을 나타낸다.

시스템 아키텍처

正在加载图表渲染器...

아키텍처 설명:

1. 프론트엔드 레이어: Vue 3 애플리케이션이 라우터, 상태 관리, UI 컴포넌트를 통합하여 사용자 인터페이스를 구성한다. Pinia 스토어는 Go 바인딩을 통해 백엔드와 통신한다 (frontend/src/main.ts:10-14).

2. Wails 런타임: Go 바인딩이 백엔드 함수를 프론트엔드에 노출하며, @wailsapp/runtime은 이벤트 기반 통신을 제공한다. 에셋 서버는 정적 리소스를 제공한다 (frontend/wailsjs/runtime/package.json:1-24).

3. 백엔드 레이어: main.go가 애플리케이션을 초기화하고, core 패키지가 비즈니스 로직을 처리한다. goproxy 서버가 트래픽을 캡처하고, zerolog가 로깅을 담당한다 (main.go:28-67).

핵심 데이터 흐름

正在加载图表渲染器...

데이터 흐름 설명:

1. 프록시 시작: 사용자가 "프록시 시작" 버튼을 클릭하면, Pinia 스토어의 OpenProxy 상태가 true로 설정된다. 이 변경은 Go 바인딩을 통해 goproxy 서버를 시작한다 (frontend/src/stores/index.ts:27).

2. 트래픽 캡처: 사용자가 대상 플랫폼(위챗, 브라우저 등)에서 콘텐츠에 접근하면, 모든 HTTP 트래픽이 로컬 프록시(127.0.0.1:8899)를 통해 라우팅된다. goproxy 서버는 요청을 가로채고 리소스 URL을 필터링한다 (README-EN.md:95-96).

3. 리소스 표시: 캡처된 리소스 목록은 Go 바인딩을 통해 프론트엔드로 전달되며, Pinia 스토어가 이를 저장한다. Vue 앱은 반응형으로 UI를 업데이트하여 사용자에게 리소스 목록을 표시한다.

주요 기능 및 특징

(README.md:21-28)

디렉토리 구조

res-downloader/
├── main.go                 # Go 진입점
├── go.mod                  # Go 의존성
├── wails.json              # Wails 설정
├── frontend/
│   ├── src/
│   │   ├── main.ts         # Vue 진입점
│   │   ├── router/
│   │   │   └── index.ts    # 라우팅 구성
│   │   ├── stores/
│   │   │   └── index.ts    # Pinia 스토어
│   │   └── views/          # 페이지 컴포넌트
│   ├── package.json        # npm 의존성
│   └── wailsjs/
│       └── runtime/        # Wails 런타임
└── build/                  # 빌드 에셋

적용 시나리오

1. 소셜 미디어 리소스 다운로드: 위챗 채널, Douyin, Kuaishou 등에서 비디오와 이미지를 다운로드한다.
2. 음악 스트리밍 캡처: KuGou Music, QQ Music 등에서 오디오 리소스를 추출한다.
3. m3u8 비디오 처리: m3u8 플레이리스트를 감지하고 외부 도구와 연동하여 다운로드한다.
4. 라이브 스트림 녹화: 라이브 스트림 URL을 캡처하여 OBS 등의 도구로 녹화한다.
5. 제한된 네트워크 환경: 업스트림 프록시를 통해 네트워크 제한을 우회한다.

보고서 로드맵

正在加载图表渲染器...

추천 읽기 순서:

1. 프로젝트 개요 (현재): 전체 시스템 구조와 핵심 모듈 이해
2. 아키텍처 분석: Go 백엔드와 Vue 프론트엔드의 상세 구조
3. 데이터 흐름: 프록시 캡처부터 다운로드까지의 전체 프로세스
4. API 설계: Go 바인딩과 프론트엔드 간의 인터페이스 명세
5. 의존성 그래프: 외부 라이브러리와의 의존 관계
6. 데이터 모델: 상태 관리와 설정 구조의 상세 분석

정량적 지표