xhshow项目架构拆解：core/generators/utils模块化设计，看懂签名库代码结构

• 后端
• 网页爬虫

xhshow 是一个小红书纯算签名库，用纯 Python 实现x-s、x-s-common、x-rap-param等请求头的生成，不依赖浏览器环境。对很多想读懂逆向代码的新手来说，这类项目最容易看懵——算法、指纹、编码混在一起，入口在哪、谁调谁都理不清。本文带你用 5 分钟看懂 xhshow 的模块化架构：core管加密、generators管指纹、utils管工具，一层层剥开它的代码结构。🧩

一、先看全局：xhshow 的目录结构

xhshow 的源码全部位于 src/xhshow/ 下，采用经典的「入口 → 算法 → 支撑 → 工具」四层结构：

src/xhshow/ ├── client.py # 公共入口：Xhshow 客户端（对外 API 全在这里） ├── session.py # 会话管理：SessionManager 有状态签名 ├── config/ │ └── config.py # CryptoConfig：全局冻结配置（密钥、模板、常量） ├── core/ # 算法层：每种签名一条独立流水线 │ ├── crypto.py # x-s 主算法：144 字节 payload + 自定义哈希 │ ├── common_sign.py # x-s-common 签名 │ ├── xrap.py # x-rap-param 风控头（SM4 变体加密） │ ├── xyw_crypto.py # XYW_ 签名（AES-128-CBC） │ └── crc32_encrypt.py # JS 风格 CRC32 ├── generators/ # 指纹层：模拟浏览器环境 │ ├── fingerprint.py # 90+ 字段的浏览器指纹生成 │ └── fingerprint_helpers.py ├── data/ │ └── fingerprint_data.py # 指纹选项表（分辨率、插件、字体等） └── utils/ # 工具层：无状态纯函数/小类 ├── bit_ops.py # XOR 变换、32 位整型处理 ├── encoder.py # 自定义 Base64 字母表编解码 ├── hash.py # xxh32 哈希 ├── hex_utils.py # 十六进制处理 ├── random_gen.py # a1 / web_id / trace_id 生成 ├── sharding.py # xy-direction 分片键 ├── url_utils.py # URL 构建与 URI 提取 └── validators.py # 参数校验装饰器

新手读逆向代码库，第一步永远是先建立「谁是谁」的地图。xhshow 的命名非常直观：目录名就是职责，这是它最值得学习的设计习惯。

二、入口层：一个类搞定所有签名

对外的公共 API 只有一个类——client.py 中的Xhshow。包级init.py 只导出了 5 个名字：Xhshow、CryptoConfig、CryptoProcessor、SessionManager、SignState，边界收得很干净。

Xhshow类内部的方法可以分成三组：

它的构造函数做了两件关键的事：

1. 把config传给 CryptoProcessor，让算法层拿到密钥与模板；
2. 初始化 RandomGenerator，供随机值生成使用。

也就是说：入口层自己几乎不写算法，只做编排——这是模块化设计的核心思想，后面会反复出现。

三、算法层 core/：每条签名一条独立流水线

core/目录是 xhshow 的心脏，里面每个文件对应一种签名的完整算法，彼此互不干扰：

1. x-s 主算法：crypto.py

x-s 的生成路径是：

1. 把 URI + 参数拼成 content string，算出 MD5（d值）；
2. CryptoProcessor.build_payload_array 构造144 字节的 payload 数组：版本字节、随机种子、时间戳、a1、appid、环境表，以及由 _custom_hash_v2 计算出的 16 字节摘要（带 4 组初始向量与循环移位）；
3. BitOperations.xor_transform_array 用 144 字节的 HEX 密钥做 XOR 变换；
4. Base64Encoder.encode_x3 用自定义 Base64 字母表编码，得到mns0301_前缀的 x3。

2. x-s-common：common_sign.py

XsCommonSigner.sign 的链路更"社交化"——它不是纯加密，而是模拟浏览器上报：

• 由 FingerprintGenerator 生成包含 User-Agent、屏幕分辨率、WebGL/Canvas 哈希等90 多个字段的指纹字典；
• generate_b1 把其中 18 个关键字段用 ARC4 加密 + URL 编码，产出 b1 值；
• CRC32.crc32_js_int 计算 JS 风格的 CRC32 作为 x9 校验位；
• 最终填入 SIGNATURE_XSCOMMON_TEMPLATE 模板，JSON 化后自定义 Base64 输出。

3. x-rap-param：xrap.py

x_rap_param 是三条流水线里最复杂的一条，feed、搜索、笔记发布接口依赖它：

1. _build_body_structure 用 TLV 格式（tag-length-value）拼装含时间戳、随机数、会话密钥、xxh32 哈希和"环境快照"的二进制体；
2. _compress_body 做 gzip 压缩（并修补 OS 字节以匹配浏览器运行环境）；
3. _pack_envelope 依次做循环 XOR、SM4 变体分组加密（自定义 S 盒 + 预展开轮密钥 + T 表加速）、拼接信封头，最后 Base64 输出。

4. XYW 签名：xyw_crypto.py

XywCipher 是一套纯 Python 手写的AES-128-CBC（S 盒、RCON、列混合一应俱全），build_xyw_payload_hex 负责把 URI、a1、时间戳打包加密。它服务于对XYS_格式返回 406 的数据类接口，与 x-s 完全独立的第二加密路径。

四、指纹层 generators/ + data/：把"环境"从算法里剥离

如果算法层是"怎么加密"，那指纹层回答的是"在什么环境下"。

FingerprintGenerator.generate 会拼出一个近乎完整的浏览器画像：UA、语言、色深、设备内存、GPU 厂商/渲染器、Canvas 哈希、WebGL 哈希、时区、字体……其中随机选项来自 fingerprint_data.py 的加权选项表（比如屏幕分辨率按真实分布概率加权抽取），配合 fingerprint_helpers.py 的辅助函数完成。

这种拆分的好处在新手学习时非常直观：

• 想改"环境仿真"→ 只动generators/和data/；
• 想改"加密逻辑"→ 只动core/；
• 两边互不污染，测试也好写（见文末tests/与模块的一一对应）。

五、工具层 utils/：小而纯，随处复用

utils/里的模块都是无状态的小零件，被core/反复组合使用：

一个值得注意的细节：validators用装饰器把参数校验前置到每个公共方法上（如@validate_signature_params），让入口层的签名函数保持"先检查、后计算"的一致节奏——这是 Python 项目里很实用的防御式编程范式。

六、配置层 config/：一处改，全局生效

CryptoConfig 是一个frozen=True的 dataclass，把散落在各算法里的密钥、字母表、模板、随机区间全部集中管理：

• HEX_KEY（144 字节 XOR 密钥）、三套 Base64 字母表；
• SIGNATURE_DATA_TEMPLATE/SIGNATURE_XSCOMMON_TEMPLATE签名 JSON 模板；
• XYW_AES_KEY/XYW_AES_IV、B1_SECRET_KEY等各流水线密钥；
• 序列号、窗口长度等随机区间。

各模块构造时接收 config 实例（依赖注入），而 with_overrides 方法支持replace生成覆盖副本，不改原对象即可自定义参数：

config = CryptoConfig().with_overrides( SEQUENCE_VALUE_MIN=20, SEQUENCE_VALUE_MAX=60, )

冻结 dataclass 保证配置不可变，避免了"某处偷偷改了密钥"的经典 bug。

七、有状态签名：session.py 的角色

SessionManager 是少数跨请求持有状态的组件：它维护页面加载时间戳、单调递增的序列号和窗口属性长度，模拟真实用户在同一页面的连续操作。

• 无 session 时，build_payload_array 每次随机填充这几个字段；
• 传入 session 时，则从 SignState（不可变 NamedTuple）读取"演进中的"状态值。

多账户场景下每个账户各建一个SessionManager即可，互不串号。

八、新手阅读路线：从 tests/ 反查模块

xhshow 的 tests/ 目录和源码模块一一对应，是理解代码的绝佳起点：

• test_crypto.py → 对照core/crypto.py的 payload 构造；
• test_xrap.py → 对照core/xrap.py的 TLV/压缩/封装流程；
• test_session.py → 对照session.py的状态演进；
• test_cookie_parsing.py、test_public_api.py → 对照入口层的参数解析与对外行为；
• test_url_utils.py → 对照utils/url_utils.py。

建议路线：client.py 入口 → 挑一条签名流水线（推荐 x-s）→ 沿途的 utils → 最后看 core 里另外两条流水线。配置项不懂时直接翻 config.py 查模板和密钥即可。

总结

xhshow 的架构可以浓缩成一句话：入口只编排，算法各管一段，环境仿真独立，工具纯函数化，配置集中注入。

掌握这套"分层 + 目录即职责"的阅读方法，再看任何逆向/签名类项目，都能先画出自己的模块地图。🚀

• 后端
• 网页爬虫