Scrapy使用步骤(1)

Scrapy 使用步骤(1)：工程创建、目录架构解密与 Item 数据模型定义

小象实战讲义 · Python数据分析实战

在理解了 Scrapy 框架的异步事件驱动与五大核心组件之后，从本节开始，我们将按照标准的工业开发流水线，分步骤实战掌握 Scrapy 项目从 0 到 1 的完整开发过程。本节作为实战第一讲，将重点聚焦于Scrapy 环境安装与健康自检、脚手架工程创建（startproject）、标准项目目录拓扑解密，以及如何通过 Item 模块设计规范、类型安全的数据模型。

💡 核心导读

• Scrapy 依赖环境与工程初始化：
  • 安装指令与基准测试：conda install -c conda-forge scrapy / pip install scrapy；
  • 命令行脚手架：scrapy startproject <project_name>。
• Scrapy 工业级标准目录架构全解密：
  • scrapy.cfg：工程部署与配置元文件；
  • items.py：结构化数据模型（Item 模式）定义中心；
  • spiders/：爬虫业务逻辑解析核心目录；
  • pipelines.py：数据清洗、持久化与入库流水线；
  • settings.py：全局并发、延时、请求头与插件开关配置中心；
  • middlewares.py：请求/响应中间件拦截器。
• Item 数据模型设计与 scrapy.Field() 机制：
  • 为什么推荐使用 Item 替代弱约束的 Python 原生 dict 字典；
  • 结构化字段约束与元数据赋值。

1. Scrapy 环境配置与项目脚手架创建

1.1 安装与验证

在终端中执行以下命令进行安装与环境检查：

# 1. 使用 conda 或 pip 安装 scrapy
pip install scrapy

# 2. 检查安装版本与基准性能测试
scrapy version
scrapy bench

1.2 创建 Scrapy 项目

进入你希望存放爬虫工程的工作目录，执行：

scrapy startproject aqi_proj

执行后，Scrapy 会自动为你生成一套规范的工业级项目骨架。

2. Scrapy 目录架构拓扑与核心文件分工

生成的 aqi_proj 工程目录结构如下：

aqi_proj/
│
├── scrapy.cfg                # 项目的部署配置文件 (指定配置模块入口)
│
└── aqi_proj/                 # 项目的 Python 包目录 (所有业务代码均在此)
    ├── __init__.py
    ├── items.py              # 目标数据模型定义文件 (定义抓取对象的字段)
    ├── middlewares.py        # 中间件定义文件 (自定义代理、请求头等拦截逻辑)
    ├── pipelines.py          # 数据管道文件 (清洗、校验与入库持久化)
    ├── settings.py           # 全局配置文件 (并发数、User-Agent、Pipeline 优先级等)
    │
    └── spiders/              # 存放爬虫主体代码的目录
        ├── __init__.py
        └── (此处存放具体 spider.py)

核心文件职责说明：

• scrapy.cfg：整个项目的顶层配置文件，指示 Scrapy 引擎从哪个模块加载 settings；
• items.py：类似于传统 Web 开发中的 ORM Model（模型层），在这里预先定义爬虫需要收集的所有数据字段；
• settings.py：控制爬虫行为的参数中枢（如爬取延时 DOWNLOAD_DELAY、最大并发 CONCURRENT_REQUESTS 等）。

3. Python 代码实战：在 items.py 中定义结构化数据模型

在 Scrapy 中，抓取到的数据通常被封装为 Item 对象。Item 提供了类似于 Python 原生字典的 API，但相比于无约束的普通字典，Item 提供了明确的字段声明机制：如果代码中不小心拼写错了字段名（如把 city 误写为 cty），Scrapy 会立即抛出 KeyError 报错，从而将数据缺陷扼杀在萌芽期。

# 示例 1：在 items.py 中定义空气质量监控数据模型

import scrapy

class CityAqiItem(scrapy.Item):
    """
    国内城市空气质量指数 (AQI) 结构化数据模型
    """
    # 城市基本信息
    city_name = scrapy.Field()       # 城市名称 (如: "北京")
    city_url = scrapy.Field()        # 城市详情页 URL
    
    # 核心环境监控指标
    aqi = scrapy.Field()             # 空气质量指数 (AQI)
    quality_level = scrapy.Field()   # 空气质量等级 (如: "优", "良", "轻度污染")
    pm2_5 = scrapy.Field()           # PM2.5 颗粒物浓度 (μg/m³)
    pm10 = scrapy.Field()            # PM10 颗粒物浓度 (μg/m³)
    co = scrapy.Field()              # 一氧化碳浓度 (mg/m³)
    no2 = scrapy.Field()             # 二氧化氮浓度 (μg/m³)
    so2 = scrapy.Field()             # 二氧化硫浓度 (μg/m³)
    o3 = scrapy.Field()              # 臭氧 8 小时浓度 (μg/m³)
    
    # 元数据
    monitor_time = scrapy.Field()    # 监测发布时间
    crawl_time = scrapy.Field()      # 爬虫采集时间戳

print("✅ CityAqiItem 数据模型定义完毕！")

接下来，我们演示如何在 Python 中实例化、赋值、读取并转换 Item 对象：

# 示例 2：Item 对象的实例化、字典操作与安全防护演练

import datetime

# 1. 实例化 Item 并赋值
item = CityAqiItem()
item["city_name"] = "北京"
item["city_url"] = "http://www.pm25.in/beijing"
item["aqi"] = 35
item["quality_level"] = "优"
item["pm2_5"] = 12
item["crawl_time"] = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")

print("\n=== 1. 读取 Item 字段内容 ===")
print(f"• 城市: {item['city_name']}")
print(f"• AQI 指数: {item['aqi']} ({item['quality_level']})")
print(f"• PM2.5: {item['pm2_5']} μg/m³")
print(f"• 采集时间: {item['crawl_time']}")

# 2. 字段访问安全机制：尝试访问未定义的非法字段
try:
    item["invalid_column"] = "非法测试数据"
except KeyError as e:
    print(f"\n2. [安全防护触发] 成功拦截未在 Item 中声明的非法字段: {e}")

# 3. 将 Item 导出为标准 Python dict 或 JSON
item_dict = dict(item)
print("\n3. 将 Item 安全转换为字典用于落盘:")
print(item_dict)

📝 动手练一练

1. 架构思考题：在 Scrapy 项目中，为什么强烈推荐对所有业务数据字段使用 scrapy.Field() 显式声明，而不是直接在各个 Spider 中自由使用 {} 普通字典传递数据？

   👉 点击查看参考答案

   参考答案： ① 字段强约束与防手误：使用 Item 时，如果开发者因拼写手误（如 item['pricee'] = 100）写入未声明字段，系统会立即抛出 KeyError，能第一时间发现 Bug，防止脏字段悄悄流入数据库； ② 文档化与团队协作规范：items.py 本身就是一份清晰的接口契约文档，团队成员只需阅读该文件就能清晰掌握全站抓取的所有数据结构； ③ 管道流水线协同：Scrapy 的 Feed Exporters（自动导出 JSON/CSV）与 Item Loader 等高级组件依赖 Item 的字段元数据来进行字段排序与格式化。

2. 编程练习：请为你熟悉的某电商平台商品，在 items.py 中设计一个 ProductItem 类，包含商品 ID（sku_id）、商品名称（title）、原价（original_price）、促销价（sale_price）以及店铺名称（shop_name）五个字段。

   👉 点击查看参考答案

   参考答案：

   import scrapy
   
   class ProductItem(scrapy.Item):
       sku_id = scrapy.Field()          # 商品唯一编号
       title = scrapy.Field()           # 商品完整标题
       original_price = scrapy.Field()  # 商品吊牌原价
       sale_price = scrapy.Field()      # 当前促销成交价
       shop_name = scrapy.Field()       # 所属店铺名称

本章小结

在本节中，我们迈出了 Scrapy 实战开发的第一步：

• 掌握了 Scrapy 脚手架工程的创建命令 scrapy startproject；
• 系统解密了 scrapy.cfg、settings.py、items.py、pipelines.py 与 spiders/ 的目录拓扑与分工；
• 深入掌握了在 items.py 中通过 scrapy.Field() 定义结构化数据模型的标准范式与类型安全保护。

📋 行动清单

• 在本地命令行中尝试运行 scrapy startproject my_test_spider 观察生成的目录结构。
• 做好准备，进入下一小节学习《Scrapy 使用步骤(2)：编写 Spider 爬虫核心与 yield 数据流》！

—— 小象教研组