scrapy-go

module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 18, 2026 License: MIT

README

🕷️ scrapy-go

Go Version Version

scrapy-go 是一个用 Go 语言实现的高性能异步爬虫框架，架构设计对齐 Python Scrapy，在保留 Scrapy 核心设计理念的同时，充分利用 Go 的并发模型和类型安全特性，提供更高的运行效率和更低的资源消耗。

✨ 核心特性

  • 🔗 Scrapy 兼容架构 — Engine → Scheduler → Downloader → Scraper 经典数据流，零成本迁移
  • ⚡ 高性能并发 — goroutine + channel 原生并发，HTTP/2 多路复用，~18,900 req/s
  • 🧩 可扩展中间件 — 11 个下载器中间件 + 5 个 Spider 中间件，支持 AutoThrottle、高级重试等
  • 🔍 内置选择器 — goquery（CSS）+ htmlquery（XPath）链式 API，CrawlSpider 规则化爬取
  • 💾 断点续爬 — 磁盘队列 + 持久化去重 + 内存溢出保护，中断后自动恢复
  • 📤 数据导出 — Feed Export（JSON/CSV/XML）+ MongoDB/PostgreSQL/ES 批量写入
  • 🌐 分布式支持 — Redis 队列 + 布隆过滤器 + 滑动窗口限速 + Web 管理 API
  • 📊 可观测性 — OpenTelemetry 追踪 + Prometheus 指标
  • 🛡️ 类型安全配置 — 泛型 Key[T] + Get[T] API，编译期类型检查，消除魔法字符串

📊 性能数据

指标 结果 说明
QPS（16 并发） ~18,900 req/s 本地服务器，最小响应
堆内存（10 万请求） ~12 MB 实际数据占用
每请求分配 ~9.4 KB 含 Request/Response/网络缓冲
vs Colly ~2.5x QPS 保留完整中间件栈
vs Geziyor ~2.0x QPS 保留完整中间件栈

🚀 快速开始

安装
go get github.com/dplcz/scrapy-go

📋 要求：Go 1.25.1+

脚手架工具
go install github.com/dplcz/scrapy-go/cmd/scrapy-go@latest

scrapy-go startproject myproject && cd myproject
scrapy-go genspider quotes quotes.toscrape.com
最简示例
package main

import (
    "context"
    "fmt"

    "github.com/dplcz/scrapy-go/pkg/crawler"
    shttp "github.com/dplcz/scrapy-go/pkg/http"
    "github.com/dplcz/scrapy-go/pkg/spider"
)

type MySpider struct {
    spider.Base
}

func NewMySpider() *MySpider {
    return &MySpider{
        Base: spider.Base{
            SpiderName: "my_spider",
            StartURLs:  []string{"https://example.com"},
        },
    }
}

func (s *MySpider) Parse(ctx context.Context, response *shttp.Response) ([]spider.Output, error) {
    title := response.CSS("title::text").Get()
    fmt.Printf("Title: %s\n", title)
    return nil, nil
}

func main() {
    c := crawler.NewDefault()
    c.Run(context.Background(), NewMySpider())
}

📖 更多示例（Pipeline、中间件、Feed Export 等）请查看 完整参考文档

🏗️ 架构概览

Engine (调度引擎)
├── Scheduler (请求调度 + 去重 + 优先级队列)
│   └── [可选] contrib/redisqueue (Redis 分布式队列)
├── Downloader (HTTP 下载 + Slot 并发控制)
│   ├── HTTP/1.1 & HTTP/2 下载处理器 (ALPN 自动协商 + h2c 可选)
│   └── Middleware Chain (11 个内置中间件)
└── Scraper (响应处理 + Spider 回调)
    ├── Spider Middleware (5 个内置中间件)
    └── Item Pipeline → [可选] contrib/storage (持久化)

⚠️ 注意事项

  • Go 版本要求 — 需要 Go 1.25.1+
  • 回调函数类型安全 — CallbackFunc/ErrbackFunc 为具体函数类型（非 any），编译期即可捕获签名错误；使用 CallbackRegistry 注册回调函数支持断点续爬时的回调恢复
  • 对象池 — 高并发场景建议使用 pkg/pool 包的对象池减少 GC 压力
  • 优雅关闭 — 第一次 Ctrl+C 优雅关闭（等待进行中的请求完成），第二次强制退出
  • 中间件顺序 — ProcessRequest 按优先级正序执行，ProcessResponse 按优先级逆序执行

📚 文档

文档 说明
📖 完整参考文档 功能特性、配置项、更新日志的完整说明
🚀 快速入门指南 从零开始的详细教程
🏗️ 架构设计 核心组件内部结构与数据流
🔄 从 Python Scrapy 迁移 概念映射 + 代码对比 + 迁移检查清单
📊 Telemetry OpenTelemetry 追踪扩展
🌐 Redis 队列 分布式 Redis 请求队列
💾 Storage MongoDB/PostgreSQL/ES 持久化 Pipeline
⏱️ Rate Limit 滑动窗口分布式限速
🖥️ Web API REST 管理接口

📄 License

MIT

Directories

Path Synopsis
benchmarks
server
Package server 提供用于性能基准测试的本地 HTTP 服务器。
 Package server 提供用于性能基准测试的本地 HTTP 服务器。
cmd
scrapy-go command
Package main 实现 scrapy-go 命令行脚手架工具。
 Package main 实现 scrapy-go 命令行脚手架工具。
contrib
telemetry module
examples
books_json command
示例爬虫：从本地 JSON API 读取多页数据，通过 Pipeline 保存到本地 JSON 文件。
 示例爬虫：从本地 JSON API 读取多页数据，通过 Pipeline 保存到本地 JSON 文件。
crawlspider command
示例爬虫：使用 CrawlSpider 演示基于规则的多页面自动爬取。
 示例爬虫：使用 CrawlSpider 演示基于规则的多页面自动爬取。
custom_middleware command
示例爬虫：演示自定义下载器中间件和 Spider 中间件的使用。
 示例爬虫：演示自定义下载器中间件和 Spider 中间件的使用。
feedexport command
示例：演示 scrapy-go 的 Feed Export 数据导出系统完整 API。
 示例：演示 scrapy-go 的 Feed Export 数据导出系统完整 API。
itemadapter command
示例：演示 scrapy-go 的 ItemAdapter 体系完整 API。
 示例：演示 scrapy-go 的 ItemAdapter 体系完整 API。
pagination command
示例爬虫：分页爬取 + 详情页抓取。
 示例爬虫：分页爬取 + 详情页抓取。
quotes command
示例爬虫：使用本地静态网站演示 scrapy-go 框架的完整爬取流程。
 示例爬虫：使用本地静态网站演示 scrapy-go 框架的完整爬取流程。
template/project
scrapy-go middlewares 模板
 scrapy-go middlewares 模板
template/spiders/basic command
scrapy-go basic 爬虫模板
 scrapy-go basic 爬虫模板
template/spiders/json_api command
Package main 演示了 scrapy-go 的 Request 便捷 API 用法。
 Package main 演示了 scrapy-go 的 Request 便捷 API 用法。
typed_settings command
示例爬虫：演示 scrapy-go 泛型类型安全 Settings API（TD-004）。
 示例爬虫：演示 scrapy-go 泛型类型安全 Settings API（TD-004）。
internal
utils
Package utils 提供 scrapy-go 框架的内部工具函数。
 Package utils 提供 scrapy-go 框架的内部工具函数。
pkg
crawler
Package crawler 实现了 scrapy-go 框架的顶层编排器。
 Package crawler 实现了 scrapy-go 框架的顶层编排器。
debug
Package debug 提供 scrapy-go 框架的调试和性能分析工具。
 Package debug 提供 scrapy-go 框架的调试和性能分析工具。
downloader
Package downloader 实现了 scrapy-go 框架的下载器系统。
 Package downloader 实现了 scrapy-go 框架的下载器系统。
downloader/middleware
Package middleware 定义了下载器中间件的接口和内置实现。
 Package middleware 定义了下载器中间件的接口和内置实现。
downloader/middleware/httpcache
Package httpcache 实现了 HTTP 缓存中间件，对应 Scrapy 的 HttpCacheMiddleware。
 Package httpcache 实现了 HTTP 缓存中间件，对应 Scrapy 的 HttpCacheMiddleware。
engine
Package engine 实现了 scrapy-go 框架的核心调度引擎。
 Package engine 实现了 scrapy-go 框架的核心调度引擎。
errors
Package errors 定义了 scrapy-go 框架中跨包共享的错误类型。
 Package errors 定义了 scrapy-go 框架中跨包共享的错误类型。
extension
Package extension 实现了 scrapy-go 框架的扩展（Extension）系统。
 Package extension 实现了 scrapy-go 框架的扩展（Extension）系统。
feedexport
Package feedexport 实现了 scrapy-go 框架的数据导出（Feed Export）系统。
 Package feedexport 实现了 scrapy-go 框架的数据导出（Feed Export）系统。
http
Package http 定义了 scrapy-go 框架的 HTTP 请求和响应模型。
 Package http 定义了 scrapy-go 框架的 HTTP 请求和响应模型。
item
Package item 提供 scrapy-go 框架的 Item 统一访问抽象（ItemAdapter 体系）。
 Package item 提供 scrapy-go 框架的 Item 统一访问抽象（ItemAdapter 体系）。
linkextractor
Package linkextractor 提供链接提取器接口和实现。
 Package linkextractor 提供链接提取器接口和实现。
log
Package log 提供了 scrapy-go 框架的结构化日志封装。
 Package log 提供了 scrapy-go 框架的结构化日志封装。
pipeline
Package pipeline 定义了 scrapy-go 框架的 Item Pipeline 接口和管理器。
 Package pipeline 定义了 scrapy-go 框架的 Item Pipeline 接口和管理器。
pool
Package pool 提供 HTTP 请求/响应对象池，用于减少 GC 压力。
 Package pool 提供 HTTP 请求/响应对象池，用于减少 GC 压力。
scheduler
Package scheduler 实现了 scrapy-go 框架的请求调度系统。
 Package scheduler 实现了 scrapy-go 框架的请求调度系统。
scraper
Package scraper 实现了 scrapy-go 框架的 Scraper 组件。
 Package scraper 实现了 scrapy-go 框架的 Scraper 组件。
selector
Package selector 提供 HTML/XML 文档的 CSS 和 XPath 选择器。
 Package selector 提供 HTML/XML 文档的 CSS 和 XPath 选择器。
settings
Package settings 实现了 scrapy-go 框架的多优先级配置系统。
 Package settings 实现了 scrapy-go 框架的多优先级配置系统。
signal
Package signal 实现了 scrapy-go 框架的信号/事件系统。
 Package signal 实现了 scrapy-go 框架的信号/事件系统。
spider
Package spider 定义了 scrapy-go 框架的 Spider 接口和基础实现。
 Package spider 定义了 scrapy-go 框架的 Spider 接口和基础实现。
spider/middleware
Package middleware 定义了 Spider 中间件的接口和管理器。
 Package middleware 定义了 Spider 中间件的接口和管理器。
stats
Package stats 实现了 scrapy-go 框架的统计收集系统。
 Package stats 实现了 scrapy-go 框架的统计收集系统。
telemetry
Package telemetry 定义了 scrapy-go 框架的可观测性扩展点接口。
 Package telemetry 定义了 scrapy-go 框架的可观测性扩展点接口。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.