python爬虫工程化需遵循“可读、可测、可配、可扩、可查”基线，分spiders、pipelines、utils、configs、services五层解耦；配置驱动行为；内置日志、指标、追踪可观测能力；通过fixture测试、文档规范和灰度升级保障可维护性。
Python爬虫项目一旦脱离脚本阶段，进入团队协作或长期维护，结构混乱、逻辑耦合、配置分散、日志缺失等问题会迅速暴露。工程化不是堆砌框架，而是围绕“可读、可测、可配、可扩、可查”建立稳定基线。
核心模块分层：按职责切分，禁止交叉污染
一个健壮的爬虫项目应明确划分为五层，每层只依赖下层，禁止反向调用：
- spiders/：仅存放 Spider 类，负责 URL 调度、页面解析、Item 提取；不写业务逻辑、不操作数据库、不处理异常重试策略
- pipelines/：仅处理 Item 流水线，如去重、清洗、字段标准化、存入 MySQL/Elasticsearch；每个 Pipeline 单一职责，用 settings 控制启停
- utils/：封装通用能力，如 UA 池、代理中间件基类、验证码识别适配器、时间工具、加解密函数；避免在 spider 中直接 import requests 或写正则提取逻辑
- configs/：分离环境配置（dev.yml / prod.yml），用 PyYAML + dataclass 加载；敏感信息（如数据库密码）通过环境变量注入，不硬编码、不提交到 Git
- services/：承载跨模块业务逻辑，如任务分发中心、增量抓取状态管理、通知服务（钉钉/邮件）、监控上报；与 Scrapy 核心解耦，便于单元测试
配置驱动开发：让爬虫行为由配置决定，而非代码修改
把易变项全部外置，运行时加载，无需改代码即可调整行为：
- 每个 spider 对应独立配置片段（如 spiders/weibo/config.yaml），定义 start_urls、allowed_domains、crawl_delay、retry_times、parse_rules（CSS/XPath 规则表）
- 使用 scrapy-poetry 或自研 loader 统一解析配置，支持继承（base → weibo → weibo_hot）和环境覆盖（prod 降低并发，dev 启用 debug 日志）
- 动态字段映射：用配置声明「原始字段名 → 标准字段名 → 类型转换函数」，例如
{'pub_time_str': {'to': 'publish_time', 'cast': 'datetime: %Y-%m-%d %H:%M'}}
可观测性落地：日志、指标、追踪三者闭环
没有监控的爬虫等于定时失联。工程化必须默认内置可观测能力：
立即学习“Python免费学习笔记（深入）”；
- 日志分级清晰：DEBUG 记录请求/响应体（脱敏后）、INFO 记录成功抓取数/跳过数、WARNING 记录重试超限/字段缺失、ERROR 记录不可恢复异常；日志格式统一含 spider_name、task_id、url_hash
- 暴露 Prometheus 指标端点：累计请求数、HTTP 状态码分布、平均响应时间、Pipeline 处理耗时、去重率；用 scrapy-prometheus 或轻量 HTTP server 实现
- 关键链路打 trace_id：从 scheduler 发起请求开始，贯穿 downloader、spider、pipeline，最终落库时写入 trace_id 字段，便于问题定位
可维护性保障：测试、文档、升级路径缺一不可
维护成本常来自“不敢动”，解决它靠三件事：
- 为每个 spider 写 fixture 测试：用本地 HTML 文件模拟响应，验证 parse 方法输出是否符合 Item 定义；用 pytest + responses mock 请求，覆盖重试、重定向、403 处理等分支
- README.md 必须包含：快速启动命令、配置项说明表（key/类型/默认值/用途）、数据字典（字段名、含义、示例值、是否为空）、常见报错速查（如 status=503 怎么调参）
- 版本升级有兜底：当目标网站结构调整，旧解析规则失效时，允许并行运行新旧两个 spider 分支，用配置开关控制流量比例，验证稳定后再下线旧版
