Phase 1: 共享核心包 - Context

Gathered: 2026-03-21 Status: Ready for planning

## Phase Boundary

提取 crawler_core/ 为独立可安装共享包，包含签名算法、HTTP 客户端封装、基类定义和数据模型。三个平台（Boss/前程无忧/智联）的后续重写全部基于此包展开。本阶段不改造任何平台的具体爬虫实现，旧爬虫保持运行不受影响。

## Implementation Decisions

包结构和安装方式

D-01: 包放在项目根目录 crawler_core/，与 app/ 和 spiderJobs/ 平级
D-02: 使用 pyproject.toml 管理包元数据，支持 pip install -e ./crawler_core
D-03: 最小依赖范围 — 只依赖 requests_go + tenacity + Python 标准库，不拉入 FastAPI/Tortoise/loguru
D-04: 包名为 crawler_core

基类接口设计

D-05: 保持两个基类：BaseFetcher（单条详情获取）和 BaseSearcher（列表搜索）
D-06: 模板方法包含 4 个：_build_params()（必须）、_parse_response()（必须）、_build_headers()（可选覆写）、_check_blocked()（可选覆写，判断是否被封）
D-07: 返回值使用类型化 Result[T] dataclass，取代现有的松散 ApiResult

核心模块分层

D-08: 签名算法保持各平台独立类（BossSign、Job51Sign、ZhilianSign），不强制统一 BaseSigner 接口
D-09: HTTP 客户端统一封装为一个 HTTPClient 类，内置代理、重试、日志功能
D-10: 内部目录按平台分层：crawler_core/boss/、crawler_core/qcwy/、crawler_core/zhilian/ + crawler_core/base/

Claude's Discretion

pyproject.toml 的具体配置（build-system、版本号等）
Result[T] dataclass 的具体字段设计
HTTPClient 的重试策略参数（次数、间隔等）
测试文件的组织方式

## Specific Ideas

现有 spiderJobs/core/base.py（154行）比 app/services/crawler/_base.py（111行）更完整，以前者为基础提取
现有 spiderJobs/core/http_client.py 已有 TLS_CHROME_LATEST + random_ja3=True 反爬配置，直接复用
签名模块已有 6 个副本（app/services/crawler/_*_sign.py + spiderJobs/platforms/*/sign.py），内容一致，取一份即可
spiderJobs/platforms/boss/sign.py 的注释 "复制自" 已经标明了源和副本的关系

<canonical_refs>

Canonical References

架构研究

.planning/research/ARCHITECTURE.md — 共享包提取方案、同步/异步边界设计、构建顺序
.planning/research/STACK.md — HTTP 客户端选择（requests_go vs httpx）、测试栈推荐

风险规避

.planning/research/PITFALLS.md — Pitfall 1（重构期间打断在线爬虫）、Pitfall 2（签名代码复制粘贴）

现有代码

spiderJobs/core/base.py — 现有 BaseFetcher/BaseSearcher 实现，提取基础
spiderJobs/core/http_client.py — 现有 HTTPClient 实现，TLS 指纹配置
spiderJobs/platforms/boss/sign.py — Boss 签名算法参考实现
spiderJobs/platforms/job51/sign.py — Job51 签名算法参考实现
spiderJobs/platforms/zhilian/sign.py — 智联签名算法参考实现

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

spiderJobs/core/base.py — BaseFetcher/BaseSearcher 模板方法基类，直接迁移到 crawler_core/base/
spiderJobs/core/http_client.py — HTTPClient 封装，含 TLS 指纹、代理、重试逻辑
spiderJobs/platforms/*/sign.py — 三个平台的签名算法，纯函数，可直接迁移并加测试

Established Patterns

模板方法模式：基类调 _build_params() → HTTP 请求 → _parse_response()
ApiResult dataclass：success, data, error, list, is_end_page 字段
签名类独立实例化，注入到 Client/Fetcher 中

Integration Points

Phase 2/3 的平台重写将 from crawler_core.boss import BossSign, BossClient 导入
Phase 4 的后端 facade 将通过 asyncio.to_thread() 调用 crawler_core 的同步方法
现有 app/services/crawler/_*.py 文件在 Phase 4 之前保持不变，旧代码继续运行

</code_context>

## Deferred Ideas

loguru 是否应该作为 crawler_core 的可选依赖 — Phase 5 统一日志时再决定
是否需要 BaseSigner 统一接口 — 如果 Phase 2/3 发现需要，再回来加

Phase: 01-shared-core Context gathered: 2026-03-21

4.4 KiB Raw Blame History Unescape Escape