requests

一个类似 Python requests 的 Node.js HTTP 客户端库，基于 CycleTLS 构建，提供自动 cookie 管理和 TLS 指纹伪装功能。

特性

• 🍪 自动 Cookie 管理：自动处理 Set-Cookie 头并在后续请求中发送
• 🔄 智能重定向处理：手动处理重定向以确保 Cookie 在重定向间正确传递
• 🎭 TLS 指纹伪装：通过 CycleTLS 支持自定义 JA3 指纹
• 🌐 代理支持：内置 HTTP/HTTPS/SOCKS 代理支持
• 📦 Session 持久化：在多个请求间保持会话状态
• 🛠️ 灵活配置：支持自定义 headers、超时、User-Agent 等

安装

npm install @youpaichris/requests

快速开始

单次请求（无状态）

类似 Python 的 requests.get()，每次请求独立，不保存 cookies 或会话状态：

const requests = require('@youpaichris/requests');

// 简单的 GET 请求
const response = await requests.get('https://httpbin.org/get');
console.log(response.status);
console.log(await response.json());

// POST 请求
const postResponse = await requests.post('https://httpbin.org/post', {
    body: JSON.stringify({ key: 'value' }),
    headers: {
        'Content-Type': 'application/json'
    }
});
console.log(await postResponse.json());

Session 会话（有状态）

类似 Python 的 requests.Session()，自动管理 cookies 和默认配置：

const { Session } = require('@youpaichris/requests');

async function example() {
    // 创建 session 实例
    const session = new Session({
        headers: {
            'Accept': 'application/json',
            'Accept-Language': 'zh-CN,zh;q=0.9'
        }
    });

    // 发送请求，cookies 会自动保存和发送
    const response = await session.get('https://httpbin.org/cookies/set?test=value');
    const response2 = await session.get('https://httpbin.org/cookies');
    console.log(await response2.json()); // 会包含之前设置的 cookie
    
    // Session 会在进程退出时自动清理
    // 也可以手动调用 await session.close()
}

example();

API 文档

单次请求 API（无状态）

这些方法每次请求都是独立的，不保存 cookies 或会话状态，请求完成后自动释放资源。

const requests = require('@youpaichris/requests');

// GET 请求
await requests.get(url, options);

// POST 请求
await requests.post(url, options);

// PUT 请求
await requests.put(url, options);

// DELETE 请求
await requests.delete(url, options);

// PATCH 请求
await requests.patch(url, options);

// HEAD 请求
await requests.head(url, options);

// OPTIONS 请求
await requests.options(url, options);

// 通用请求方法
await requests.request(method, url, options);

options 参数：

• headers (Object): 请求头
• body 或 data (String): 请求体
• ja3 (String): TLS JA3 指纹
• userAgent (String): User-Agent 字符串
• proxy (String): 代理服务器 URL
• timeout (Number): 超时时间（秒）
• disableRedirect (Boolean): 是否禁用重定向
• insecureSkipVerify (Boolean): 是否跳过 SSL 验证

创建 Session（有状态）

const session = new Session(options);

options 参数：

• headers (Object): 默认请求头
• ja3 (String): TLS JA3 指纹
• userAgent (String): User-Agent 字符串
• proxy (String): 代理服务器 URL（如：http://127.0.0.1:8080）
• timeout (Number): 请求超时时间（秒），默认 7 秒
• disableRedirect (Boolean): 是否禁用自动重定向，默认 false
• insecureSkipVerify (Boolean): 是否跳过 SSL 证书验证，默认 false

HTTP 方法

所有方法返回 Promise，响应对象包含 status、headers、body 等属性。

// GET 请求
await session.get(url, options);

// POST 请求
await session.post(url, options);

// PUT 请求
await session.put(url, options);

// DELETE 请求
await session.delete(url, options);

// PATCH 请求
await session.patch(url, options);

// HEAD 请求
await session.head(url, options);

// OPTIONS 请求
await session.options(url, options);

Cookie 管理

// 手动设置 cookie
await session.setCookie('name=value; Domain=example.com', 'https://example.com');

// 获取指定 URL 的 cookies
const cookies = await session.getCookies('https://example.com');

// 获取 cookie 字符串（用于请求头）
const cookieString = await session.getCookieString('https://example.com');

// 清空所有 cookies
session.clearCookies();

配置更新

// 更新默认 headers
session.updateHeaders({ 'X-Custom-Header': 'value' });

// 更新代理
session.updateProxy('http://new-proxy:8080');

// 更新 User-Agent
session.updateUserAgent('CustomBot/2.0');

// 更新 JA3 指纹
session.updateJA3('新的JA3字符串');

资源管理

由于 Node.js 的事件循环机制，Session 需要正确关闭才能让进程退出。有以下几种方式：

方式一：使用 run 工具函数（推荐）

const { Session, run } = require('@youpaichris/requests');

// 使用 run 包装，自动管理生命周期
run(async () => {
    const session = new Session();
    const response = await session.get('https://httpbin.org/get');
    console.log(response.status);
    // 无需手动 close，run 会自动处理
});

方式二：手动关闭

const session = new Session();
await session.get('https://httpbin.org/get');
await session.close();  // 手动关闭

方式三：关闭所有 Session

const { closeAllSessions } = require('@youpaichris/requests');

// 在脚本结束时
await closeAllSessions();

方式四：禁用自动等待（让进程自然退出）

// 通过环境变量禁用
process.env.REQUESTS_NO_AUTO_CLOSE = 'true';

// 或者在创建时禁用
const session = new Session({ autoClose: false });

高级用法

使用代理

const session = new Session({
    proxy: 'http://username:password@proxy-server:8080'
});

自定义 TLS 指纹

const session = new Session({
    ja3: '771,4865-4867-4866-49195-49199-52393-52392-49196-49200-49162-49161-49171-49172-51-57-47-53-10,0-23-65281-10-11-35-16-5-51-43-13-45-28-21,29-23-24-25-256-257,0'
});

处理重定向

库默认自动处理重定向并保持 cookies。如需手动处理：

const session = new Session({
    disableRedirect: true  // 禁用自动重定向
});

const response = await session.get('https://example.com/redirect');
if (response.status >= 300 && response.status < 400) {
    const location = response.headers.Location;
    // 手动处理重定向
}

架构说明

核心依赖

• CycleTLS: 提供 TLS 指纹伪装和高级 HTTP 客户端功能
• tough-cookie: RFC 6265 兼容的 cookie 管理

关键实现细节

Cookie 处理流程

• 自动存储响应中的 Set-Cookie 头到 cookieJar
• 每个请求自动包含相关 cookies
• 包含降级解析器处理非标准 cookies
• 禁用公共后缀检查以避免误判

重定向处理

• 手动实现重定向跟随，因为 CycleTLS 的自动重定向不会保持 cookies
• 遵循 HTTP 标准：POST 请求在 301/302 重定向时转换为 GET
• 支持绝对和相对 Location 头
• 默认最大重定向次数为 10

资源管理

• 单次请求方法（如 requests.get()）会在请求完成后自动清理
• Session 需要显式关闭或使用 run() 工具函数来管理生命周期
• 提供多种资源管理方式适应不同场景

开发指南

运行测试

node tests/test.js

注意：测试脚本需要代理服务器运行在 http://127.0.0.1:9090。

调试 Cookie 问题

• 查看控制台输出了解 cookie 设置成功/失败信息
• 使用 session.getCookieString(url) 检查特定 URL 的 cookies
• 降级解析器会在标准解析失败时记录详细信息

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

作者

Chris ([email protected])