1.3 项目结构与命令行工具

1.3 项目结构与命令行工具

本节摘要：Scrapy 工程的目录结构不是习惯问题，而是框架装载组件的依据——引擎按固定入口查找爬虫、管道、中间件与配置。本节带你生成一个标准工程，逐个说清每个模块在双程旅程里的岗位，并把日常高频的命令行操作一次配齐。

环境通了，这一节把车间的房间隔出来。第 1 章的最后一个问题——"怎么从零搭起一个可运行的工程"——在这里收口。读完它，第 2 章写 Spider 时你就知道每行代码该落在哪个文件。

生成工程：一条命令隔出所有房间

scrapy startproject bookstation
cd bookstation
scrapy genspider books books.example.com
# Created spider 'books' using template 'basic' in module:
#   bookstation.spiders.books
​

genspider 第二个参数是允许抓取的域名，框架会据此生成 allowed_domains 初始值。生成完的工程长这样：

bookstation/
    scrapy.cfg                # 部署入口配置：指明默认工程设置模块
    bookstation/
        __init__.py
        items.py              # 数据模型：定义 Item 有哪些字段
        middlewares.py        # 中间件：去程与回程关卡的自定义逻辑
        pipelines.py          # 管道：Item 回程的清洗与入库
        settings.py           # 全局配置：全册最重要参数的集中地
        spiders/
            __init__.py
            books.py          # Spider：车票的出生地
​

图3 标准工程的岗位分布：文件与双程旅程的对应

记住一个判断规则：你写的类几乎都能从文件名猜出岗位。要加数据字段进 items 模型；要拦请求进中间件；要洗数据进管道；要调行为进 settings。框架按 settings 里的清单去对应模块装载组件，这就是"结构即装配依据"的含义。

组件如何被装配：settings 是总花名册

打开 settings，你会看到被注释掉的管道与中间件清单。取消注释即启用，数字是执行顺序：

# settings 配置模块中的装配清单（节选）
ITEM_PIPELINES = {
    "bookstation.pipelines.CleanPipeline": 100,    # 数字小的先执行
    "bookstation.pipelines.DbPipeline": 300,
}

DOWNLOADER_MIDDLEWARES = {
    "bookstation.middlewares.RotateUA": 543,       # 543 在默认中间件之后
}

SPIDER_MIDDLEWARES = {
    "bookstation.middlewares.DedupResult": 500,    # 蜘蛛中间件同样有序
}
​

数字排序的规则值得记牢：下载器中间件里数字小靠引擎侧、大靠下载器侧，去程先过小号关卡、回程先过大号关卡。理解这一点，第 4 章的中间件顺序问题就迎刃而解。

案例展开：从生成到首跑的完整十分钟

把前三节的知识串成一次真实操作，这是你接下来就要做的事。背景：为站点 books.example.com 搭一个列表加详情的采集工程。

scrapy startproject bookstation
cd bookstation
scrapy genspider books books.example.com
scrapy list
# books                      ← 工程自检通过
scrapy shell "https://books.example.com/list"
# ...交互终端里调通两个选择器...
​

操作到结果的全过程：生成工程约两秒；shell 里先确认 response.css("h3 a::attr(title)").getall() 出数据、再确认翻页地址的取法；把选择器填进 Spider 的解析回调；首跑加保险丝限两百页：

scrapy crawl books -s CLOSESPIDER_PAGECOUNT=200 -o trial.jsonl
​

结果核验看三处：统计里 item_scraped_count 与页面条数对得上；finish_reason: finished 说明自然跑完；输出的 trial.jsonl 抽样看字段完整。解读：三处全绿，说明车间的出票、拆包、产出的最小闭环成立；哪一处不对，按 1.1 节的双程动线定位是哪一站的事。

变式一：站点要按分类分别统计时，生成第二个爬虫（scrapy genspider books_fiction），共享工程配置但各管各的起始地址——同一工程多爬虫是常态，scrapy list 管名册。变式二：验收别人交付的工程，不读代码先跑三条命令：scrapy list 看名册、scrapy crawl 名字 -s CLOSESPIDER_PAGECOUNT=20 试跑、翻启动日志的装配清单核对组件——十行代码不看也能判断工程是否装配合规。

命令行工具速查：日常操作全在这

Scrapy 的命令分两类：全局命令（工程外可用）与项目命令（须在工程目录内跑）。

scrapy list                      # 列出本工程全部爬虫
# books
scrapy crawl books               # 正式运行：车票开始发行
scrapy crawl books -o out.json   # 运行并把 Item 导出到文件
scrapy parse "https://books.example.com/book/1" --spider books
# 快速验证单页解析逻辑，不用整程跑
scrapy shell "https://books.example.com/list"
# 进入交互终端：现场试验选择器，第2章的主力调试工具
scrapy runspider single.py       # 工程外直接跑一个独立爬虫文件
​

scrapy shell 值得单独强调：它是"到站拆包"的试验台。你在写解析代码前，先在这里把选择器调通，再粘回 Spider，能省掉大量整程重跑。一个典型会话：

>>> response.status
200
>>> response.css("h1::text").get()
'All products'
>>> response.xpath("//div[@class='price']/text()").getall()
['£51.77', '£23.19']
​

命令行还有一个隐性职责：crawl 启动时会打印装配报告——启用了哪些中间件、管道、扩展，顺序如何。出问题时先看这份报告，很多"我明明配置了却没生效"的疑案，答案就在装配清单里。

💡 关键直觉：把 scrapy list 与 crawl 的启动日志当成体检报告读，工程哪里装错了件，它比报错栈更早告诉你。

本节要点回顾

• 结构即装配：框架按固定入口装载组件，文件放错位置等于没写；
• 五个模块五类岗：spiders 出票、items 建模、middlewares 设卡、pipelines 洗货、settings 总控；
• 装配数字管顺序：管道数字小的先跑，中间件数字决定靠引擎侧还是下载器侧；
• parse 与 shell 是左膀右臂：单页验证与选择器试验，别用整程爬取做调试。

第 1 章到此收尾。下一章进 Spider 车间——写下第一段真正属于你的旅程代码。