Tổng quan dự án

Tệp nguồn liên quan

Trang này được tạo dựa trên các tệp nguồn sau:

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

res-downloader là một công cụ tải tài nguyên đa nền tảng được xây dựng dựa trên ngôn ngữ Go và framework Wails v2. Ứng dụng cho phép sniffing và tải nhiều loại tài nguyên khác nhau bao gồm video, audio, hình ảnh, m3u8 và live stream thông qua cơ chế proxy cục bộ. Với giao diện người dùng trực quan được xây dựng bằng Vue.js 3, công cụ hỗ trợ nhiều nền tảng phổ biến như WeChat Channels, Mini Programs, Douyin, Kuaishou, Xiaohongshu, KuGou Music và QQ Music (README.md:1-32, README-EN.md:1-104).

Giới thiệu dự án

Dự án res-downloader được thiết kế để giải quyết nhu cầu tải xuống các tài nguyên đa phương tiện từ nhiều nền tảng trực tuyến khác nhau. Nguyên lý hoạt động của công cụ dựa trên việc bắt giữ lưu lượng mạng thông qua proxy cục bộ và lọc các tài nguyên hữu ích. Cơ chế này tương tự như các công cụ như Fiddler, Charles hoặc browser DevTools, nhưng với giao diện thân thiện hơn và khả năng lọc nâng cao, phù hợp cho người dùng phổ thông không có kiến thức kỹ thuật sâu (README-EN.md:1-104).

Mục đích và giá trị cốt lõi

Công cụ cung cấp giải pháp toàn diện cho việc tải tài nguyên với các đặc điểm chính:

• Đa dạng loại tài nguyên: Hỗ trợ video, audio, hình ảnh, m3u8, live stream
• Tương thích nền tảng rộng: WeChat, Douyin, Kuaishou, Xiaohongshu, KuGou, QQ Music
• Giao diện trực quan: UI sạch đẹp, dễ sử dụng với theme sáng/tối
• Cơ chế proxy linh hoạt: Hỗ trợ proxy cục bộ và upstream proxy cho các mạng bị hạn chế

Phiên bản hiện tại của sản phẩm là 3.1.3, được phát hành dưới dạng ứng dụng desktop hỗ trợ Windows, macOS và Linux (wails.json:1-20).

Thông tin phiên bản và cấu hình

Thông tin sản phẩm

Cấu hình build được định nghĩa trong wails.json:1-20, bao gồm các chỉ thị cho frontend install, build và development server. Module Go sử dụng toolchain go1.23.2 với các dependencies chính được khai báo trong go.mod:1-42.

Dependencies chính

Các dependencies gián tiếp quan trọng bao gồm Echo v4 framework cho HTTP server, go-ole cho Windows integration, và go-webview2 cho WebView renderer trên Windows (go.mod:1-42).

Kiến trúc kỹ thuật

Tổng quan kiến trúc hệ thống

Hệ thống được xây dựng theo mô hình hybrid với backend Go xử lý logic nghiệp vụ và proxy, frontend Vue.js quản lý giao diện người dùng. Wails framework đóng vai trò cầu nối (bridge) giữa hai tầng, cung cấp cơ chế IPC (Inter-Process Communication) thông qua binding và runtime API.

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

Giải thích kiến trúc:

1. Frontend Layer: Xử lý rendering UI và state management, giao tiếp với backend thông qua WailsJS bridge
2. Wails Bridge Layer: Cung cấp runtime API và Go bindings cho hai chiều communication
3. Backend Layer: Chứa logic nghiệp vụ chính bao gồm proxy server và resource processing
4. External Resources: Lưu lượng mạng được intercept và tài nguyên được download

Điểm khởi tạo ứng dụng:

File main.go:28-67 đóng vai trò entry point, thực hiện:

• Khởi tạo app instance thông qua core.GetApp()
• Tạo binding object với core.NewBind()
• Cấu hình window options (1280x800 default, frameless trên non-macOS)
• Thiết lập AssetServer với middleware tùy chỉnh
• Đăng ký OnStartup callback để khởi chạy app context

Stack công nghệ chi tiết

Frontend entry point tại frontend/src/main.ts:1-14 khởi tạo Vue app với router, i18n và Pinia store, sau đó mount vào DOM element #app.

Cấu trúc giao diện và trạng thái

Hệ thống Routing

Ứng dụng sử dụng Vue Router với hash-based history mode, định nghĩa hai view chính:

Cấu trúc routing được wrap trong layout component tại @/components/layout/Index.vue với redirect mặc định về /index (frontend/src/router/index.ts:1-31).

State Management với Pinia

Store chính useIndexStore quản lý hai state quan trọng:

appInfo - Thông tin ứng dụng:

• AppName: Tên ứng dụng
• Version: Phiên bản hiện tại
• Description: Mô tả
• Copyright: Thông tin bản quyền

globalConfig - Cấu hình toàn cục (frontend/src/stores/index.ts:1-36):

Store import Environment từ Wails runtime và bind từ Go bindings để đồng bộ state với backend (frontend/src/stores/index.ts:1-36).

Tích hợp Runtime Wails

Kiến trúc Runtime API

Wails runtime cung cấp bộ API phong phú cho frontend tương tác với hệ thống native. File frontend/wailsjs/runtime/runtime.js:26-202 expose các function wrapper gọi đến window.runtime object.

Logging API:

javascript
1export function LogWarning(message) {
2    window.runtime.LogWarning(message);
3}
4
5export function LogError(message) {
6    window.runtime.LogError(message);
7}
8
9export function LogFatal(message) {
10    window.runtime.LogFatal(message);
11}

Event System:

javascript
1export function EventsOnMultiple(eventName, callback, maxCallbacks) {
2    return window.runtime.EventsOnMultiple(eventName, callback, maxCallbacks);
3}
4
5export function EventsOn(eventName, callback) {
6    return EventsOnMultiple(eventName, callback, -1);
7}
8
9export function EventsOff(eventName, ...additionalEventNames) {
10    return window.runtime.EventsOff(eventName, ...additionalEventNames);
11}
12
13export function EventsEmit(eventName) {
14    let args = [eventName].slice.call(arguments);
15    return window.runtime.EventsEmit.apply(null, args);
16}

Event system cho phép communication hai chiều: backend Go có thể emit events mà frontend subscribe, và ngược lại (frontend/wailsjs/runtime/runtime.js:26-202).

Window Management API

TypeScript definitions tại frontend/wailsjs/runtime/runtime.d.ts:86-246 định nghĩa type-safe interface cho window operations:

Theme Control (Windows only):

typescript
1export function WindowSetSystemDefaultTheme(): void;
2export function WindowSetLightTheme(): void;
3export function WindowSetDarkTheme(): void;

Clipboard và Browser Integration

Runtime cung cấp API cho clipboard operations và mở URL trong browser hệ thống:

typescript
1export function ClipboardGetText(): Promise<string>;
2export function ClipboardSetText(text: string): Promise<boolean>;
3export function BrowserOpenURL(url: string): void;

Clipboard API trả về Promise, cho phép async/await pattern trong Vue components. BrowserOpenURL mở URL trong browser mặc định của hệ thống, hữu ích cho việc mở documentation hoặc external links (frontend/wailsjs/runtime/runtime.d.ts:86-246).

Luồng dữ liệu và khởi tạo ứng dụng

Chuỗi khởi tạo ứng dụng

Quá trình khởi tạo diễn ra theo sequence sau:

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

Giải thích sequence:

1. Backend Initialization: main.go:28-67 khởi tạo app instance và binding, sau đó gọi wails.Run() với các options
2. Window Creation: Wails framework tạo window với kích thước 1280x800, frameless mode trên non-macOS
3. Startup Callback: OnStartup được gọi với context, trigger app.Startup(ctx)
4. Frontend Mount: Vue app được tạo với router, i18n, Pinia và mount vào DOM
5. Runtime Integration: Frontend gọi Environment() và bind.GetAppInfo() để đồng bộ state

Cơ chế Proxy và Resource Interception

Dựa trên cấu hình trong store, proxy server được khởi tạo với các thông số:

• Host/Port: 0.0.0.0:8899 (default)
• Upstream Proxy: Tùy chọn cho mạng bị hạn chế
• MimeMap: Lọc theo MIME type của resource

Luồng xử lý proxy:

1. User bật proxy thông qua UI → OpenProxy: true trong globalConfig
2. Backend khởi động goproxy server trên port 8899
3. System proxy được cấu hình trỏ đến 127.0.0.1:8899
4. Traffic từ WeChat/Douyin/etc đi qua proxy
5. Proxy filter resources theo MimeMap và capture metadata
6. Frontend nhận events với danh sách resources mới
7. User chọn resource để download

Lưu ý quan trọng: Khi đóng ứng dụng, user cần tắt system proxy thủ công nếu không được tự động khôi phục (README-EN.md:1-104).

Cấu trúc thư mục dự án

res-downloader/
├── main.go                    # Entry point backend
├── wails.json                 # Cấu hình Wails build
├── go.mod                     # Go module definition
├── go.sum                     # Dependency checksums
├── frontend/                  # Frontend source code
│   ├── src/
│   │   ├── main.ts           # Vue app entry point
│   │   ├── App.vue           # Root component
│   │   ├── router/
│   │   │   └── index.ts      # Route definitions
│   │   ├── stores/
│   │   │   └── index.ts      # Pinia store
│   │   ├── views/
│   │   │   ├── index.vue     # Main view
│   │   │   └── setting.vue   # Settings view
│   │   ├── components/
│   │   │   └── layout/       # Layout components
│   │   ├── api/              # API service layer
│   │   ├── types/            # TypeScript types
│   │   └── assets/           # Static assets
│   └── wailsjs/
│       ├── runtime/          # Wails runtime API
│       │   ├── runtime.js    # JS implementation
│       │   └── runtime.d.ts  # TypeScript definitions
│       └── go/               # Go bindings
│           └── core/         # Core module bindings
├── build/                    # Build assets
│   └── appicon.png          # Application icon
└── docs/                     # Documentation
    └── images/
        └── show.webp        # Preview image

Tính năng cốt lõi

1. Multi-Resource Type Support

Hỗ trợ sniffing và download nhiều loại tài nguyên:

• Video: MP4, WebM, AVI
• Audio: MP3, AAC, WAV, M4A
• Images: JPG, PNG, WebP, GIF
• Streaming: M3U8 playlists, HLS streams
• Live Streams: RTMP, FLV live broadcasts

2. Cross-Platform Compatibility

Ứng dụng được build cho ba nền tảng chính:

• Windows: Windows 7+ (version 2.3.0 cho Win7)
• macOS: Intel và Apple Silicon
• Linux: Multiple distributions

3. Platform-Specific Support

Tương thích với nhiều nền tảng nội dung:

• WeChat Channels (视频号)
• WeChat Mini Programs
• Douyin (抖音)
• Kuaishou (快手)
• Xiaohongshu (小红书)
• KuGou Music (酷狗音乐)
• QQ Music (QQ音乐)

4. Proxy-Based Interception

Cơ chế proxy cục bộ cho phép:

• Intercept HTTPS traffic với certificate installation
• Filter resources theo MIME type
• Support upstream proxy cho mạng bị hạn chế
• Auto-detect resource URLs từ traffic

5. User-Friendly Interface

Giao diện được thiết kế với focus vào usability:

• Clean, modern UI với theme sáng/tối
• Real-time resource list updates
• One-click download functionality
• Batch download support
• Download progress tracking

6. Configuration Flexibility

Cấu hình linh hoạt thông qua settings:

• Custom proxy port và host binding
• Concurrent task và download limits
• Custom User-Agent headers
• Filename customization options
• Download directory selection

7. Security Features

Các tính năng bảo mật:

• Certificate pinning support
• HTTPS traffic decryption
• Secure credential handling
• Local-only proxy binding

8. Error Handling và Recovery

Xử lý lỗi và phục hồi:

• Automatic retry cho failed downloads
• Network error recovery
• Proxy connection fallback
• Graceful shutdown handling

Sơ đồ đọc báo cáo

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

Hướng dẫn đọc báo cáo:

1. Bắt đầu: Trang tổng quan này cung cấp cái nhìn tổng thể về kiến trúc và tính năng
2. Hiểu sâu: Các trang phân tích sâu đi vào chi tiết implementation của từng module
3. Thực hành: Phần vận hành hướng dẫn deployment, configuration và troubleshooting

Chỉ số định lượng dự án

Kết luận

res-downloader là một ứng dụng desktop hoàn chỉnh được xây dựng với stack công nghệ hiện đại (Go + Wails + Vue.js). Kiến trúc hybrid cho phép tận dụng performance của Go cho backend processing trong khi vẫn có giao diện người dùng responsive và hiện đại. Cơ chế proxy-based interception cung cấp giải pháp linh hoạt cho việc sniffing tài nguyên từ nhiều nền tảng khác nhau mà không cần integration riêng biệt với từng platform.

Với phiên bản 3.1.3, dự án đã đạt đến độ trưởng thành nhất định với bộ tính năng đầy đủ cho use cases phổ biến. Kiến trúc modular cho phép mở rộng dễ dàng khi cần hỗ trợ thêm nền tảng hoặc loại tài nguyên mới.