errors

Documentation

Overview

Package errors 定义了 scrapy-go 框架中跨包共享的错误类型。

概述

errors 包收纳了需要在多个包之间共享语义契约的错误——即某个包抛出后， 其他包需要通过 errors.Is 进行识别并据此改变行为的框架级语义错误。 对应 Scrapy Python 版本中 scrapy.exceptions 模块的功能。

职责边界

本包仅包含跨包共享的框架级错误。对于仅在单个包内使用的局部错误 （如 Runner 生命周期错误、Queue 满错误等），应遵循 Go 官方惯用法 就近定义在其所属包中（参考 io.EOF、sql.ErrNoRows 的放置方式）。

哨兵错误（Sentinel Errors）

框架定义了以下哨兵错误，使用 errors.Is 进行匹配：

组件配置：

• ErrNotConfigured：组件未配置，框架将跳过该组件

Spider 控制：

• ErrCloseSpider：请求关闭 Spider
• ErrDontCloseSpider：阻止 Spider 关闭（在 SpiderIdle 信号中使用）

请求处理：

• ErrIgnoreRequest：决定不处理某个请求
• ErrNewRequest：中间件希望用新请求替代当前请求

Item 处理：

• ErrDropItem：从 Pipeline 中丢弃一个 Item

下载错误：

• ErrDownloadTimeout：下载超时
• ErrDownloadFailed：下载失败
• ErrConnectionRefused：连接被拒绝
• ErrCannotResolveHost：无法解析主机名
• ErrResponseDataLoss：响应数据不完整
• ErrStopDownload：停止下载响应体

其他：

• ErrInvalidOutput：中间件返回了无效的输出类型
• ErrNotSupported：不支持的功能或方法
• ErrPanic：从 panic 中恢复的错误

结构化错误类型

对于需要携带额外上下文信息的错误，包提供了对应的结构化类型：

• CloseSpiderError：带关闭原因的 CloseSpider 错误
• DropItemError：带消息的 DropItem 错误
• StopDownloadError：带 fail 标志的 StopDownload 错误
• NewRequestError：携带新请求的替换错误
• NotConfiguredError：带消息的 NotConfigured 错误
• PanicError：带 panic 值和堆栈信息的错误

所有结构化错误类型都实现了 errors.Is 接口，可以匹配对应的哨兵错误：

err := errors.NewCloseSpiderError("timeout")
errors.Is(err, errors.ErrCloseSpider) // true

错误创建

每种结构化错误都提供了对应的构造函数：

• NewCloseSpiderError(reason)
• NewDropItemError(message)
• NewStopDownloadError(fail)
• NewNewRequestError(request, reason)
• NewNotConfiguredError(message)
• NewPanicError(value, stack)

辅助函数

IsRetryable 判断错误是否可重试，以下错误类型被认为是可重试的：

• ErrDownloadTimeout
• ErrConnectionRefused
• ErrDownloadFailed
• ErrResponseDataLoss
• ErrCannotResolveHost

与 Scrapy 的差异

• 使用 Go 的 errors.Is/errors.As 替代 Python 的 isinstance 类型检查
• 使用哨兵错误 + 结构化错误的双层设计（Scrapy 只有异常类）
• NewRequestError 替代 Scrapy 中通过 Meta 键传递新请求的 hack 方式
• PanicError 是 Go 特有的（Python 无 panic 机制）
• StopDownloadError 的 Fail 标志决定部分响应传递给 callback 还是 errback
• 使用 any 类型避免循环依赖（NewRequestError.Request）

使用模式

中间件中丢弃请求：

func (m *MyMiddleware) ProcessRequest(req *http.Request) error {
    if shouldIgnore(req) {
        return errors.ErrIgnoreRequest
    }
    return nil
}

Pipeline 中丢弃 Item：

func (p *MyPipeline) ProcessItem(ctx context.Context, item any) (any, error) {
    if isDuplicate(item) {
        return nil, errors.NewDropItemError("duplicate item")
    }
    return item, nil
}

信号处理器中阻止 Spider 关闭：

manager.Connect(func(params map[string]any) error {
    if hasMoreWork() {
        return errors.ErrDontCloseSpider
    }
    return nil
}, signal.SpiderIdle)

Index

• Variables
• func IsRetryable(err error) bool
• type CloseSpiderError
  • func NewCloseSpiderError(reason string) *CloseSpiderError
  • func (e *CloseSpiderError) Error() string
  • func (e *CloseSpiderError) Is(target error) bool
• type DropItemError
  • func NewDropItemError(message string) *DropItemError
  • func (e *DropItemError) Error() string
  • func (e *DropItemError) Is(target error) bool
• type NewRequestError
  • func NewNewRequestError(request any, reason string) *NewRequestError
  • func (e *NewRequestError) Error() string
  • func (e *NewRequestError) Is(target error) bool
• type NotConfiguredError
  • func NewNotConfiguredError(message string) *NotConfiguredError
  • func (e *NotConfiguredError) Error() string
  • func (e *NotConfiguredError) Is(target error) bool
• type PanicError
  • func NewPanicError(value any, stack string) *PanicError
  • func (e *PanicError) Error() string
  • func (e *PanicError) Is(target error) bool
• type StopDownloadError
  • func NewStopDownloadError(fail bool) *StopDownloadError
  • func (e *StopDownloadError) Error() string
  • func (e *StopDownloadError) Is(target error) bool

Variables

var ErrCannotResolveHost = errors.New("cannot resolve host")

ErrCannotResolveHost 表示无法解析主机名，对应 Scrapy 的 CannotResolveHostError。

var ErrCloseSpider = errors.New("close spider")

ErrCloseSpider 表示请求关闭 Spider，对应 Scrapy 的 CloseSpider 异常。

var ErrConnectionRefused = errors.New("connection refused")

ErrConnectionRefused 表示连接被拒绝，对应 Scrapy 的 DownloadConnectionRefusedError。

var ErrDontCloseSpider = errors.New("don't close spider")

ErrDontCloseSpider 表示请求不要关闭 Spider，对应 Scrapy 的 DontCloseSpider 异常。 在 spider_idle 信号处理器中返回此错误可阻止 Spider 关闭。

var ErrDownloadFailed = errors.New("download failed")

ErrDownloadFailed 表示下载失败，对应 Scrapy 的 DownloadFailedError。

var ErrDownloadTimeout = errors.New("download timeout")

ErrDownloadTimeout 表示下载超时，对应 Scrapy 的 DownloadTimeoutError 异常。

var ErrDropItem = errors.New("item dropped")

ErrDropItem 表示从 Item Pipeline 中丢弃一个 Item，对应 Scrapy 的 DropItem 异常。

var ErrIgnoreRequest = errors.New("request ignored")

ErrIgnoreRequest 表示决定不处理某个请求，对应 Scrapy 的 IgnoreRequest 异常。

var ErrInvalidOutput = errors.New("invalid middleware output")

ErrInvalidOutput 表示中间件返回了无效的输出类型，对应 Scrapy 的 _InvalidOutput 异常。

var ErrNewRequest = errors.New("new request")

ErrNewRequest 是一个哨兵错误，表示中间件希望用一个新请求替代当前请求。 使用 errors.Is(err, ErrNewRequest) 可以匹配 NewRequestError。

var ErrNotConfigured = errors.New("component not configured")

ErrNotConfigured 表示组件未配置，对应 Scrapy 的 NotConfigured 异常。 中间件初始化时返回此错误，框架将跳过该中间件并记录警告日志。

var ErrNotSupported = errors.New("not supported")

ErrNotSupported 表示不支持的功能或方法，对应 Scrapy 的 NotSupported 异常。

var ErrPanic = errors.New("panic recovered")

ErrPanic 表示从 panic 中恢复的错误。 当用户代码（Spider 回调、Pipeline、中间件等）发生 panic 时， 框架会捕获 panic 并将其转换为此错误，避免整个进程崩溃。

var ErrResponseDataLoss = errors.New("response data loss")

ErrResponseDataLoss 表示响应数据不完整，对应 Scrapy 的 ResponseDataLossError。

var ErrStopDownload = errors.New("stop download")

ErrStopDownload 表示停止下载响应体，对应 Scrapy 的 StopDownload 异常。

Functions

func IsRetryable

func IsRetryable(err error) bool

IsRetryable 判断错误是否可重试。 以下错误类型被认为是可重试的：

• ErrDownloadTimeout
• ErrConnectionRefused
• ErrDownloadFailed
• ErrResponseDataLoss
• ErrCannotResolveHost

Types

type CloseSpiderError

type CloseSpiderError struct {
	Reason string
}

CloseSpiderError 是带关闭原因的 CloseSpider 错误。 使用 errors.Is(err, ErrCloseSpider) 可以匹配此错误。

func NewCloseSpiderError

func NewCloseSpiderError(reason string) *CloseSpiderError

NewCloseSpiderError 创建一个带原因的 CloseSpider 错误。

func (*CloseSpiderError) Error

func (e *CloseSpiderError) Error() string

func (*CloseSpiderError) Is

func (e *CloseSpiderError) Is(target error) bool

Is 实现 errors.Is 接口，使 CloseSpiderError 可以匹配 ErrCloseSpider。

type DropItemError

type DropItemError struct {
	Message  string
	LogLevel string // 可选的日志级别覆盖
}

DropItemError 是带消息的 DropItem 错误。 使用 errors.Is(err, ErrDropItem) 可以匹配此错误。

func NewDropItemError

func NewDropItemError(message string) *DropItemError

NewDropItemError 创建一个带消息的 DropItem 错误。

func (*DropItemError) Error

func (e *DropItemError) Error() string

func (*DropItemError) Is

func (e *DropItemError) Is(target error) bool

Is 实现 errors.Is 接口，使 DropItemError 可以匹配 ErrDropItem。

type NewRequestError

type NewRequestError struct {
	// Request 是需要重新调度的新请求。
	Request any // 实际类型为 *http.Request，使用 any 避免循环依赖
	// Reason 是产生新请求的原因（如 "retry"、"redirect"）。
	Reason string
}

NewRequestError 表示中间件需要将当前请求替换为一个新请求。 典型场景包括重试（RetryMiddleware）和重定向（RedirectMiddleware）。

当中间件的 ProcessResponse 或 ProcessException 返回此错误时， Manager 会将其传播给 Engine，由 Engine 将新请求重新调度到 Scheduler。 这种方式替代了之前通过 Meta 键（如 "_retry_request"、"_redirect_request"） 传递新请求的 hack 方式，更加类型安全且符合 Go 的错误处理惯例。

func NewNewRequestError

func NewNewRequestError(request any, reason string) *NewRequestError

NewNewRequestError 创建一个 NewRequestError。 request 参数的实际类型应为 *http.Request。

func (*NewRequestError) Error

func (e *NewRequestError) Error() string

func (*NewRequestError) Is

func (e *NewRequestError) Is(target error) bool

Is 实现 errors.Is 接口，使 NewRequestError 可以匹配 ErrNewRequest。

type NotConfiguredError

type NotConfiguredError struct {
	Message string
}

NotConfiguredError 是带消息的 NotConfigured 错误。

func NewNotConfiguredError

func NewNotConfiguredError(message string) *NotConfiguredError

NewNotConfiguredError 创建一个带消息的 NotConfigured 错误。

func (*NotConfiguredError) Error

func (e *NotConfiguredError) Error() string

func (*NotConfiguredError) Is

func (e *NotConfiguredError) Is(target error) bool

Is 实现 errors.Is 接口。

type PanicError

type PanicError struct {
	// Value 是 panic 传递的原始值。
	Value any
	// Stack 是 panic 发生时的堆栈信息。
	Stack string
}

PanicError 是带有 panic 值和堆栈信息的结构化错误。 使用 errors.Is(err, ErrPanic) 可以匹配此错误。

func NewPanicError

func NewPanicError(value any, stack string) *PanicError

NewPanicError 创建一个 PanicError。 value 是 recover() 返回的值，stack 是格式化的堆栈信息。

func (*PanicError) Error

func (e *PanicError) Error() string

func (*PanicError) Is

func (e *PanicError) Is(target error) bool

Is 实现 errors.Is 接口，使 PanicError 可以匹配 ErrPanic。

type StopDownloadError

type StopDownloadError struct {
	Fail bool
}

StopDownloadError 是带 fail 标志的 StopDownload 错误。 Fail 为 true 时，部分响应将传递给 errback；为 false 时传递给 callback。

func NewStopDownloadError

func NewStopDownloadError(fail bool) *StopDownloadError

NewStopDownloadError 创建一个 StopDownload 错误。

func (*StopDownloadError) Error

func (e *StopDownloadError) Error() string

func (*StopDownloadError) Is

func (e *StopDownloadError) Is(target error) bool

Is 实现 errors.Is 接口，使 StopDownloadError 可以匹配 ErrStopDownload。