QtMultiThreadNetwork

English

A high-performance, thread-safe C++ library that provides multi-threaded HTTP(S)/FTP networking capabilities built on top of Qt's Network module.

Features

🚀 Core Capabilities

Multi-threaded Architecture: Each request executes in separate threads using a managed thread pool
Concurrent Operations: Support for both single and batch request modes
Multi-threaded Downloads: Large file downloads with multiple channels for faster performance (auto-detects CPU cores when threadCount=0)
Protocol Support: HTTP(S)/FTP with full request method support (GET/POST/PUT/DELETE/HEAD/PATCH/OPTIONS)
Asynchronous API: Non-blocking operations with signal/slot progress reporting
Thread Safety: All public methods are thread-safe with atomic operations

🛠️ Advanced Features

Memory-Mapped Files: Efficient file I/O for large downloads using platform-specific APIs
Batch Operations: Group multiple requests with aggregated progress tracking
Retry with Exponential Backoff: Automatic retry of transient failures (connection refused, timeout, SSL errors) via pluggable strategy
Extensible Architecture: Template Method + Strategy + State patterns enable clean extension points; self-registering factory eliminates switch-case for new request types
Proxy Support: Per-request proxy or global proxy with two-level cascade
Persistent Cookie Jar: File-backed cookie storage shared across all requests
Request Priority Queue: Higher-priority requests execute first when threads are saturated
Progress Tracking: Real-time progress updates for downloads, uploads, and batch operations
Cross-Platform: Windows, Linux, and macOS support with platform-specific optimizations

📦 Sample Applications

QtRequester: GUI demo application for testing HTTP requests (located in samples/networkrequesttool/)
QtDownloader: Download manager with intelligent multi-threading support (located in samples/networkdownloader/)
Unit Tests: Comprehensive test suite covering all functionality

Requirements

Build Requirements

C++17 compatible compiler (MSVC 2017+, GCC 7+, Clang 6+)
Qt 5.6.x+ with Core, Network, Widgets, Xml, Test modules
CMake 3.15+ (recommended) or QMake
OpenSSL 1.1.1 for HTTPS support

Platform-Specific Requirements

Windows

Visual Studio 2017+ or MSVC build tools
Windows SDK
OpenSSL DLLs (included in ThirdParty/)

Linux

GCC 7+ or Clang 6+
OpenSSL development packages: libssl-dev, libcrypto-dev

macOS

Xcode 10+ (Clang)
OpenSSL via Homebrew or system packages

Installation

Using CMake (Recommended)

# Clone the repository
git clone https://github.com/lucaswang420/qt-network-request.git
cd qt-network-request

# Configure and build (Windows)
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel

# Configure and build (Linux)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel

# Configure and build (macOS)
# (Requires Homebrew's OpenSSL 1.1)
export OPENSSL_ROOT_DIR=$(brew --prefix openssl@1.1)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR="${OPENSSL_ROOT_DIR}"
# Note: If building on Apple Silicon (M1/M2) but using Qt 5.x x86_64 binaries, append: -DCMAKE_OSX_ARCHITECTURES="x86_64"
cmake --build build --config Release --parallel

# Install (optional)
cmake --install build --prefix /usr/local

Using QMake

# Generate Visual Studio solution
qmake -r -tp vc QtNetworkRequest.pro

# Build using nmake
qmake
nmake release

Using Provided Scripts

Windows

# Windows build script
scripts\build_win.bat

# Generate Visual Studio solution
GenerateVsSln.bat

Linux

# Linux build script (requires execution permissions)
chmod +x scripts/build_linux.sh
./scripts/build_linux.sh

# Build with debug symbols
./scripts/build_linux.sh --debug

# Clean build and run tests
./scripts/build_linux.sh --clean --tests

macOS

# Build using the provided script (run from scripts/ directory)
./build_macos.sh --release

# With tests and explicit architecture
./build_macos.sh --release --tests --arch x86_64

# Or build directly via CMake
export OPENSSL_ROOT_DIR=$(brew --prefix openssl@1.1)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR="${OPENSSL_ROOT_DIR}"
cmake --build build --config Release --parallel

Quick Start

Basic Usage

#include "requestcontext.h"
#include "networkrequestmanager.h"
#include "networkreply.h"

using namespace QtNetworkRequest;

// Initialize in main thread
NetworkRequestManager::initialize();

// Build a multi-threaded download request with the fluent builder
auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://example.com/file.zip")
        .type(RequestType::MTDownload)
        .showProgress(true)
        .downloadConfig(std::make_unique<DownloadConfig>(
            DownloadConfig{ .saveDir = "downloads", .overwriteFile = true, .threadCount = 0 }))
        .build());
/*
 * Thread count options:
 * - 0: Auto detect CPU cores (recommended for most cases)
 * - 1: Single-threaded download
 * - N>1: Use N threads for multi-threaded download
 */

if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onFinished);
}

// Cleanup before exit
NetworkRequestManager::unInitialize();

Batch Operations

// Prepare batch requests with fluent builder
QtNetworkRequest::BatchRequestPtrTasks tasks;
for (const QString& url : urls) {
    tasks.push_back(
        RequestContextBuilder()
            .url(url)
            .type(RequestType::Download)
            .downloadConfig(std::make_unique<DownloadConfig>(
                DownloadConfig{ .saveDir = "downloads" }))
            .build());
}

// Execute batch with progress tracking
quint64 batchId = 0;
auto reply = NetworkRequestManager::globalInstance()->postBatchRequest(std::move(tasks), batchId);
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onBatchFinished);
}

Usage Examples

Example

Network Request Tool demo

MultiThread Downloader demo

File Download

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/image/png")
        .type(RequestType::Download)
        .showProgress(true)
        .downloadConfig(std::make_unique<DownloadConfig>(
            DownloadConfig{ .saveDir = "Download", .overwriteFile = true }))
        .build());
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onDownloadFinished);
}

File Upload

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/post")
        .type(RequestType::Upload)
        .showProgress(true)
        .uploadConfig(std::make_unique<UploadConfig>(
            UploadConfig{ .filePath = "resources/1.png", .usePutMethod = false }))
        .build());
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onUploadFinished);
}

HTTP GET Request

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get?userId=123&userName=456")
        .type(RequestType::Get)
        .retry(3)          // retryOnFailed = true, maxRetryCount = 3, delay 1s
        .maxRedirects(3)
        .build());
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onGetFinished);
}

HTTP POST Request

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/post")
        .type(RequestType::Post)
        .body("userId=123&userName=456")
        .retry(3)
        .maxRedirects(3)
        .build());
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onPostFinished);
}

Proxy Configuration

// Global proxy (applied to all requests unless overridden)
ProxyConfig proxy;
proxy.enabled = true;
proxy.host = "proxy.example.com";
proxy.port = 3128;
proxy.user = "username";
proxy.password = "password";
NetworkRequestManager::setGlobalProxy(proxy);

// Per-request proxy (overrides global) — pass a heap-allocated ProxyConfig
auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get")
        .type(RequestType::Get)
        .proxyConfig(std::make_unique<ProxyConfig>(
            ProxyConfig{ .enabled = true, .host = "127.0.0.1", .port = 8080 }))
        .build());

SSL/TLS Configuration

// Global secure default is applied automatically (VerifyPeer + TLS1.2+ + system CA).
// Override per-request via the builder:
auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://self-signed.example.com/api")
        .type(RequestType::Get)
        .sslConfig(SslConfig::secureDefault())   // copy; or build a custom SslConfig first
        .build());

Persistent Cookie Jar

// Enable file-backed cookie storage (in main thread before requests)
NetworkRequestManager::setCookieStoragePath("cookies.json");

// Cookies are automatically saved after each response
// and reloaded on next application start

// Disable (in-memory only)
NetworkRequestManager::setCookieStoragePath(QString());

Request Priority

auto highReply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get")
        .type(RequestType::Get)
        .priority(10)      // higher = more urgent
        .build());

auto lowReply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get")
        .type(RequestType::Get)
        .priority(0)       // default priority
        .build());

// When threads are saturated, priority 10 executes before priority 0

Retry on Failure

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get")
        .type(RequestType::Get)
        .retry(3, 1000)    // up to 3 retries, 1s base delay (then 2s, 4s — exponential)
        .build());

Request Management

// Stop single request
quint64 taskId = 1;
NetworkRequestManager::globalInstance()->stopRequest(taskId);

// Stop batch requests
quint64 batchId = 1;
NetworkRequestManager::globalInstance()->stopBatchRequests(batchId);

// Stop all requests
NetworkRequestManager::globalInstance()->stopAllRequest();

API Reference

Core Classes

NetworkRequestManager

Singleton class that manages the thread pool and request lifecycle.

Key Methods:

initialize(): Initialize the manager (must be called in main thread)
unInitialize(): Cleanup resources (must be called in main thread)
postRequest(std::unique_ptr<RequestContext>): Build with RequestContextBuilder and execute a single request
postBatchRequest(BatchRequestPtrTasks): Execute batch requests
stopRequest(quint64): Stop a specific request
stopBatchRequests(quint64): Stop batch requests
stopAllRequest(): Stop all active requests
setGlobalProxy(ProxyConfig): Set global proxy (applied to all requests)
setCookieStoragePath(path): Enable persistent cookie jar with file path
setMaxThreadCount(int): Set thread pool size (1-100)

Signals:

downloadProgress(quint64, qint64, qint64): Download progress for a single request.
uploadProgress(quint64, qint64, qint64): Upload progress for a single request.
batchDownloadProgress(quint64, qint64): Aggregated download progress for a batch of requests.
batchUploadProgress(quint64, qint64): Aggregated upload progress for a batch of requests.

RequestContext

Configuration structure for network requests (replaces the old RequestTask).

Key Properties:

url: Target URL
type: Request type (Download, Upload, Get, Post, Put, Delete, Head)
headers: Request headers (QMap<QByteArray, QByteArray>)
body: Request body for POST/PUT
behavior.showProgress: Enable progress reporting
behavior.retryOnFailed: Enable retry on transient failures
behavior.maxRetryCount: Maximum retry attempts (default: 3)
behavior.retryDelayMs: Base retry delay in ms (doubles each attempt, default: 1000)
behavior.maxRedirectionCount: Maximum redirect limit (default: 3)
behavior.priority: Request priority (higher = more urgent, default: 0)
behavior.transferTimeout: Transfer timeout in ms (default: 30000)
proxyConfig: Per-request proxy override (overrides global proxy)
downloadConfig: Download configuration (saveDir, overwriteFile, threadCount)
uploadConfig: Upload configuration (filePath, usePutMethod, useFormData, useStream)
userContext: User-defined context data

NetworkReply

Handles the asynchronous response for a single request or a batch of requests.

Signals:

requestFinished(QSharedPointer<ResponseResult>): Emitted when the request is complete (either successfully or with an error).

ResponseResult

Structure containing request response data.

Key Properties:

success: Whether the request succeeded
cancelled: Whether the request was cancelled
errorMessage: Error message if failed
body: Response body data
headers: Response headers
performance.durationMs: Request duration in milliseconds
performance.bytesReceived: Bytes received
performance.bytesSent: Bytes sent
userContext: User-defined context data

DownloadConfig

Configuration structure for download operations.

Key Properties:

saveFileName: Custom filename for the downloaded file
saveDir: Directory to save the downloaded file
overwriteFile: Whether to overwrite existing files (default: false)
threadCount: Number of download threads for multi-threaded downloads (default: 0 = auto detect CPU cores)

UploadConfig

Configuration structure for upload operations.

Key Properties:

filePath: Path to the file to upload
data: Raw data to upload
usePutMethod: Use HTTP PUT method instead of POST (default: false)
useStream: Use streaming upload (default: false)
useFormData: Use multipart form data (default: false)

Building

Build Configuration

The library supports both CMake and QMake build systems with standardized naming:

CMake: Modern, cross-platform build system with automatic dependency detection
QMake: Traditional Qt build system with Visual Studio integration

Build Targets

CMake Targets:

QNetworkRequest: Core library (DLL)
QtRequester: GUI demo application (source in samples/networkrequesttool/)
QtDownloader: Download manager application (source in samples/networkdownloader/)
UnitTests: Test suite

QMake Targets:

QNetworkRequest: Core library (DLL)
QtRequester: GUI demo application (source in samples/networkrequesttool/)
QtDownloader: Download manager application (source in samples/networkdownloader/)

Build Types

# CMake Release build
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# CMake Debug build
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug

# QMake build
qmake -r -tp vc QtNetworkRequest.pro
nmake release
nmake debug

Build Scripts

# Windows build script
scripts\build_win.bat

# Generate Visual Studio solution
GenerateVsSln.bat

Cross-Platform Building

Using CMake Directly

# Linux
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# macOS
export OPENSSL_ROOT_DIR=$(brew --prefix openssl@1.1)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR="${OPENSSL_ROOT_DIR}"
cmake --build build --config Release

# Windows
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release

Using Build Scripts

# Windows (batch script)
scripts\build_win.bat

# Linux (shell script)
chmod +x scripts/build_linux.sh
./scripts/build_linux.sh --release

Cross-Platform Compatibility

QtMultiThreadNetwork is designed to work across multiple platforms with proper build configuration.

Supported Platforms

Platform	Status	Notes
Windows	✅ Fully Supported	Primary development platform, MSVC 2017+
Linux	✅ Fully Supported	GCC 7+ or Clang 6+, CMake 3.15+
macOS	✅ Fully Supported	Xcode 10+ (Clang), CMake 3.15+

Component Compatibility

Component	Windows	Linux	macOS	Status
Core Network Functions	✅	✅	✅	Based on Qt Network (cross-platform)
Memory-Mapped Files	✅	✅	✅	Implemented with platform-specific APIs
Multi-threaded Downloads	✅	✅	✅	Compatible across platforms
Thread Pool Management	✅	✅	✅	Uses Qt's threading framework
Build System	✅	✅	✅	CMake with platform-specific optimizations
OpenSSL Integration	DLL	Dynamic	Dynamic	Platform-specific linking
GUI Applications	✅	✅	✅	Conditional WIN32 flag for proper GUI apps

Platform-Specific Implementations

Memory-Mapped Files

Windows: Uses CreateFileMapping / MapViewOfFile
Linux/macOS: Uses mmap / munmap
File Size: Supports large files (>4GB) on all platforms

Build Requirements

Windows

Compiler: MSVC 2017+
Qt: 5.6.x+
OpenSSL: DLL files (libeay32.dll, ssleay32.dll)

Linux

Compiler: GCC 7+ or Clang 6+
Qt: 5.6.x+
OpenSSL: Development packages (libssl-dev, libcrypto-dev)
Build: CMake 3.15+

macOS

Compiler: Xcode 10+ (Clang)
Qt: 5.6.x+
OpenSSL: Homebrew (brew install openssl@1.1)
Build: CMake 3.15+
Architecture: Supports both Intel (x86_64) and Apple Silicon (arm64). Use -DCMAKE_OSX_ARCHITECTURES to target a specific architecture if it differs from your Qt binaries.

Platform-Specific Notes

OpenSSL Handling: Platform-specific dynamic library linking (Windows DLLs, Unix dynamic libraries)
Build System: CMake automatically detects and configures platform-specific settings

Cross-Platform Build Instructions

# Linux/macOS build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# Find and link OpenSSL automatically on Unix systems
find_package(OpenSSL REQUIRED)
target_link_libraries(QNetworkRequest PRIVATE OpenSSL::SSL OpenSSL::Crypto)

Migration Guide

The build system now supports cross-platform compilation with automatic platform detection:

Automatic GUI Flag: The WIN32 flag is automatically applied only on Windows for GUI executables
OpenSSL Detection: CMake automatically finds and links OpenSSL on all platforms
Cross-Platform Paths: CMake handles platform-specific path separators
Threading: Thread pool management works identically across all platforms

The core library functionality is platform-agnostic and works seamlessly across all supported platforms with proper build configuration.

Testing

Running Tests

# Using CTest
cd build
ctest -C Release

# Direct execution
./test/Release/UnitTests.exe

Test Coverage

The test suite covers:

Basic request functionality (GET, POST, PUT, DELETE, HEAD, form data)
File download (single-threaded and multi-threaded)
File upload (PUT with file)
Proxy configuration (global and per-request)
Retry behavior (retry on transient failures, disabled retries)
Persistent cookie jar (save, reload, cross-request cookie sharing)
Request priority queue (thread pool saturation with priority ordering)
Request cancellation (stop running, stop batch, stop all)
Rapid cancel stress (20x create/cancel cycle)
Error handling scenarios
Progress reporting
Thread safety
Memory management
Platform-specific implementations

Contributing

We welcome contributions! Please follow these guidelines:

Fork the repository and create a feature branch
Follow the existing code style and patterns
Add tests for new functionality
Update documentation as needed
Submit a pull request with a clear description

Development Setup

# Clone with submodules
git clone --recursive https://github.com/lucaswang420/qt-network-request.git
cd qt-network-request

# Setup development build
cmake -S . -B build-dev -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
cmake --build build-dev --config Debug

Code Style

Use C++17 features and modern C++ practices
Follow Qt coding conventions
Use smart pointers for memory management
Implement proper error handling
Add comprehensive documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.

中文

基于 Qt Network 模块构建的高性能、线程安全的 C++ 多线程 HTTP(S)/FTP 网络请求库。

功能特性

🚀 核心能力

多线程架构：每个请求在独立线程中执行，使用托管的线程池
并发操作：支持单请求和批量请求两种模式
多线程下载：大文件多通道并行下载，更高性能（threadCount=0 时自动检测 CPU 核心数）
协议支持：HTTP(S)/FTP，完整请求方法（GET/POST/PUT/DELETE/HEAD/PATCH/OPTIONS）
异步 API：非阻塞操作，通过信号/槽机制推送进度
线程安全：所有公共方法均线程安全，使用原子操作

🛠️ 高级特性

内存映射文件：利用平台特定 API 实现大文件高效 I/O
批量操作：多请求编组，聚合进度追踪
指数退避重试：通过可插拔策略自动重试瞬时故障（连接拒绝、超时、SSL 错误）
可扩展架构：模板方法 + 策略 + 状态模式提供清晰的扩展点；自注册工厂消除新增请求类型时的 switch-case
代理支持：支持逐请求代理和全局代理，两级级联
持久化 Cookie Jar：基于文件的 Cookie 存储，跨请求共享
请求优先级队列：线程饱和时高优先级请求优先执行
进度追踪：下载、上传、批量操作的实时进度更新
跨平台：Windows、Linux、macOS 全支持，含平台特定优化

📦 示例应用

QtRequester：HTTP 请求测试 GUI 演示程序（位于 samples/networkrequesttool/）
QtDownloader：支持智能多线程的下载管理器（位于 samples/networkdownloader/）
Unit Tests：覆盖所有功能的全面测试套件

环境要求

构建要求

C++17 兼容编译器（MSVC 2017+、GCC 7+、Clang 6+）
Qt 5.6.x+（需 Core、Network、Widgets、Xml、Test 模块）
CMake 3.15+（推荐）或 QMake
OpenSSL 1.1.1（用于 HTTPS 支持）

平台特定要求

Windows

Visual Studio 2017+ 或 MSVC 构建工具
Windows SDK
OpenSSL DLL（已包含在 ThirdParty/ 目录）

Linux

GCC 7+ 或 Clang 6+
OpenSSL 开发包：libssl-dev、libcrypto-dev

macOS

Xcode 10+（Clang）
通过 Homebrew 或系统包安装 OpenSSL

安装

使用 CMake（推荐）

# 克隆仓库
git clone https://github.com/lucaswang420/qt-network-request.git
cd qt-network-request

# 配置并构建（Windows）
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel

# 配置并构建（Linux）
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel

# 配置并构建（macOS）
# （需要 Homebrew 安装的 OpenSSL 1.1）
export OPENSSL_ROOT_DIR=$(brew --prefix openssl@1.1)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR="${OPENSSL_ROOT_DIR}"
# 注意：如果在 Apple Silicon（M1/M2）上使用 Qt 5.x x86_64 二进制包，需追加：-DCMAKE_OSX_ARCHITECTURES="x86_64"
cmake --build build --config Release --parallel

# 安装（可选）
cmake --install build --prefix /usr/local

使用 QMake

# 生成 Visual Studio 解决方案
qmake -r -tp vc QtNetworkRequest.pro

# 使用 nmake 构建
qmake
nmake release

使用提供的脚本

Windows

# Windows 构建脚本
scripts\build_win.bat

# 生成 Visual Studio 解决方案
GenerateVsSln.bat

Linux

# Linux 构建脚本（需要执行权限）
chmod +x scripts/build_linux.sh
./scripts/build_linux.sh

# 带调试符号构建
./scripts/build_linux.sh --debug

# 清理构建并运行测试
./scripts/build_linux.sh --clean --tests

macOS

# 使用提供的脚本构建（在 scripts/ 目录下运行）
./build_macos.sh --release

# 带测试和指定架构
./build_macos.sh --release --tests --arch x86_64

# 或直接通过 CMake 构建
export OPENSSL_ROOT_DIR=$(brew --prefix openssl@1.1)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR="${OPENSSL_ROOT_DIR}"
cmake --build build --config Release --parallel

快速开始

基本用法

#include "requestcontext.h"
#include "networkrequestmanager.h"
#include "networkreply.h"

using namespace QtNetworkRequest;

// 在主线程初始化
NetworkRequestManager::initialize();

// 通过流式构造器构建多线程下载请求
auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://example.com/file.zip")
        .type(RequestType::MTDownload)
        .showProgress(true)
        .downloadConfig(std::make_unique<DownloadConfig>(
            DownloadConfig{ .saveDir = "downloads", .overwriteFile = true, .threadCount = 0 }))
        .build());
/*
 * 线程数选项：
 * - 0：自动检测 CPU 核心数（推荐，适用于大多数场景）
 * - 1：单线程下载
 * - N>1：使用 N 个线程进行多线程下载
 */

if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onFinished);
}

// 退出前清理
NetworkRequestManager::unInitialize();

批量操作

// 使用流式构造器准备批量请求
QtNetworkRequest::BatchRequestPtrTasks tasks;
for (const QString& url : urls) {
    tasks.push_back(
        RequestContextBuilder()
            .url(url)
            .type(RequestType::Download)
            .downloadConfig(std::make_unique<DownloadConfig>(
                DownloadConfig{ .saveDir = "downloads" }))
            .build());
}

// 执行批量请求并追踪进度
quint64 batchId = 0;
auto reply = NetworkRequestManager::globalInstance()->postBatchRequest(std::move(tasks), batchId);
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onBatchFinished);
}

使用示例

界面预览

Network Request Tool 演示

MultiThread Downloader 演示

文件下载

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/image/png")
        .type(RequestType::Download)
        .showProgress(true)
        .downloadConfig(std::make_unique<DownloadConfig>(
            DownloadConfig{ .saveDir = "Download", .overwriteFile = true }))
        .build());
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onDownloadFinished);
}

文件上传

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/post")
        .type(RequestType::Upload)
        .showProgress(true)
        .uploadConfig(std::make_unique<UploadConfig>(
            UploadConfig{ .filePath = "resources/1.png", .usePutMethod = false }))
        .build());
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onUploadFinished);
}

HTTP GET 请求

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get?userId=123&userName=456")
        .type(RequestType::Get)
        .retry(3)          // retryOnFailed = true，最大重试 3 次，间隔 1s
        .maxRedirects(3)
        .build());
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onGetFinished);
}

HTTP POST 请求

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/post")
        .type(RequestType::Post)
        .body("userId=123&userName=456")
        .retry(3)
        .maxRedirects(3)
        .build());
if (reply) {
    connect(reply.get(), &NetworkReply::requestFinished, this, &MyClass::onPostFinished);
}

代理配置

// 全局代理（自动应用于所有请求，除非单独覆盖）
ProxyConfig proxy;
proxy.enabled = true;
proxy.host = "proxy.example.com";
proxy.port = 3128;
proxy.user = "username";
proxy.password = "password";
NetworkRequestManager::setGlobalProxy(proxy);

// 逐请求代理（覆盖全局设置）——传入堆分配的 ProxyConfig
auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get")
        .type(RequestType::Get)
        .proxyConfig(std::make_unique<ProxyConfig>(
            ProxyConfig{ .enabled = true, .host = "127.0.0.1", .port = 8080 }))
        .build());

SSL/TLS 配置

// 全局安全默认值自动生效（VerifyPeer + TLS1.2+ + 系统 CA）。
// 可通过构造器逐请求覆盖：
auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://self-signed.example.com/api")
        .type(RequestType::Get)
        .sslConfig(SslConfig::secureDefault())   // 拷贝；也可先构造自定义 SslConfig
        .build());

持久化 Cookie Jar

// 启用基于文件的 Cookie 存储（在主线程中、发起请求之前调用）
NetworkRequestManager::setCookieStoragePath("cookies.json");

// Cookie 在每次响应后自动保存，
// 并在下次应用启动时重新加载

// 禁用（仅内存模式）
NetworkRequestManager::setCookieStoragePath(QString());

请求优先级

auto highReply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get")
        .type(RequestType::Get)
        .priority(10)      // 数值越大越优先
        .build());

auto lowReply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get")
        .type(RequestType::Get)
        .priority(0)       // 默认优先级
        .build());

// 线程饱和时，优先级 10 的请求会先于优先级 0 执行

失败重试

auto reply = NetworkRequestManager::globalInstance()->postRequest(
    RequestContextBuilder()
        .url("https://httpbin.org/get")
        .type(RequestType::Get)
        .retry(3, 1000)    // 最多重试 3 次，基础延迟 1s（随后 2s、4s——指数增长）
        .build());

请求管理

// 停止单个请求
quint64 taskId = 1;
NetworkRequestManager::globalInstance()->stopRequest(taskId);

// 停止批量请求
quint64 batchId = 1;
NetworkRequestManager::globalInstance()->stopBatchRequests(batchId);

// 停止所有请求
NetworkRequestManager::globalInstance()->stopAllRequest();

API 参考

核心类

NetworkRequestManager

管理线程池和请求生命周期的单例类。

主要方法：

initialize()：初始化管理器（必须在主线程调用）
unInitialize()：清理资源（必须在主线程调用）
postRequest(std::unique_ptr<RequestContext>)：通过 RequestContextBuilder 构建并执行单个请求
postBatchRequest(BatchRequestPtrTasks)：执行批量请求
stopRequest(quint64)：停止指定请求
stopBatchRequests(quint64)：停止批量请求
stopAllRequest()：停止所有活动请求
setGlobalProxy(ProxyConfig)：设置全局代理（应用于所有请求）
setCookieStoragePath(path)：通过文件路径启用持久化 Cookie jar
setMaxThreadCount(int)：设置线程池大小（1-100）

信号：

downloadProgress(quint64, qint64, qint64)：单个请求的下载进度
uploadProgress(quint64, qint64, qint64)：单个请求的上传进度
batchDownloadProgress(quint64, qint64)：批量请求的聚合下载进度
batchUploadProgress(quint64, qint64)：批量请求的聚合上传进度

RequestContext

网络请求的配置结构体（替代旧的 RequestTask）。

主要属性：

url：目标 URL
type：请求类型（Download、Upload、Get、Post、Put、Delete、Head）
headers：请求头（QMap<QByteArray, QByteArray>）
body：POST/PUT 的请求体
behavior.showProgress：是否启用进度上报
behavior.retryOnFailed：是否在瞬时故障时启用重试
behavior.maxRetryCount：最大重试次数（默认：3）
behavior.retryDelayMs：基础重试延迟（毫秒，每次翻倍，默认：1000）
behavior.maxRedirectionCount：最大重定向限制（默认：3）
behavior.priority：请求优先级（数值越大越优先，默认：0）
behavior.transferTimeout：传输超时（毫秒，默认：30000）
proxyConfig：逐请求代理覆盖（覆盖全局代理）
downloadConfig：下载配置（saveDir、overwriteFile、threadCount）
uploadConfig：上传配置（filePath、usePutMethod、useFormData、useStream）
userContext：用户自定义上下文数据

NetworkReply

处理单个请求或批量请求的异步响应。

信号：

requestFinished(QSharedPointer<ResponseResult>)：请求完成后发出（无论成功或出错）

ResponseResult

包含请求响应数据的结构体。

主要属性：

success：请求是否成功
cancelled：请求是否被取消
errorMessage：失败时的错误信息
body：响应体数据
headers：响应头
performance.durationMs：请求耗时（毫秒）
performance.bytesReceived：接收字节数
performance.bytesSent：发送字节数
userContext：用户自定义上下文数据

DownloadConfig

下载操作的配置结构体。

主要属性：

saveFileName：下载文件的自定义文件名
saveDir：下载文件保存目录
overwriteFile：是否覆盖已存在文件（默认：false）
threadCount：多线程下载的线程数（默认：0 = 自动检测 CPU 核心数）

UploadConfig

上传操作的配置结构体。

主要属性：

filePath：待上传文件路径
data：待上传的原始数据
usePutMethod：使用 HTTP PUT 方法而非 POST（默认：false）
useStream：使用流式上传（默认：false）
useFormData：使用 multipart 表单数据（默认：false）

构建

构建配置

本库支持 CMake 和 QMake 两种构建系统，采用标准化命名：

CMake：现代跨平台构建系统，自动检测依赖
QMake：传统 Qt 构建系统，支持 Visual Studio 集成

构建目标

CMake 目标：

QNetworkRequest：核心库（DLL）
QtRequester：GUI 演示应用（源码位于 samples/networkrequesttool/）
QtDownloader：下载管理器应用（源码位于 samples/networkdownloader/）
UnitTests：测试套件

QMake 目标：

QNetworkRequest：核心库（DLL）
QtRequester：GUI 演示应用（源码位于 samples/networkrequesttool/）
QtDownloader：下载管理器应用（源码位于 samples/networkdownloader/）

构建类型

# CMake Release 构建
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# CMake Debug 构建
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug

# QMake 构建
qmake -r -tp vc QtNetworkRequest.pro
nmake release
nmake debug

构建脚本

# Windows 构建脚本
scripts\build_win.bat

# 生成 Visual Studio 解决方案
GenerateVsSln.bat

跨平台构建

直接使用 CMake

# Linux
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# macOS
export OPENSSL_ROOT_DIR=$(brew --prefix openssl@1.1)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR="${OPENSSL_ROOT_DIR}"
cmake --build build --config Release

# Windows
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release

使用构建脚本

# Windows（批处理脚本）
scripts\build_win.bat

# Linux（Shell 脚本）
chmod +x scripts/build_linux.sh
./scripts/build_linux.sh --release

跨平台兼容性

QtMultiThreadNetwork 设计为跨平台运行，通过适当的构建配置即可。

支持平台

平台	状态	备注
Windows	✅ 完全支持	主要开发平台，MSVC 2017+
Linux	✅ 完全支持	GCC 7+ 或 Clang 6+，CMake 3.15+
macOS	✅ 完全支持	Xcode 10+（Clang），CMake 3.15+

组件兼容性

组件	Windows	Linux	macOS	状态
核心网络功能	✅	✅	✅	基于 Qt Network（跨平台）
内存映射文件	✅	✅	✅	使用平台特定 API 实现
多线程下载	✅	✅	✅	跨平台兼容
线程池管理	✅	✅	✅	使用 Qt 线程框架
构建系统	✅	✅	✅	CMake + 平台特定优化
OpenSSL 集成	DLL	动态	动态	平台特定链接方式
GUI 应用	✅	✅	✅	条件 WIN32 标志，正确生成 GUI 应用

平台特定实现

内存映射文件

Windows：使用 CreateFileMapping / MapViewOfFile
Linux/macOS：使用 mmap / munmap
文件大小：所有平台均支持大文件（>4GB）

构建要求

Windows

编译器：MSVC 2017+
Qt：5.6.x+
OpenSSL：DLL 文件（libeay32.dll、ssleay32.dll）

Linux

编译器：GCC 7+ 或 Clang 6+
Qt：5.6.x+
OpenSSL：开发包（libssl-dev、libcrypto-dev）
构建：CMake 3.15+

macOS

编译器：Xcode 10+（Clang）
Qt：5.6.x+
OpenSSL：Homebrew 安装（brew install openssl@1.1）
构建：CMake 3.15+
架构：支持 Intel（x86_64）和 Apple Silicon（arm64）。如果架构与 Qt 二进制包不同，请使用 -DCMAKE_OSX_ARCHITECTURES 指定目标架构。

平台特定注意事项

OpenSSL 处理：平台特定的动态库链接（Windows DLL、Unix 动态库）
构建系统：CMake 自动检测并配置平台特定设置

跨平台构建说明

# Linux/macOS 构建
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# 在 Unix 系统上自动查找并链接 OpenSSL
find_package(OpenSSL REQUIRED)
target_link_libraries(QNetworkRequest PRIVATE OpenSSL::SSL OpenSSL::Crypto)

迁移指南

构建系统现已支持跨平台编译，具备自动平台检测功能：

自动 GUI 标志：WIN32 标志仅在 Windows 上自动应用于 GUI 可执行文件
OpenSSL 检测：CMake 在所有平台上自动查找并链接 OpenSSL
跨平台路径：CMake 处理平台特定的路径分隔符
线程：线程池管理在所有平台上行为一致

核心库功能与平台无关，在正确的构建配置下可在所有支持的平台上无缝运行。

测试

运行测试

# 使用 CTest
cd build
ctest -C Release

# 直接执行
./test/Release/UnitTests.exe

测试覆盖

测试套件覆盖以下功能：

基本请求功能（GET、POST、PUT、DELETE、HEAD、表单数据）
文件下载（单线程和多线程）
文件上传（PUT 方式上传文件）
代理配置（全局和逐请求代理）
重试行为（瞬时故障重试、禁用重试）
持久化 Cookie jar（保存、重新加载、跨请求 Cookie 共享）
请求优先级队列（线程池饱和时的优先级排序）
请求取消（停止正在运行的请求、停止批量、停止全部）
快速取消压力测试（20 次创建/取消循环）
错误处理场景
进度上报
线程安全
内存管理
平台特定实现

贡献

欢迎贡献！请遵循以下指引：

Fork 仓库并创建功能分支
遵循现有代码风格和模式
为新功能添加测试
根据需要更新文档
提交 Pull Request，并附上清晰的描述

开发环境搭建

# 克隆（含子模块）
git clone --recursive https://github.com/lucaswang420/qt-network-request.git
cd qt-network-request

# 搭建开发构建
cmake -S . -B build-dev -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
cmake --build build-dev --config Debug

代码风格

使用 C++17 特性和现代 C++ 实践
遵循 Qt 编码规范
使用智能指针管理内存
实现合理的错误处理
添加完善的文档

许可证

本项目采用 MIT 许可证 — 详见 LICENSE 文件。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
.workbuddy/outputs		.workbuddy/outputs
ThirdParty/openssl		ThirdParty/openssl
cmake		cmake
docs		docs
images		images
include		include
ports/qtnetworkrequest		ports/qtnetworkrequest
samples		samples
scripts		scripts
source		source
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
.linguist		.linguist
.qt.conf		.qt.conf
AGENTS.md		AGENTS.md
CMakeLists.txt		CMakeLists.txt
Changelog		Changelog
GenerateVsSln.bat		GenerateVsSln.bat
LICENSE		LICENSE
QtNetworkRequest.pro		QtNetworkRequest.pro
README.md		README.md
README.zh-CN.md		README.zh-CN.md
conanfile.py		conanfile.py

Latest commit

History

Folders and files

Repository files navigation

QtMultiThreadNetwork

English

Table of Contents

Features

🚀 Core Capabilities

🛠️ Advanced Features

📦 Sample Applications

Requirements

Build Requirements

Platform-Specific Requirements

Windows

Linux

macOS

Installation

Using CMake (Recommended)

Using QMake

Using Provided Scripts

Windows

Linux

macOS

Quick Start

Basic Usage

Batch Operations

Usage Examples

Example

File Download

File Upload

HTTP GET Request

HTTP POST Request

Proxy Configuration

SSL/TLS Configuration

Persistent Cookie Jar

Request Priority

Retry on Failure

Request Management

API Reference

Core Classes

NetworkRequestManager

RequestContext

NetworkReply

ResponseResult

DownloadConfig

UploadConfig

Building

Build Configuration

Build Targets

Build Types

Build Scripts

Cross-Platform Building

Using CMake Directly

Using Build Scripts

Cross-Platform Compatibility

Supported Platforms

Component Compatibility

Platform-Specific Implementations

Memory-Mapped Files

Build Requirements

Windows

Linux

macOS

Platform-Specific Notes

Cross-Platform Build Instructions

Migration Guide

Testing

Running Tests

Test Coverage

Contributing

Development Setup

Code Style

License

中文

目录

功能特性

🚀 核心能力

🛠️ 高级特性

📦 示例应用