# HttpTransferLib

**Repository Path**: AITechInfo/http-transfer-lib

## Basic Information

- **Project Name**: HttpTransferLib
- **Description**: No description available
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HttpTransferLib - 统一的 HTTP 文件传输工具类库

![.NET](https://img.shields.io/badge/.NET-4.0%20|%204.5%20|%20Standard%202.0%20|%208.0-blue)
![NuGet](https://img.shields.io/badge/NuGet-Newtonsoft.Json%2013.0.3-green)

## 目录

- [概述](#概述)
- [支持平台](#支持平台)
- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [模块详解](#模块详解)
  - [1. 认证模块 (Auth)](#1-认证模块-auth)
  - [2. 文件下载模块 (Download)](#2-文件下载模块-download)
  - [3. 文件上传模块 (Upload)](#3-文件上传模块-upload)
  - [4. JSON API 模块 (Json)](#4-json-api-模块-json)
  - [5. 进度报告模块 (Progress)](#5-进度报告模块-progress)
  - [6. 连接池模块 (Pool)](#6-连接池模块-pool)
  - [7. 公共模块 (Common)](#7-公共模块-common)
- [完整示例](#完整示例)
- [项目结构](#项目结构)

---

## 概述

HttpTransferLib 是一个基于 `System.Net.Http` 构建的统一 HTTP 文件传输工具类库，提供了文件上传/下载、断点续传、多线程并行下载、远程文件夹打包下载、JSON API 调用、统一登录认证、实时进度报告和 HttpClient 连接池管理等一站式功能。

> **背景**：在 .NET 应用开发中，频繁创建 `HttpClient` 会导致 Socket 耗尽和性能下降，大文件传输缺少断点续传，缺乏标准化进度反馈接口。本库旨在解决这些问题。

---

## 支持平台

| 目标框架 | 说明 |
|----------|------|
| `.NET Framework 4.0` | 最低支持版本（需 Microsoft.Bcl.Async + Microsoft.Net.Http） |
| `.NET Framework 4.5+` | 原生支持 async/await |
| `.NET Standard 2.0` | 适用于 .NET Core 2.x / .NET 5/6/7 |
| `.NET 8.0+` | 最新平台优化 |

外部依赖仅 `Newtonsoft.Json 13.0.3`（JSON 序列化）。

---

## 功能特性

### 下载功能
- **普通下载** — 单线程 HTTP 文件下载，支持自定义请求头
- **断点续传** — 基于 HTTP `Range` 头恢复中断的下载
- **多线程并行下载** — 大文件分块并发下载，完成后自动合并
- **远程文件夹打包** — 支持 `?download=1`（按清单逐文件下载）和 `?zip=1`（服务端直接返回 ZIP）
- **下载队列管理** — 并发数限制、优先级、暂停/恢复/取消
- **自动重试** — 可配置次数和指数退避间隔
- **完整性校验** — 支持 MD5/SHA256 验证
- **下载限速** — 带宽控制（字节/秒）
- **下载状态持久化** — 程序重启后恢复未完成的任务

### 上传功能
- **multipart/form-data** — 标准 HTTP 表单文件上传
- **分块上传** — 大文件自动分块（可配置块大小）
- **断点续传** — 分块级别的上传恢复
- **多文件批量上传** — 单次请求上传多个文件
- **表单字段混合** — 自定义字段与文件同时提交
- **上传前压缩** — 可选 GZip 压缩

### JSON API 调用
- 支持 GET / POST / PUT / DELETE / PATCH
- 自动序列化请求对象 / 反序列化响应为强类型
- 查询字符串参数构建
- 自定义请求头

### 认证管理
- **Bearer Token** — 支持自动刷新（过期前 5 分钟预刷新）
- **Cookie 认证** — ASP.NET Forms Auth 等场景
- **Basic 认证** — 支持直接传入或工厂模式获取凭证
- **自定义认证** — 实现 `IAuthProvider` 接口即可扩展

### 进度报告
- 遵循 `IProgress<T>` 标准模式
- 实时报告：百分比、已传输字节、总字节
- 瞬时速度计算（指数平滑算法）
- 预计剩余时间（ETA）
- **多任务进度聚合** — `MultiProgressReporter` 管理并发传输

### 连接池
- **单例工厂** — 全局共享 HttpClient 实例
- **BaseAddress 隔离** — 按目标独立维护连接
- **生命周期管理** — 自动过期清理，解决 DNS 刷新问题
- **自动解压** — GZip/Deflate

---

## 快速开始

### 安装

通过 NuGet 安装：

```
Install-Package HttpTransferLib
```

或直接在解决方案中引用项目：

```xml
<ProjectReference Include="..\HttpTransferLib\HttpTransferLib.csproj" />
```

### 最简示例

```csharp
using HttpTransferLib.Core;
using HttpTransferLib.Progress;

// 1. 创建客户端
using var client = new HttpTransferClient(new TransferOptions
{
    BaseUrl = "https://api.example.com"
});

// 2. 下载文件（带进度条）
var progress = new Progress<TransferProgress>(p =>
    Console.Write($"\r{p.Percentage:F1}% - {p.SpeedKbps:F1} KB/s"));

await client.DownloadAsync(
    url: "/files/large-file.zip",
    localPath: @"d:\downloads\large-file.zip",
    progress: progress);

Console.WriteLine("\n下载完成!");
```

---

## 模块详解

### 1. 认证模块 (Auth)

#### 接口定义

```csharp
public interface IAuthProvider
{
    string Name { get; }
    bool IsAuthenticated { get; }
    Task ApplyAuthenticationAsync(HttpRequestMessage request, CancellationToken ct = default);
    Task<bool> RefreshAuthenticationAsync(CancellationToken ct = default);
}
```

#### Bearer Token 认证

```csharp
client.SetAuthProvider(new BearerAuthProvider(
    tokenFactory: async () =>
    {
        // 首次获取 Token
        var response = await httpClient.PostAsync("/auth/login", ...);
        return await response.Content.ReadAsStringAsync();
    },
    tokenRefreshFactory: async () =>
    {
        // Token 过期时自动刷新
        return await RefreshTokenAsync();
    }
));
```

特性：
- Token 过期前 5 分钟自动触发刷新
- `SemaphoreSlim(1,1)` 确保并发请求下仅刷新一次
- 支持固定 Token、同步/异步工厂

#### Cookie 认证

```csharp
var cookieAuth = new CookieAuthProvider(async () =>
{
    var loginData = new FormUrlEncodedContent(new[] {
        new KeyValuePair<string, string>("username", "admin"),
        new KeyValuePair<string, string>("password", "secret")
    });
    var response = await httpClient.PostAsync("/login", loginData);
    return string.Join("; ", response.Headers.GetValues("Set-Cookie"));
});
client.SetAuthProvider(cookieAuth);
```

#### Basic 认证

```csharp
// 直接传入
client.SetAuthProvider(new BasicAuthProvider("admin", "secret"));

// 同步工厂
client.SetAuthProvider(new BasicAuthProvider(
    () => ConfigurationManager.AppSettings["Username"],
    () => ConfigurationManager.AppSettings["Password"]
));

// 异步工厂
client.SetAuthProvider(new BasicAuthProvider(
    async () => await SecureStorage.GetAsync("username"),
    async () => await SecureStorage.GetAsync("password")
));
```

#### 自定义认证

实现 `IAuthProvider` 接口即可支持任意认证方式：

```csharp
public class ApiKeyAuthProvider : IAuthProvider
{
    public string Name => "API-Key";
    public bool IsAuthenticated => true;

    public async Task ApplyAuthenticationAsync(HttpRequestMessage request, CancellationToken ct)
    {
        request.Headers.Add("X-API-Key", "your-api-key");
    }

    public Task<bool> RefreshAuthenticationAsync(CancellationToken ct)
        => Task.FromResult(true);
}
```

---

### 2. 文件下载模块 (Download)

#### DownloadOptions 配置

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `EnableResume` | bool | `true` | 断点续传 |
| `EnableParallelDownload` | bool | `false` | 多线程分块下载 |
| `ChunkCount` | int | `0` | 并行线程数（0=自动计算） |
| `ParallelMinFileSize` | long | `10MB` | 并行下载最小文件阈值 |
| `SpeedLimitBytesPerSecond` | long | `0` | 下载限速（0=不限） |
| `VerifyHash` | bool | `false` | 完整性校验 |
| `ExpectedHash` | string | `null` | 期望哈希值 |
| `HashAlgorithm` | enum | `MD5` | 哈希算法 |
| `MaxRetryCount` | int | `3` | 最大重试次数 |
| `OverwriteExisting` | bool | `false` | 覆盖已有文件 |
| `StateFilePath` | string | `null` | 状态持久化路径 |
| `BufferSize` | int | `81920` | 写缓冲区大小 |

#### 普通下载

```csharp
await client.DownloadAsync(url, localPath, new DownloadOptions
{
    EnableResume = true,
    MaxRetryCount = 5,
    SpeedLimitBytesPerSecond = 1024 * 1024 // 1MB/s 限速
});
```

#### 多线程并行下载（大文件加速）

```csharp
await client.DownloadAsync(url, localPath, new DownloadOptions
{
    EnableParallelDownload = true,
    ChunkCount = 4  // 4 个线程并发
});
```

> 原理：将文件分为 N 块，每块用独立的 HTTP Range 请求并发下载到临时文件，下载完成后合并。服务端不支持 Range 时自动降级为普通下载。

#### 远程文件夹打包下载

URL 后添加查询参数触发远程文件夹下载：

```csharp
// ?download=1 模式：获取服务端 JSON 清单，逐文件下载到本地文件夹
await client.DownloadFolderAsync(
    "https://cdn.example.com/project?download=1",
    new FolderDownloadOptions
    {
        OutputPath = @"d:\projects",
        MaxConcurrent = 3
    });

// ?zip=1 模式：服务端直接返回 ZIP 压缩包
await client.DownloadFolderAsync(
    "https://cdn.example.com/project?zip=1",
    new FolderDownloadOptions
    {
        OutputPath = @"d:\downloads\project.zip"
    });
```

服务端 `?download=1` 应返回的 JSON 格式：

```json
{
  "folderName": "myproject",
  "totalSize": 12345678,
  "files": [
    { "url": "https://cdn.example.com/project/file1.txt", "name": "file1.txt", "size": 1234 },
    { "url": "https://cdn.example.com/project/sub/file2.jpg", "name": "sub/file2.jpg", "size": 5678 }
  ]
}
```

#### 下载队列管理

```csharp
// 添加任务到队列
var task1 = client.EnqueueDownload(url1, path1);
var task2 = client.EnqueueDownload(url2, path2);

// 管理任务
task1.Pause();
task2.Resume();
// task1.Cancel();

// 查看队列
var queue = client.GetDownloadQueue();

// 等待完成
await task1.WaitAsync();
```

#### 断点续传恢复

```csharp
// 从持久化的状态文件恢复中断的下载
await client.ResumeDownloadAsync(@"d:\downloads\state.json");
```

---

### 3. 文件上传模块 (Upload)

#### UploadOptions 配置

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `ChunkSize` | int | `5MB` | 分块大小 |
| `EnableChunkedUpload` | bool | `true` | 分块上传 |
| `EnableResume` | bool | `true` | 断点续传 |
| `CompressBeforeUpload` | bool | `false` | 上传前 GZip 压缩 |
| `RemoteFileName` | string | `null` | 服务端保存的文件名 |
| `MergeChunksUrl` | string | `null` | 分块合并通知接口 |
| `SpeedLimitBytesPerSecond` | long | `0` | 上传限速 |
| `FormFields` | Dictionary | `{}` | 自定义表单字段 |

#### 单文件上传

```csharp
await client.UploadAsync("/api/upload", @"d:\data.zip", new UploadOptions
{
    RemoteFileName = "backup.zip",
    FormFields = { ["category"] = "backup" }
});
```

#### 批量上传

```csharp
var multipartUploader = new MultipartUploader(client.HttpClient);
await multipartUploader.UploadMultipleAsync(
    "/api/upload",
    new[] { @"d:\file1.zip", @"d:\file2.jpg" },
    new UploadOptions { RemoteFileName = "files" }
);
```

---

### 4. JSON API 模块 (Json)

```csharp
// GET
var users = await client.GetJsonAsync<List<UserInfo>>("/api/users");

// POST
var created = await client.PostJsonAsync<CreateUserReq, UserInfo>("/api/users", newUser);

// PUT
var updated = await client.PutJsonAsync<CreateUserReq, UserInfo>("/api/users/1", updatedUser);

// DELETE
await client.DeleteJsonAsync<object>("/api/users/1");

// 查询参数
var jsonClient = new JsonRestClient(client.HttpClient);
jsonClient.AddQueryParameter("page", "1");
jsonClient.AddQueryParameter("size", "20");
var result = await jsonClient.GetAsync<PagedResult<UserInfo>>("/api/users");
```

---

### 5. 进度报告模块 (Progress)

#### TransferProgress 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `TaskId` | Guid | 任务唯一标识 |
| `Type` | TransferType | Download / Upload |
| `SourceUrl` | string | 源 URL |
| `LocalPath` | string | 本地路径 |
| `FileName` | string | 文件名（自动提取） |
| `BytesTransferred` | long | 已传输字节 |
| `TotalBytes` | long | 总字节 |
| `Percentage` | double | 百分比（0-100） |
| `SpeedBytesPerSecond` | double | 瞬时速度 |
| `SpeedKbps` | double | 速度（KB/s） |
| `EstimatedTimeRemaining` | TimeSpan? | 预计剩余时间 |
| `Status` | TransferStatus | 运行/暂停/完成/失败/取消 |
| `CurrentChunkIndex` | int | 当前分块索引 |
| `TotalChunks` | int | 总分块数 |

#### 单任务进度

```csharp
var progress = new Progress<TransferProgress>(p =>
    Console.Write($"\r{p.FileName}: {p.Percentage:F1}% | {p.SpeedKbps:F1} KB/s"));
```

#### 多任务并发进度聚合

```csharp
var batchProgress = new Progress<IReadOnlyList<TransferProgress>>(snapshot =>
{
    Console.Clear();
    foreach (var p in snapshot)
    {
        Console.WriteLine($"  {p.FileName,-30} " +
            $"{p.Percentage,6:F1}%  {p.SpeedKbps,7:F1} KB/s  [{p.Status}]");
    }
    Console.WriteLine($"--- 总计: {snapshot.Count} 个任务 ---");
});

var multi = new MultiProgressReporter(batchProgress);
```

---

### 6. 连接池模块 (Pool)

连接池采用 **单例模式** 管理 `HttpClient` 实例，解决以下问题：

- 频繁 `new HttpClient()` 导致的 Socket 耗尽
- 长时间复用同一实例导致的 DNS 缓存问题
- 连接数无限制导致的资源竞争

```csharp
// 获取池统计
var pool = HttpClientPool.Instance;
var stats = pool.Statistics;

Console.WriteLine($"活跃连接: {stats.ActiveCount}");
Console.WriteLine($"总创建: {stats.TotalCreated}");
Console.WriteLine($"总释放: {stats.TotalDisposed}");

// 自定义池配置
var config = new HttpClientPoolConfig
{
    BaseAddress = "https://api.example.com",
    LifeTime = TimeSpan.FromMinutes(5),
    MaxConnections = 20,
    AllowAutoRedirect = true
};
```

特性：
- 每 30 秒自动清理过期客户端
- `PooledConnectionLifetime` 控制 DNS 刷新
- 支持自定义 `HttpMessageHandler`（代理、证书等）

---

### 7. 公共模块 (Common)

#### RetryPolicy — 重试策略

```csharp
var retry = new RetryPolicy
{
    MaxRetryCount = 5,
    RetryIntervalMs = 1000,
    UseExponentialBackoff = true,
    MaxRetryIntervalMs = 30000
};

// 可重试的 HTTP 状态码: 408, 429, 500, 502, 503, 504
```

#### HashValidator — 完整性校验

```csharp
// 计算 MD5
var hash = await HashValidator.ComputeHashAsync(filePath);

// 验证 SHA256
var isValid = await HashValidator.ValidateAsync(filePath, expectedHash,
    HashValidator.HashAlgorithmType.SHA256);
```

#### Logger — 日志组件

```csharp
// 自定义日志输出
Logger.LogWriter = (level, message) => myLogger.Log(level, message);
Logger.MinLevel = LogLevel.Debug;
```

---

## 完整示例

请参考 [DemoApp/Program.cs](DemoApp/Program.cs) 的完整示例代码，包含：

1. Bearer Token 登录认证 + Token 自动刷新
2. Cookie 表单登录认证
3. Basic 认证（三种构造方式）
4. 文件下载（带进度条 + 断点续传）
5. 文件上传（分块上传 + 进度）
6. JSON API 调用（CRUD）
7. 远程文件夹打包下载（?download=1 / ?zip=1）
8. 多任务并发进度聚合
9. 自定义认证处理器
10. 连接池统计监控

---

## 项目结构

```
HttpTransferLib/
├── HttpTransferLib.slnx                    # 解决方案文件
├── DemoApp/                                # 演示控制台应用
│   ├── DemoApp.csproj
│   └── Program.cs                          # 完整示例代码
├── HttpTransferLib/                        # 核心类库
│   ├── HttpTransferLib.csproj              # 多目标框架 (net40;net45;netstandard2.0;net8.0)
│   ├── Compat.cs                           # NET40 polyfill (IProgress, TaskEx)
│   ├── Core/
│   │   ├── IHttpTransferClient.cs          # 统一主接口
│   │   ├── HttpTransferClient.cs           # 主实现（集成所有功能）
│   │   └── TransferOptions.cs              # 全局配置
│   ├── Auth/
│   │   ├── IAuthProvider.cs                # 认证提供者接口
│   │   ├── BearerAuthProvider.cs           # Bearer Token (自动刷新)
│   │   ├── CookieAuthProvider.cs           # Cookie 认证
│   │   └── BasicAuthProvider.cs            # Basic 认证
│   ├── Pool/
│   │   ├── IHttpClientPool.cs             # 连接池接口
│   │   └── HttpClientPool.cs              # 单例连接池实现
│   ├── Download/
│   │   ├── DownloadOptions.cs             # 下载配置
│   │   ├── Downloader.cs                  # 普通下载器
│   │   ├── RangeDownloader.cs             # 断点续传下载器
│   │   ├── ParallelDownloader.cs          # 多线程并行下载器
│   │   ├── DownloadTask.cs                # 下载任务管理
│   │   ├── BundleDownloader.cs            # 批量打包下载
│   │   └── RemoteFolderDownloader.cs      # 远程文件夹下载
│   ├── Upload/
│   │   ├── UploadOptions.cs               # 上传配置
│   │   ├── Uploader.cs                    # 上传器
│   │   ├── MultipartUploader.cs           # 多文件上传
│   │   └── ResumableUploader.cs           # 分块续传上传器
│   ├── Json/
│   │   └── JsonRestClient.cs              # JSON REST 客户端
│   ├── Progress/
│   │   ├── TransferProgress.cs            # 进度数据模型（含文件标识）
│   │   ├── ProgressReporter.cs            # 进度报告器（速度/ETA）
│   │   └── MultiProgressReporter.cs       # 多任务进度聚合
│   └── Common/
│       ├── RetryPolicy.cs                 # 重试策略（指数退避）
│       ├── HashValidator.cs               # 文件完整性校验
│       ├── JsonHelper.cs                  # JSON 序列化（Newtonsoft.Json）
│       └── Logger.cs                      # 日志组件
```

---

## 许可证

MIT License