Architecture at a Glance

Source Files

This page is generated from the following source files:

• main.go
• core/app.go
• core/proxy.go
• core/bind.go
• frontend/src/main.ts
• frontend/wailsjs/go/core/Bind.js
• core/http.go
• core/downloader.go
• core/aes.go
• core/rule.go
• frontend/src/router/index.ts
• frontend/src/stores/index.ts
• go.mod
• frontend/package.json
• frontend/wailsjs/runtime/package.json
• core/utils.go
• core/config.go
• core/logger.go
• core/system.go
• core/storage.go

This document provides a comprehensive architectural analysis of the res-downloader project, a cross-platform desktop application designed for network resource sniffing and high-speed downloading. The application combines a Go-based backend with a Vue 3 frontend, leveraging the Wails framework to deliver native performance across Windows, macOS, and Linux.

Technology Stack Framework

The project adopts a modern hybrid architecture that bridges native Go performance with contemporary web development practices.

The main entry point (main.go:1-101) demonstrates the Wails application initialization with platform-specific configurations. The Go module dependencies (go.mod:1-42) confirm the use of goproxy for traffic interception and zerolog for structured logging.

The frontend entry point (frontend/src/main.ts:1-14) shows the Vue 3 application setup with Pinia state management and i18n internationalization support.

Core Application Architecture

The backend architecture follows a singleton-based service registry pattern, where core services are initialized once and accessed globally throughout the application lifecycle.

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

App Service (Lifecycle Controller)

The App struct serves as the central orchestrator, managing application lifecycle events and maintaining global state. Key responsibilities include:

• Initialization: Parses version information from embedded wails.json and initializes all singleton services (core/app.go:42-172)
• Startup Hook: Launches the HTTP server in a goroutine when the Wails context becomes available
• Shutdown Hook: Cleans up system proxy settings, closes loggers, and optionally resets application state
• Proxy Management: Provides OpenSystemProxy() and UnsetSystemProxy() methods for traffic interception control

The singleton pattern ensures only one App instance exists throughout the application lifetime, with thread-safe initialization via sync.Once.

Configuration Service

The Config struct manages all user-configurable settings with automatic persistence to disk. Default values are established at initialization (core/config.go:46-221):

go
1defaultConfig := &Config{
2    Theme:         "lightTheme",
3    Locale:        "zh",
4    Host:          "127.0.0.1",
5    Port:          "8899",
6    TaskNumber:    runtime.NumCPU() * 2,
7    DownNumber:    3,
8    UserAgent:     "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
9    Rule:          "*",
10}

The configuration service delegates file operations to the Storage abstraction, enabling transparent persistence without coupling to filesystem details.

Logger Service

Structured logging is provided through a custom Logger wrapper around zerolog (core/logger.go:1-68). The logger supports:

• Dual Output: Console output during development, file output in production
• Structured Fields: Stack traces on errors via .Stack().Err(err)
• Automatic Rotation: Log files stored in {UserDir}/logs/app.log

Network Layer Proxy System

The network layer is the most architecturally significant component, implementing a dual-purpose HTTP server that handles both API requests and proxy traffic.

HTTP Server Architecture

The HttpServer (core/http.go:21-408) listens on a configurable host/port combination and routes incoming requests based on the Host header:

go
1http.Serve(listener, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
2    if r.Host == "127.0.0.1:"+globalConfig.Port && HandleApi(w, r) {
3        // API request handled
4    } else {
5        proxyOnce.Proxy.ServeHTTP(w, r) // Proxy request
6    }
7}))

This design allows a single port to serve both the frontend API and proxy traffic, simplifying deployment and reducing port conflicts.

Plugin-Based Proxy Interception

The proxy system uses a plugin registry pattern to enable extensible request/response modification. Each domain can register a custom plugin implementing the shared.Plugin interface:

go
1func (p *Proxy) httpRequestEvent(r *http.Request, ctx *goproxy.ProxyCtx) (*http.Request, *http.Response) {
2    plugin := p.matchPlugin(r.Host)
3    if plugin != nil {
4        newReq, newResp := plugin.OnRequest(r, ctx)
5        if newResp != nil {
6            return newReq, newResp
7        }
8        if newReq != nil {
9            return newReq, nil
10        }
11    }
12    return pluginRegistry["default"].OnRequest(r, ctx)
13}

The plugin matching logic (core/proxy.go:135-173) extracts the top-level domain and looks up registered handlers, falling back to a default handler for unmatched domains.

Rule-Based MITM Filtering

Not all traffic should be intercepted and decrypted. The RuleSet engine (core/rule.go:22-126) provides flexible filtering through a custom rule syntax:

The rule evaluation logic processes rules in order, with later rules potentially overriding earlier ones:

go
1func (r *RuleSet) shouldMitm(host string) bool {
2    action := false
3    for _, rule := range r.rules {
4        if rule.isAll {
5            action = !rule.isNeg
6            continue
7        }
8        if rule.isWildcard {
9            if h == rule.domain || strings.HasSuffix(h, "."+rule.domain) {
10                action = !rule.isNeg
11            }
12            continue
13        }
14        if h == rule.domain {
15            action = !rule.isNeg
16        }
17    }
18    return action
19}

Frontend-Backend Communication

The communication between Vue frontend and Go backend follows a type-safe binding pattern enforced by Wails code generation.

Go Binding Layer

The Bind struct (core/bind.go:9-25) exposes methods that the frontend can invoke:

go
1func (b *Bind) Config() *ResponseData {
2    return httpServerOnce.buildResp(1, "ok", globalConfig)
3}
4
5func (b *Bind) AppInfo() *ResponseData {
6    return httpServerOnce.buildResp(1, "ok", appOnce)
7}
8
9func (b *Bind) ResetApp() {
10    appOnce.IsReset = true
11    runtime.Quit(appOnce.ctx)
12}

These methods are automatically wrapped by Wails and exposed to JavaScript through generated bindings (frontend/wailsjs/go/core/Bind.js:1-15):

javascript
1export function AppInfo() {
2  return window['go']['core']['Bind']['AppInfo']();
3}
4
5export function Config() {
6  return window['go']['core']['Bind']['Config']();
7}

Pinia State Management

The frontend uses Pinia for centralized state management (frontend/src/stores/index.ts:1-99). The useIndexStore manages:

• App Info: Application metadata (name, version, description)
• Global Config: User settings synchronized with backend
• Proxy State: Current system proxy status
• Environment Info: Build type, platform, architecture

The initialization flow demonstrates the async coordination between Wails bindings and Pinia:

typescript
1const init = async () => {
2    Environment().then((res) => {
3        envInfo.value = res
4    })
5
6    await bind.AppInfo().then((res: core.ResponseData)=>{
7        appInfo.value = Object.assign({}, appInfo.value, res.data)
8        isProxy.value = res.data.IsProxy
9    })
10
11    await bind.Config().then((res: core.ResponseData)=>{
12        globalConfig.value = Object.assign({}, globalConfig.value, res.data)
13    })
14
15    baseUrl.value = "http://127.0.0.1:" + globalConfig.value.Port
16}

Vue Router Configuration

The SPA navigation is handled by Vue Router with lazy-loaded components (frontend/src/router/index.ts:1-31):

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

The hash-based history mode (createWebHashHistory()) is essential for local file serving, as it doesn't require server-side URL rewriting.

Data Flow Critical Call Chains

The following sequence diagram illustrates the end-to-end flow from application startup through a proxied network request:

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

Key Data Flow Points

1. Startup Sequence: The Wails runtime calls main() which creates the App singleton, triggering a cascade of service initializations (Config → Logger → System → HttpServer → Proxy → RuleSet)

2. Request Routing: Every incoming HTTP request is inspected for its Host header. Requests to 127.0.0.1:{Port} are treated as API calls; all others are proxied

3. MITM Decision: The rule engine evaluates the target domain against configured patterns to determine whether HTTPS decryption should be attempted

4. Plugin Interception: If a domain-specific plugin exists, it can modify both requests and responses, enabling custom resource extraction logic

Supporting Services

AES Encryption for Credential Storage

The AESCipher (core/aes.go:16-72) provides AES-CBC encryption for sensitive data like cached passwords:

go
1func (a *AESCipher) Encrypt(plainText string) (string, error) {
2    block, err := aes.NewCipher(a.key)
3    // ... PKCS7 padding
4    iv := cipherText[:aes.BlockSize]
5    mode := cipher.NewCBCEncrypter(block, iv)
6    mode.CryptBlocks(cipherText[aes.BlockSize:], []byte(plainText))
7    return base64.StdEncoding.EncodeToString(cipherText), nil
8}

The decryption routine validates padding to prevent oracle attacks:

go
1padding := int(cipherTextBytes[len(cipherTextBytes)-1])
2if padding > len(cipherTextBytes) || padding > aes.BlockSize {
3    return "", errors.New("padding size error")
4}

File-Based Storage Abstraction

The Storage struct (core/storage.go:1-41) provides a simple abstraction for file persistence:

go
1func (l *Storage) Load() ([]byte, error) {
2    if !shared.FileExist(l.fileName) {
3        err := os.WriteFile(l.fileName, l.def, 0644)
4        return l.def, nil
5    }
6    return os.ReadFile(l.fileName)
7}

This pattern is used by Config for settings persistence and by SystemSetup for credential caching.

Multi-Part Downloader

The FileDownloader supports parallel downloads through range requests (core/downloader.go:200-239):

go
1func (fd *FileDownloader) createDownloadTasks() {
2    if fd.IsMultiPart {
3        eachSize := fd.TotalSize / int64(fd.totalTasks)
4        if eachSize < MinPartSize {
5            fd.totalTasks = int(fd.TotalSize / MinPartSize)
6            // ... adjust task count
7        }
8        for i := 0; i < fd.totalTasks; i++ {
9            start := eachSize * int64(i)
10            end := eachSize*int64(i+1) - 1
11            if i == fd.totalTasks-1 {
12                end = fd.TotalSize - 1
13            }
14            fd.DownloadTaskList = append(fd.DownloadTaskList, &DownloadTask{
15                taskID:     i,
16                rangeStart: start,
17                rangeEnd:   end,
18            })
19        }
20    }
21}

The downloader automatically adjusts the number of parallel tasks based on file size, ensuring each part is at least MinPartSize bytes.

System Setup & Certificate Management

The SystemSetup service (core/system.go:16-83) handles:

• Certificate Initialization: Extracts embedded CA certificate to disk for system installation
• Password Caching: Encrypts and stores credentials with a 1-month expiration
• Proxy Configuration: Platform-specific system proxy settings (Windows/macOS/Linux)

go
1func (s *SystemSetup) checkPasswordFile() {
2    fileInfo, err := os.Stat(s.CacheFile)
3    lastModified := fileInfo.ModTime()
4    oneMonthAgo := time.Now().AddDate(0, -1, 0)
5    if lastModified.Before(oneMonthAgo) {
6        os.Remove(s.CacheFile)  // Expired cache
7        return
8    }
9    // ... decrypt and load password
10}

Module Dependency Graph

The following diagram illustrates the dependency relationships between core modules:

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

Dependency Analysis

• Entry Point: main.go depends only on core/app, maintaining clean separation
• Core Services: App, Config, Logger, System, Http, Proxy, Rule, Bind form the application core
• Supporting Services: Storage, AES, Downloader, Utils provide infrastructure
• Shared Utilities: core/shared package provides cross-cutting utilities used by multiple modules

The dependency graph shows a well-structured layered architecture with no circular dependencies.

Key Design Decisions Trade-offs

Known Limitations

1. Certificate Trust: Users must manually trust the self-signed CA certificate for HTTPS interception
2. Platform-Specific Proxy: System proxy configuration requires different approaches per OS
3. No Database: All data stored in flat files, limiting query capabilities
4. Single Instance: No support for multiple concurrent instances (lock file mechanism)

Configuration Startup Flow

Default Configuration Values

The application ships with sensible defaults (core/config.go:46-221):

Startup Sequence

1. Main Entry (main.go:1-101): Wails application created with platform-specific options
2. App Initialization (core/app.go:42-172): Singleton created, version parsed from embedded JSON
3. Service Chain: Config → Logger → System → HttpServer → Proxy → RuleSet
4. Context Binding: Wails context passed to App on startup
5. HTTP Server Launch: Goroutine starts listening on configured port
6. Frontend Ready: Vue app mounts, calls Bind methods to fetch initial state

Shutdown Sequence

1. Wails Shutdown: OnShutdown callback invoked
2. Proxy Cleanup: System proxy settings restored to original state
3. Logger Close: Log file handle released
4. Optional Reset: If IsReset flag set, application data is cleared