proxy-pool-manager 1.0.0

package/README.md

@@ -0,0 +1,653 @@
+# Proxy Manager SDK
+
+一个功能强大的代理管理器 SDK，提供代理管理、HTTP 请求封装、自动代理轮换和健康检查等功能。
+
+## ✨ 特性
+
+- 🔄 **智能代理管理**：支持从 MongoDB 加载代理，自动验证和轮换
+- 🌐 **HTTP 请求封装**：内置 HTTP 客户端，支持自动代理切换
+- 📊 **代理健康检查**：自动检测代理可用性，支持自定义检测规则
+- 🎯 **多种代理策略**：支持顺序、随机、故障转移三种策略
+- 📦 **批量操作**：支持批量插入和管理代理
+- 🔍 **日志系统**：基于 Winston 的完整日志记录
+- ⚡ **异步队列**：高效的异步任务处理机制
+- 🛡️ **类型安全**：完整的 TypeScript 类型定义
+
+## 📦 安装
+
+```bash
+npm install proxy_manager
+```
+
+## 🚀 快速开始
+
+### 基本使用
+
+```typescript
+import { createProxyRequest } from 'proxy_manager';
+
+// 创建 SDK 实例
+const sdk = await createProxyRequest({
+  mongoUri: 'mongodb://localhost:27017/proxy_db',
+  proxyStrategy: 'sequential',
+  logLevel: 'info',
+  timeout: 30,
+  proxyCheckOptions: {
+    mainUrl: 'http://example.com/check',
+    timeout: 10,
+  }
+});
+
+// 发送 GET 请求
+const response = await sdk.get('https://api.example.com/data', {
+  params: { page: 1 }
+});
+
+console.log(response.data);
+```
+
+### 添加代理
+
+```typescript
+// 添加单个代理
+await sdk.addProxy('proxy.example.com:8080:username:password');
+
+// 批量添加代理
+const count = await sdk.bulkInsertProxies([
+  'proxy1.example.com:8080:user1:pass1',
+  'proxy2.example.com:8080:user2:pass2',
+  'proxy3.example.com:8080:user3:pass3',
+]);
+
+console.log(`成功添加 ${count} 个代理`);
+```
+
+### HTTP 请求方法
+
+```typescript
+// GET 请求
+const getResponse = await sdk.get('https://api.example.com/users', {
+  params: { page: 1, limit: 10 }
+});
+
+// POST 请求
+const postResponse = await sdk.post('https://api.example.com/users', {
+  data: { name: 'John', email: 'john@example.com' },
+  headers: { 'Content-Type': 'application/json' }
+});
+
+// PUT 请求
+const putResponse = await sdk.put('https://api.example.com/users/1', {
+  data: { name: 'Jane' }
+});
+
+// DELETE 请求
+const deleteResponse = await sdk.delete('https://api.example.com/users/1');
+
+// PATCH 请求
+const patchResponse = await sdk.patch('https://api.example.com/users/1', {
+  data: { status: 'active' }
+});
+
+// 自定义请求
+const customResponse = await sdk.request({
+  url: 'https://api.example.com/custom',
+  method: 'POST',
+  options: {
+    data: { custom: 'data' },
+    timeout: 60,
+    proxy: 'specific-proxy.com:8080' // 使用特定代理
+  }
+});
+```
+
+## 📖 API 文档
+
+### ProxyRequestSDK
+
+主 SDK 类，提供统一的 API 接口。
+
+#### 构造函数选项
+
+```typescript
+interface SDKOptions {
+  mongoUri: string;                    // MongoDB 连接 URI（必需）
+  maxRetries?: number;                 // 最大重试次数，默认 3
+  timeout?: number;                    // 请求超时时间（秒），默认 30
+  proxyStrategy?: ProxyStrategy;       // 代理策略，默认 'sequential'
+  logLevel?: LogLevel;                 // 日志级别，默认 'info'
+  instanceId?: string;                 // 实例 ID，用于多实例场景
+  proxyCheckOptions: {                 // 代理检查配置（必需）
+    mainUrl: string;                   // 代理检查主 URL（必需）
+    testUrls?: string[];               // 额外的测试 URL
+    timeout?: number;                  // 检查超时时间（秒）
+    successStatusCodes?: number[];     // 成功状态码列表
+    checkInterval?: number;            // 检查间隔（毫秒）
+    maxConsecutiveFails?: number;      // 最大连续失败次数
+    maxResponseTime?: number;          // 最大响应时间（毫秒）
+  };
+}
+```
+
+#### 方法
+
+##### 请求方法
+
+- `get<T>(url: string, params?: Record<string, string>, options?: RequestOptions): Promise<HttpResponse<T>>`
+- `post<T>(url: string, options?: RequestOptions): Promise<HttpResponse<T>>`
+- `put<T>(url: string, options?: RequestOptions): Promise<HttpResponse<T>>`
+- `delete<T>(url: string, options?: RequestOptions): Promise<HttpResponse<T>>`
+- `patch<T>(url: string, options?: RequestOptions): Promise<HttpResponse<T>>`
+- `request<T>(config: RequestConfig): Promise<HttpResponse<T>>`
+
+##### 代理管理方法
+
+- `addProxy(proxyUrl: string): Promise<ProxyItem | null>` - 添加代理
+- `deleteProxy(proxyUrl: string): Promise<boolean>` - 删除代理
+- `getAvailableProxies(): string[]` - 获取可用代理列表
+- `getCurrentProxy(): string | null` - 获取当前使用的代理
+- `rotateProxy(): Promise<string | null>` - 轮换到下一个代理
+- `setProxyStrategy(strategy: ProxyStrategy): void` - 设置代理策略
+- `checkProxy(proxy?: string): Promise<boolean>` - 检查代理可用性
+- `triggerProxyCheck(): Promise<void>` - 触发代理检查
+- `getProxyDetails(proxyUrl: string): ProxyItem | undefined` - 获取代理详情
+
+##### 批量操作
+
+- `bulkInsertProxies(proxyUrls: string[]): Promise<number>` - 批量插入代理
+
+##### 统计信息
+
+- `getProxyStats(): Promise<ProxyStats>` - 获取代理统计信息
+- `getQueueStats(): QueueStats` - 获取队列统计信息
+
+##### 工具方法
+
+- `waitForReady(): Promise<void>` - 等待初始化完成
+- `setLogLevel(level: LogLevel): void` - 设置日志级别
+- `getLogLevel(): LogLevel` - 获取当前日志级别
+- `getInstanceId(): string` - 获取实例 ID
+- `destroy(): Promise<void>` - 清理资源
+
+### 代理策略
+
+支持三种代理选择策略：
+
+- **sequential**（顺序）：按顺序使用代理列表中的代理
+- **random**（随机）：随机选择可用代理
+- **failover**（故障转移）：当前代理失败时自动切换到下一个
+
+### 日志级别
+
+- `none` - 不记录日志
+- `error` - 仅记录错误
+- `warn` - 记录警告和错误
+- `info` - 记录信息、警告和错误（默认）
+- `debug` - 记录调试信息
+- `verbose` - 记录所有详细信息
+
+## 🔧 高级用法
+
+### 多实例场景
+
+```typescript
+import { initializeServices } from 'proxy_manager';
+
+// 创建多个独立的 SDK 实例
+const sdk1 = await initializeServices({
+  mongoUri: 'mongodb://localhost:27017/proxy_db',
+  instanceId: 'instance-1',
+  proxyCheckOptions: {
+    mainUrl: 'http://example.com/check'
+  }
+});
+
+const sdk2 = await initializeServices({
+  mongoUri: 'mongodb://localhost:27017/proxy_db',
+  instanceId: 'instance-2',
+  proxyCheckOptions: {
+    mainUrl: 'http://example.com/check'
+  }
+});
+```
+
+### 自定义代理检查
+
+```typescript
+const sdk = await createProxyRequest({
+  mongoUri: 'mongodb://localhost:27017/proxy_db',
+  proxyCheckOptions: {
+    mainUrl: 'https://httpbin.org/ip',
+    testUrls: [
+      'https://api.ipify.org?format=json',
+      'https://ipinfo.io/json'
+    ],
+    timeout: 15,
+    successStatusCodes: [200, 201],
+    checkInterval: 60000,        // 每分钟检查一次
+    maxConsecutiveFails: 3,      // 连续失败3次后标记为无效
+    maxResponseTime: 5000         // 最大响应时间5秒
+  }
+});
+```
+
+### 请求级代理指定
+
+```typescript
+// 为特定请求指定代理
+const response = await sdk.get('https://api.example.com/data', {
+  proxy: 'specific-proxy.com:8080:user:pass'
+});
+```
+
+### 代理统计信息
+
+```typescript
+const stats = await sdk.getProxyStats();
+console.log({
+  total: stats.total,           // 总代理数
+  valid: stats.valid,            // 有效代理数
+  invalid: stats.invalid,       // 无效代理数
+  available: stats.available    // 可用代理数
+});
+
+// 获取队列统计
+const queueStats = sdk.getQueueStats();
+console.log({
+  length: queueStats.length,     // 队列长度
+  running: queueStats.running,   // 运行中任务数
+  concurrency: queueStats.concurrency, // 并发数
+  idle: queueStats.idle          // 是否空闲
+});
+```
+
+### 批量插入代理
+
+```typescript
+import { bulkInsertProxyUrls } from 'proxy_manager';
+
+const count = await bulkInsertProxyUrls({
+  mongoUri: 'mongodb://localhost:27017/proxy_db',
+  proxyUrls: [
+    'proxy1.com:8080:user1:pass1',
+    'proxy2.com:8080:user2:pass2',
+    // ... 更多代理
+  ],
+  batchSize: 500,      // 每批处理500个
+  concurrency: 4,      // 并发4个批次
+  logLevel: 'info'
+});
+
+console.log(`成功插入 ${count} 个代理`);
+```
+
+## 📋 异步队列使用
+
+`AsyncQueueSingleton` 是一个强大的异步任务队列管理器，支持并发控制、优先级任务、多实例等特性。
+
+### 队列快速开始
+
+```typescript
+import { AsyncQueueSingleton } from 'proxy_manager';
+
+// 创建队列实例
+const queue = AsyncQueueSingleton.getInstance('my-queue', {
+  concurrency: 3,        // 并发数：同时执行3个任务
+  autoStart: true,      // 自动开始执行
+  logLevel: 'info',
+  onDrain: () => {
+    console.log('所有任务完成！');
+  },
+  onError: (error) => {
+    console.error('任务执行错误:', error);
+  },
+  onSuccess: (result) => {
+    console.log('任务成功:', result);
+  }
+});
+
+// 添加单个任务
+const result = await queue.add({ id: 1, name: '任务1' });
+console.log('任务结果:', result);
+
+// 批量添加任务
+const tasks = [
+  { id: 1, name: '任务1' },
+  { id: 2, name: '任务2' },
+  { id: 3, name: '任务3' }
+];
+const results = await queue.addBatch(tasks);
+console.log('批量任务结果:', results);
+```
+
+### 自定义任务处理器
+
+```typescript
+// 创建队列并设置自定义处理器
+const queue = AsyncQueueSingleton.getInstance('custom-queue', {
+  concurrency: 2,
+  logLevel: 'debug'
+});
+
+// 设置任务处理器
+queue.setTaskHandler(async (task: any) => {
+  console.log(`处理任务: ${task.name}`);
+  
+  // 模拟异步操作
+  await new Promise(resolve => setTimeout(resolve, task.duration));
+  
+  // 返回处理结果
+  return {
+    taskId: task.id,
+    status: 'completed',
+    timestamp: new Date().toISOString()
+  };
+});
+
+// 添加任务
+const result = await queue.add({ id: 1, name: '处理文件', duration: 1000 });
+console.log(result);
+```
+
+### 队列控制
+
+```typescript
+const queue = AsyncQueueSingleton.getInstance('control-queue', {
+  concurrency: 2,
+  autoStart: false  // 手动控制启动
+});
+
+// 添加任务（队列已暂停，不会立即执行）
+const promise = queue.add({ id: 1, name: '任务1' });
+
+// 暂停队列
+queue.pause();
+console.log('队列已暂停');
+
+// 恢复队列
+queue.resume();
+console.log('队列已恢复');
+
+// 等待任务完成
+const result = await promise;
+```
+
+### 优先级任务
+
+```typescript
+const queue = AsyncQueueSingleton.getInstance('priority-queue', {
+  concurrency: 2
+});
+
+// 普通任务（priority = 0，默认）
+await queue.add({ id: 1, name: '普通任务1' }, 0);
+
+// 高优先级任务（priority > 0，会插入到队列前面）
+await queue.add({ id: 2, name: '高优先级任务' }, 1);
+
+// 最高优先级任务
+await queue.add({ id: 3, name: '紧急任务' }, 2);
+```
+
+### 队列状态监控
+
+```typescript
+const queue = AsyncQueueSingleton.getInstance('monitor-queue');
+
+// 获取队列统计信息
+const stats = queue.stats;
+console.log({
+  length: stats.length,        // 队列中等待的任务数
+  running: stats.running,      // 正在执行的任务数
+  concurrency: stats.concurrency, // 并发数
+  idle: stats.idle             // 是否空闲
+});
+
+// 获取队列长度
+console.log('队列长度:', queue.length);
+
+// 获取运行中任务数
+console.log('运行中任务:', queue.running);
+
+// 检查队列是否空闲
+if (queue.idle) {
+  console.log('队列空闲，所有任务已完成');
+}
+```
+
+### 多实例队列
+
+```typescript
+// 创建不同类型的队列实例
+const imageQueue = AsyncQueueSingleton.getInstance('image-processing', {
+  concurrency: 2,
+  taskHandler: async (task) => {
+    console.log(`处理图片: ${task.filename}`);
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    return `图片处理完成: ${task.filename}`;
+  }
+});
+
+const dataQueue = AsyncQueueSingleton.getInstance('data-processing', {
+  concurrency: 5,
+  taskHandler: async (task) => {
+    console.log(`处理数据: ${task.id}`);
+    await new Promise(resolve => setTimeout(resolve, 500));
+    return `数据处理完成: ${task.id}`;
+  }
+});
+
+// 同时使用多个队列
+const [imageResults, dataResults] = await Promise.all([
+  imageQueue.addBatch(imageTasks),
+  dataQueue.addBatch(dataTasks)
+]);
+
+// 获取所有实例名称
+const instanceNames = AsyncQueueSingleton.getInstanceNames();
+console.log('所有队列实例:', instanceNames);
+
+// 获取所有实例的统计信息
+const allStats = AsyncQueueSingleton.getAllInstancesStats();
+console.log('所有队列统计:', allStats);
+```
+
+### 动态调整并发数
+
+```typescript
+const queue = AsyncQueueSingleton.getInstance('dynamic-queue', {
+  concurrency: 3
+});
+
+// 动态更新并发数
+queue.updateConcurrency(5);
+console.log('并发数已更新为:', queue.stats.concurrency);
+```
+
+### 泛型支持
+
+```typescript
+// 使用泛型指定返回类型
+interface ApiResponse {
+  endpoint: string;
+  status: string;
+  data: any;
+}
+
+const apiQueue = AsyncQueueSingleton.getInstance<ApiResponse>('api-queue', {
+  concurrency: 3
+});
+
+apiQueue.setTaskHandler(async (task: any): Promise<ApiResponse> => {
+  // 模拟API请求
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  
+  return {
+    endpoint: task.url,
+    status: 'success',
+    data: { result: 'ok' }
+  };
+});
+
+const response = await apiQueue.add({ url: '/api/users' });
+// response 的类型是 ApiResponse
+console.log(response.endpoint, response.status);
+```
+
+### 实际应用场景
+
+#### 1. API 请求限流
+
+```typescript
+const apiQueue = AsyncQueueSingleton.getInstance('api-rate-limit', {
+  concurrency: 5  // 限制同时最多5个API请求
+});
+
+apiQueue.setTaskHandler(async (apiCall: any) => {
+  const response = await fetch(apiCall.url);
+  return await response.json();
+});
+
+// 添加多个API请求，自动限流
+const results = await apiQueue.addBatch([
+  { url: 'https://api.example.com/users' },
+  { url: 'https://api.example.com/orders' },
+  { url: 'https://api.example.com/products' }
+]);
+```
+
+#### 2. 文件批量处理
+
+```typescript
+const fileQueue = AsyncQueueSingleton.getInstance('file-processing', {
+  concurrency: 2,
+  onDrain: () => console.log('所有文件处理完成')
+});
+
+fileQueue.setTaskHandler(async (file: any) => {
+  // 处理文件
+  await processFile(file);
+  return `文件 ${file.name} 处理完成`;
+});
+
+const files = [
+  { name: 'document1.pdf', size: 1024 },
+  { name: 'image1.jpg', size: 2048 }
+];
+
+const results = await fileQueue.addBatch(files);
+```
+
+#### 3. 数据库操作队列
+
+```typescript
+const dbQueue = AsyncQueueSingleton.getInstance('database-queue', {
+  concurrency: 1  // 串行执行，避免数据库锁冲突
+});
+
+dbQueue.setTaskHandler(async (operation: any) => {
+  // 执行数据库操作
+  await db.execute(operation);
+  return `操作完成: ${operation.type}`;
+});
+
+await dbQueue.add({ type: 'INSERT', table: 'users', data: {...} });
+```
+
+### 队列清理
+
+```typescript
+// 销毁指定队列实例
+AsyncQueueSingleton.destroyInstance('my-queue');
+
+// 销毁所有队列实例
+AsyncQueueSingleton.destroyAllInstances();
+```
+
+### AsyncQueue API 参考
+
+#### 静态方法
+
+- `getInstance<T>(name: string, options?: AsyncQueueOptions<T>): AsyncQueueSingleton<T>` - 获取或创建队列实例
+- `getInstanceNames(): string[]` - 获取所有实例名称
+- `getAllInstancesStats(): Record<string, QueueStats>` - 获取所有实例统计信息
+- `hasInstance(name: string): boolean` - 检查实例是否存在
+- `getExistingInstance<T>(name: string): AsyncQueueSingleton<T> | null` - 获取已存在的实例
+- `destroyInstance(name: string): void` - 销毁指定实例
+- `destroyAllInstances(): void` - 销毁所有实例
+
+#### 实例方法
+
+- `add(task: Task, priority?: number): Promise<T>` - 添加任务
+- `addBatch(tasks: Task[], priority?: number): Promise<T[]>` - 批量添加任务
+- `setTaskHandler(handler: (task: Task) => Promise<T>): void` - 设置任务处理器
+- `updateConcurrency(newConcurrency: number): void` - 更新并发数
+- `pause(): this` - 暂停队列
+- `resume(): this` - 恢复队列
+- `destroy(): void` - 销毁队列
+- `setLogLevel(level: LogLevel): void` - 设置日志级别
+- `getLogLevel(): LogLevel` - 获取日志级别
+- `getName(): string` - 获取实例名称
+
+#### 属性
+
+- `length: number` - 队列长度
+- `running: number` - 运行中任务数
+- `idle: boolean` - 是否空闲
+- `stats: QueueStats` - 队列统计信息
+
+#### 配置选项
+
+```typescript
+interface AsyncQueueOptions<T> {
+  concurrency?: number;        // 并发数，默认 100
+  autoStart?: boolean;          // 自动开始，默认 true
+  logLevel?: LogLevel;          // 日志级别
+  onDrain?: () => void;         // 队列排空回调
+  onError?: (error: Error) => void;  // 错误回调
+  onSuccess?: (result: T) => void;   // 成功回调
+  taskHandler?: (task: Task) => Promise<T>;  // 任务处理器
+}
+```
+
+## 🗄️ MongoDB 数据结构
+
+代理数据存储在 MongoDB 中，集合结构如下：
+
+```typescript
+interface ProxyDocument {
+  url: string;                    // 代理 URL（格式：host:port:username:password）
+  totalRequests: number;          // 总请求数
+  failCount: number;              // 失败次数
+  avgResponseTime: number;        // 平均响应时间（毫秒）
+  lastCheckTime: number;          // 最后检查时间（时间戳）
+  consecutiveFails: number;       // 连续失败次数
+  status: 'valid' | 'invalid';    // 状态
+  createdAt: Date;               // 创建时间
+  updatedAt: Date;               // 更新时间
+}
+```
+
+## 📝 类型定义
+
+完整的 TypeScript 类型定义已包含在包中：
+
+```typescript
+import type {
+  RequestOptions,
+  HttpResponse,
+  ProxyStrategy,
+  ProxyItem,
+  ProxyCheckOptions,
+  LogLevel
+} from 'proxy_manager';
+```
+
+## ⚠️ 注意事项
+
+1. **MongoDB 连接**：确保 MongoDB 服务正在运行且连接 URI 正确
+2. **代理格式**：代理 URL 格式为 `host:port:username:password`
+3. **初始化等待**：SDK 初始化是异步的，使用 `waitForReady()` 确保初始化完成
+4. **资源清理**：使用完毕后调用 `destroy()` 方法清理资源
+5. **并发限制**：代理检查的并发数可通过 `maxConcurrentChecks` 配置
+