客户端配置¶

x-api-rs 是 SDK，HTTP/性能/可用性相关参数都通过 RquestClientBuilder 暴露给上层使用方。本文档列出所有可配置项的默认值、风险、何时该改。

设计原则¶

安全默认 + 可覆盖：默认值对非幂等写操作（DM/Posts/Like/上传）安全，高级用户可通过 builder 覆盖
协议常量不暴露：与 Twitter API 协议绑定的常量（如 MAX_MESSAGE_LENGTH = 10000、GraphQL queryId、Bearer Token）写死在 SDK 内，不可配置
传输/性能参数暴露：timeout、retry、proxy、pool size、JA3 指纹等可调

配置项参考¶

`http2_max_retry_count: usize` 🔴¶

HTTP/2 自动重试次数。控制 rquest 在收到 RST_STREAM(REFUSED_STREAM) 或 GOAWAY(NO_ERROR) 时是否自动重发请求。

项目	值
本 SDK 默认	`0`（禁用）
rquest 原始默认	`2`
风险等级	🔴 高（影响数据正确性）

为什么默认禁用：

rquest 把 H2 REFUSED_STREAM 视为"请求未到达 server"自动重发（RFC 9113 §8.7-3.2）。但 Twitter 在限流时会先处理请求再发 RST_STREAM——server 已经收到并执行了请求， rquest 仍重发，导致同一条 DM/Tweet 被发送 2 次。

200 并发 DM 场景实测：11-19 条消息出现重复（5.5%-9.5% 重复率）。

何时可以改成 >0：

✅ 客户端只用于幂等读操作：搜索、获取用户资料、获取 timeline、获取私信列表
❌ 绝对不能用于：DM 发送、发帖、点赞、转发、关注、上传——任何写操作

如果同一个客户端实例会混用读写，保留默认 0。

用法：

use x_api_rs::{RquestClientBuilder, CookieAuth, ClientTransaction};
use std::sync::Arc;

// ✅ 安全默认（推荐）
let client = RquestClientBuilder::new(auth, transaction).build()?;

// ⚠️ 仅在纯读场景下可考虑
let client = RquestClientBuilder::new(auth, transaction)
    .http2_max_retry_count(2)
    .build()?;

`proxy_url: Option<String>`¶

代理服务器 URL，支持 HTTP / HTTPS / SOCKS5。

项目	值
默认	`None`（直连）
风险等级	🟢 低

已知陷阱：

Burp Suite 会破坏 JA3 指纹模拟（TLS MITM 终止连接）→ 触发 Twitter 226 反爬
大文件 multipart 上传 (>~100KB) 通过 Burp 会失败：Stream failed to close correctly
测试场景建议使用 mitmproxy 或直连

用法：

RquestClientBuilder::new(auth, transaction)
    .proxy_url("http://127.0.0.1:8080".to_string())
    .build()?;

`enable_ja3: bool`¶

是否启用 JA3/TLS 指纹模拟（Chrome 136）。

项目	值
默认	`true`
风险等级	🟡 中（关闭后反爬触发率显著上升）

用法：

RquestClientBuilder::new(auth, transaction)
    .enable_ja3(false)  // 仅在调试场景关闭
    .build()?;

`fingerprint: Option<BrowserFingerprint>`¶

自定义浏览器指纹（Sec-CH-UA 系列头部 + User-Agent）。

项目	值
默认	随机生成（Chrome 144 浏览器版本池）
风险等级	🟢 低

用法：

use x_api_rs::common::fingerprint;

let fp = fingerprint::random_fingerprint();
RquestClientBuilder::new(auth, transaction)
    .fingerprint(fp)
    .build()?;

完整示例¶

use x_api_rs::{
    Twitter, CookieAuth, ClientTransaction, RquestClientBuilder,
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123";

    // 1. 解析 cookies
    let auth = Arc::new(CookieAuth::parse(cookies.to_string())?);

    // 2. 异步创建 ClientTransaction
    let transaction = ClientTransaction::create(None, None).await?;

    // 3. 显式配置 RquestClient
    let client = RquestClientBuilder::new(auth.clone(), transaction)
        .enable_ja3(true)             // 启用 JA3（默认）
        .http2_max_retry_count(0)     // 禁用 H2 重试（默认，DM 场景必须）
        // .proxy_url("http://...".to_string())  // 可选代理
        .build()?;

    // 4. 创建 Twitter 客户端
    let twitter = Twitter::with_client(cookies.to_string(), Arc::new(client))?;

    Ok(())
}

如果不需要自定义任何配置，直接用 Twitter::create 即可（内部使用安全默认）：

let twitter = Twitter::create(cookies.to_string(), None, true).await?;

Python 用户¶

Python 绑定通过 Twitter.create 暴露常用配置。当前可配置项：

import x_api_rs

# 基础用法（默认安全配置）
client = await x_api_rs.Twitter.create(cookies)

# 带代理
client = await x_api_rs.Twitter.create(cookies, proxy_url="http://127.0.0.1:8080")

# 关闭 JA3（仅调试用）
client = await x_api_rs.Twitter.create(cookies, enable_ja3=False)

http2_max_retry_count 当前未在 Python 层暴露——因为 Python 用户场景几乎都涉及写操作，强制使用安全默认（0）。如需读专用客户端，请联系 issue 反馈。

历史¶

2026-05-09：发现 rquest 默认 http2_max_retry_count=2 导致 DM 重复发送，本 SDK 默认改为 0，并通过 RquestClientBuilder::http2_max_retry_count 暴露为可配置（v1.0.15）

客户端配置¶

设计原则¶

配置项参考¶

http2_max_retry_count: usize 🔴¶

proxy_url: Option<String>¶

enable_ja3: bool¶

fingerprint: Option<BrowserFingerprint>¶