# Scarpy-sqlalchemy-Template

**Repository Path**: nobb2333/Scarpy-sqlalchemy-Template

## Basic Information

- **Project Name**: Scarpy-sqlalchemy-Template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-20
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学成在线爬虫项目

这是一个按 Scrapy 组织的可复用爬虫模板。

核心目标很直接：

- 公共能力放外层
- 每个站点项目独立放在 `xuecheng_online/spiders/<site_project>/`
- 解析阶段用 DTO
- 持久化边界用 Item
- 中间件、管道、数据库落库逻辑统一复用

## 建模模式

当前项目只保留两层：

1. DTO
   - 负责解析阶段的临时数据结构
   - 适合复杂页面、嵌套字段、拆分流程

2. Item
   - 负责持久化边界
   - 数据库管道只认 Item
   - Item 自己声明表名、字段、主键、数据库类型

### 模式 1：直接写 Item（推荐）

```python
import scrapy
from sqlalchemy import String, Text
from xuecheng_online.item_core import PersistentItem, persist_field


class CustomSchoolItem(PersistentItem):
    persist_table = "custom_school_records"

    school_id = persist_field(sa_type=String(50), primary_key=True, nullable=False)
    name = persist_field(sa_type=String(100))
    logo_url = persist_field(sa_type=Text())
    source_url = persist_field(sa_type=Text())
    DownloadImageUrl = scrapy.Field()
```

说明：

- `persist_field(...)` 用来声明数据库字段元数据
- 普通 `scrapy.Field()` 会被当成抓取过程字段，不参与数据库落库

### 模式 2：DTO -> Item（复杂页面推荐）

```python
from dataclasses import dataclass
from xuecheng_online.dto import BaseDTO


@dataclass
class SchoolDTO(BaseDTO):
    school_id: str
    name: str
    remote_logo: str


dto = SchoolDTO(
    school_id="1001",
    name="北京大学",
    remote_logo="https://example.com/logo.png",
)

item = dto.to_item(
    CustomSchoolItem,
    field_mapping={"remote_logo": "logo_url"},
)
```

说明：

- DTO 只承接解析阶段数据
- Item 才是统一的持久化对象
- 一个 DTO 可以拆成多个 Item，适合多表场景

## 功能特点

- DTO -> Item 转换
- Item-first 数据库存储
- 公共图片下载 / 文件下载 / POST 下载
- 公共请求钩子中间件
- `fake_useragent` 随机请求头
- 站点级多文件 spider 组织方式

## 环境要求

- Python 3.8+
- 数据库（可选）：
  - MySQL 5.7+
  - PostgreSQL 12+

## 安装依赖

```bash
# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt
```

## 配置说明

1. 数据库配置

   - 在 [xuecheng_online/settings.py](/Users/wong/Code/PythonLang/Scarpy-sqlalchemy-Template/xuecheng_online/settings.py) 配置 `DATABASE_URL`
   - 默认使用 SQLite

2. 爬虫配置

   - 全局公共配置放 [xuecheng_online/settings.py](/Users/wong/Code/PythonLang/Scarpy-sqlalchemy-Template/xuecheng_online/settings.py)
   - 站点项目自己的配置放各自目录，比如 [config.py](/Users/wong/Code/PythonLang/Scarpy-sqlalchemy-Template/xuecheng_online/spiders/site_shop_demo/config.py)
   - spider 里通过 `custom_settings` 只覆盖自己关心的那一小部分键

3. 中间件配置

   - `RequestHookMiddleware` 负责请求日志、计时、元数据、可选认证
   - `RandomUserAgentMiddleware` 负责随机 UA
   - `ProxyMiddleware` 负责从 `PROXY_LIST` 里选代理
   - 详细说明见 [request_hooks.md](/Users/wong/Code/PythonLang/Scarpy-sqlalchemy-Template/xuecheng_online/Docs/request_hooks.md)

4. 下载配置

   - 图片下载走 `ImagePipeline`
   - 普通 GET 文件下载走 `FilePipeline`
   - POST 下载走 `PostDownloadPipeline`
   - 详细说明见 [downloads.md](/Users/wong/Code/PythonLang/Scarpy-sqlalchemy-Template/xuecheng_online/Docs/downloads.md)

## 使用方法

1. 爬取学校信息：

```bash
scrapy crawl schools
```

2. 爬取专业信息：

```bash
scrapy crawl majors
```

3. 运行复杂电商爬虫示例：

```bash
# 产品爬虫
scrapy crawl ecommerce_products

# 分类爬虫
scrapy crawl ecommerce_categories

# 评价爬虫
scrapy crawl ecommerce_reviews

# 带参数运行
scrapy crawl ecommerce_products -a max_pages=5 -a price_min=100 -a price_max=1000

# 运行启动器
python run_spider.py
```

4. 直接双击或运行 [run_spider.py](/Users/wong/Code/PythonLang/Scarpy-sqlalchemy-Template/run_spider.py)

   - 不传参数时会弹出一个简单 GUI 选择 spider
   - 传 `-s` 时走命令行

## 数据入库规则

- 数据库管道优先读取 Item 自带的持久化元数据
- 只有 `persist_field(...)` 声明过的字段会进入数据库
- 普通 `scrapy.Field()` 会被当成临时字段自动跳过
- 如果 Item 对应的是 JSON 列，`list/dict` 会按原样写入

下载相关字段是否入库，由 Item 自己决定：

- 想落库，就声明成 `persist_field(...)`
- 只想给下载管道临时使用，就声明成普通字段或 `transient_field()`

## 项目结构

```
Scarpy-sqlalchemy-Template/
├── scrapy.cfg
├── requirements.txt
├── README.md
├── run_spider.py         # GUI / CLI 启动器
└── xuecheng_online/      # 主项目目录
    ├── __init__.py
    ├── dto.py            # DTO 基类
    ├── item_core.py      # Item-first 核心支撑
    ├── middlewares/      # 公共中间件
    ├── pipelines/        # 公共管道
    ├── settings.py       # 项目配置
    ├── Docs/             # 简化后的文档
    └── spiders/          # 站点项目集合
        ├── __init__.py
        ├── site_baidu_demo/     # 百度演示项目
        │   ├── __init__.py
        │   ├── items.py
        │   └── spider_baidu.py
        ├── site_school_demo/    # 学校/专业演示项目
        │   ├── __init__.py
        │   ├── items.py
        │   ├── spider_school.py
        │   └── spider_major.py
        └── site_shop_demo/      # 站点级多文件 spider 示例
            ├── __init__.py
            ├── spider_base.py      # 项目内部基础 spider
            ├── dto.py              # 项目内部 DTO
            ├── items.py            # 项目内部 Item
            ├── parsers.py          # 解析器模块
            ├── utils.py            # 工具函数
            ├── config.py           # 配置文件
            ├── spider_product.py   # 产品 spider
            ├── spider_category.py  # 分类 spider
            ├── spider_review.py    # 评价 spider
            └── README.md           # 模块说明
```

## 常见问题

1. 数据库连接失败

   - 检查 [settings.py](/Users/wong/Code/PythonLang/Scarpy-sqlalchemy-Template/xuecheng_online/settings.py) 里的 `DATABASE_URL`

2. 爬取速度过慢

   - 调整 `DOWNLOAD_DELAY`
   - 调整 `CONCURRENT_REQUESTS`
   - 需要时打开 `AUTOTHROTTLE`

3. 图片下载失败

   - 检查 `DownloadImageUrl`
   - 检查 `IMAGES_STORE`

4. 文件下载失败

   - 检查 `DownloadConfig` / `PostDownloadConfig`
   - 检查目标保存路径