Package Exports
- @youpaichris/requests
- @youpaichris/requests/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@youpaichris/requests) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
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): 代理服务器 URLtimeout(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): 是否禁用自动重定向，默认 falseinsecureSkipVerify(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 (10512@qq.com)