SocksProxy 1.0.3

SocksWebProxy

一个高性能、易用的 .NET SOCKS 代理实现，支持 SOCKS4/4a/5 协议。

✨ 特性

• 支持 SOCKS4、SOCKS4a 和 SOCKS5 协议
• 支持用户名/密码认证 (SOCKS5)
• 支持用户标识 (SOCKS4/4a)
• 智能的资源管理
  • 自动清理过期代理资源
  • 异步清理机制
  • 线程安全的缓存系统
• 内存友好的缓存机制
• 灵活的配置选项
• 支持依赖注入
• 多种使用方式

📦 安装

# 基本包
dotnet add package GeekTools.SocksProxy

# 如果需要依赖注入支持
dotnet add package Microsoft.Extensions.DependencyInjection.Abstractions
dotnet add package Microsoft.Extensions.Http

🚀 快速开始

1. 基本用法

// 直接使用
var handler = new HttpClientHandler
{
    Proxy = new SocksWebProxy("127.0.0.1", 1080)
};
var client = new HttpClient(handler);

// 使用扩展方法
var handler = new HttpClientHandler()
    .UseSocksProxy("127.0.0.1", 1080);
var client = new HttpClient(handler);

// 使用工厂方法
var proxy = SocksWebProxy.GetProxy("127.0.0.1", 1080);

2. 依赖注入

// 基本注册
services.AddHttpClientWithSocksProxy(
    "MyClient", 
    "127.0.0.1", 
    1080);

// 带配置的注册
services.AddHttpClientWithSocksProxy(
    "MyClient",
    "127.0.0.1",
    1080,
    client =>
    {
        client.BaseAddress = new Uri("https://api.example.com");
        client.Timeout = TimeSpan.FromSeconds(30);
    });

// 类型化客户端注册
services.AddHttpClientWithSocksProxy<MyApiClient>(
    "127.0.0.1",
    1080);

// 在服务中使用
public class MyService
{
    private readonly HttpClient _client;

    public MyService(IHttpClientFactory clientFactory)
    {
        _client = clientFactory.CreateClient("MyClient");
    }
}

// 使用类型化客户端
public class MyApiClient
{
    private readonly HttpClient _client;

    public MyApiClient(HttpClient client)
    {
        _client = client;
    }
}

3. SOCKS5 认证

// 直接使用
var handler = new HttpClientHandler()
    .UseSocksProxy("127.0.0.1", 1080,
        SocksWebProxy.SocksVersion.Socks5,
        username: "user",
        password: "pass");

// 依赖注入
services.AddHttpClientWithSocksProxy(
    "MyClient",
    "127.0.0.1",
    1080,
    version: SocksWebProxy.SocksVersion.Socks5,
    username: "user",
    password: "pass");

4. 自定义配置

var options = new SocksWebProxyOptions
{
    EnableAutoCleanup = true,     // 启用自动清理
    EnableCaching = true,         // 启用缓存
    CleanupInterval = TimeSpan.FromMinutes(10),  // 清理间隔
    CacheExpiration = TimeSpan.FromHours(1)      // 缓存过期时间
};

var handler = new HttpClientHandler()
    .UseSocksProxy("127.0.0.1", 1080, options: options);

🔧 配置选项

SocksWebProxyOptions

详细配置说明：

EnableAutoCleanup

• 作用：自动清理不再使用的代理资源，防止资源泄露
• 特点：
  • 异步清理机制，不影响主线程性能
  • 智能跟踪代理实例使用状态
  • 自动调整清理频率
• 建议：一般情况下保持启用，特殊场景可禁用

EnableCaching

• 作用：复用相同配置的代理实例，优化内存使用
• 特点：
  • 使用 WeakReference 弱引用机制
  • 线程安全的缓存实现
  • 自动过期清理
• 建议：频繁创建代理时建议启用

CleanupInterval

• 作用：定期清理未使用或过期的代理实例
• 特点：
  • 可动态调整清理间隔
  • 自动停止无需清理时的定时器
  • 资源使用量感知
• 建议：根据应用场景和资源使用情况调整

CacheExpiration

• 作用：控制缓存代理实例的生命周期
• 特点：
  • 基于创建时间的过期机制
  • 支持动态调整
  • 内存友好的实现
• 建议：根据代理服务器的稳定性和应用需求调整

配置场景示例

// 高性能场景：长连接，低清理频率
var options = new SocksWebProxyOptions
{
    EnableAutoCleanup = true,
    EnableCaching = true,
    CleanupInterval = TimeSpan.FromHours(1),
    CacheExpiration = TimeSpan.FromHours(24)
};

// 内存敏感场景：短连接，频繁清理
var options = new SocksWebProxyOptions
{
    EnableAutoCleanup = true,
    EnableCaching = true,
    CleanupInterval = TimeSpan.FromMinutes(1),
    CacheExpiration = TimeSpan.FromMinutes(5)
};

// 手动管理场景：禁用自动管理
var options = new SocksWebProxyOptions
{
    EnableAutoCleanup = false,
    EnableCaching = false
};

📝 注意事项

1. SOCKS4 只支持 IPv4

2. SOCKS4a 添加了域名解析支持

3. SOCKS5 支持 IPv4、IPv6 和域名

4. 代理实例会被缓存和复用

5. 自动清理过期的缓存实例

6. 依赖注入需要安装 Microsoft.Extensions.Http 包

7. 重要: 使用时必须传入 HttpClientHandler 以确保资源能够被正确跟踪和清理：

   // 推荐方式 1: 使用扩展方法
   var handler = new HttpClientHandler()
       .UseSocksProxy("127.0.0.1", 1080);
   
   // 推荐方式 2: 使用工厂方法（需要传入 handler）
   var handler = new HttpClientHandler();
   var proxy = SocksWebProxy.GetProxy("127.0.0.1", 1080, handler: handler);
   
   // 推荐方式 3: 使用依赖注入
   services.AddHttpClientWithSocksProxy("MyClient", "127.0.0.1", 1080);
   
   // 推荐方式 4: 直接构造（需要传入 handler）
   var handler = new HttpClientHandler();
   var proxy = new SocksWebProxy("127.0.0.1", 1080, handler: handler);
   
   // 不推荐: 不传入 handler
   var proxy = SocksWebProxy.GetProxy("127.0.0.1", 1080); // ❌ 没有资源跟踪
   var proxy = new SocksWebProxy("127.0.0.1", 1080); // ❌ 没有资源跟踪
   

   无论使用哪种方式，都需要确保传入 HttpClientHandler 以启用资源跟踪和自动清理功能。

🔍 性能考虑

• 异步清理机制
  • 使用 Task-based 异步模式
  • 避免阻塞主线程
  • 智能调度清理任务
• 线程安全实现
  • 使用 ConcurrentDictionary 确保线程安全
  • 原子操作计数器
  • 锁优化
• 资源管理
  • 自动管理代理实例生命周期
  • 智能清理未使用资源
  • 内存泄漏防护
• 缓存优化
  • WeakReference 弱引用机制
  • 可配置的缓存策略
  • 自动过期处理
• 依赖注入支持
  • 支持单例模式
  • 生命周期管理
  • 资源共享

📋 支持的平台

• .NET Standard 2+
• .NET 5.0+
• .NET 6.0+
• .NET 7.0+
• .NET 8.0+

📄 许可证

MIT License

📚 更新日志

1.0.2 (2024-11-20)

• 可选依赖包安装

1.0.1 (2024-11-20)

• 优化资源清理机制
• 添加异步清理支持
• 改进日志输出
• 增强性能监控
• 完善文档

1.0.0 (2024-11-19)

• 初始发布
• 支持 SOCKS4/4a/5 协议
• 自动清理代理资源
• 可配置的缓存机制
• 添加依赖注入支持