Faraday 2.0 升级指南：适配器与中间件的重大变革

Faraday 2.0 升级指南：适配器与中间件的重大变革

faraday Simple, but flexible HTTP client library, with support for multiple backends. 项目地址: https://gitcode.com/gh_mirrors/fa/faraday

前言

Faraday 是一个广受欢迎的 Ruby HTTP 客户端库，以其简洁的 API 和灵活的中间件架构著称。随着 Faraday 2.0 的发布，项目架构发生了重大变化，主要涉及适配器和中间件的管理方式。本文将详细解析这些变更，帮助开发者顺利完成升级。

适配器的重大变革

适配器外移的核心变化

Faraday 2.0 最显著的变化是将除 net_http 外的所有适配器移出了核心库。这意味着：

1. 默认情况下，只有 net_http 适配器可用
2. 其他适配器需要作为独立 gem 安装
3. 每个适配器将有独立的维护周期

重要提示：虽然最初 2.0 版本移除了 net_http 适配器，但在 2.0.1 版本中又重新引入。建议直接使用 2.0.1 或更高版本。

变革背后的技术考量

这一架构调整基于以下技术考虑：

1. 关注点分离：让 Faraday 核心专注于提供标准化的中间件栈 API
2. 维护效率：减轻核心团队维护多种适配器的负担，依靠社区力量维护特定适配器
3. 平等原则：避免"一等"和"二等"适配器的区分，所有适配器都作为独立 gem 存在
4. 依赖管理：保持 Faraday 核心无依赖，适配器自行管理所需依赖

升级实践指南

根据您的使用场景，升级步骤有所不同：

场景一：仅使用默认 net_http 适配器

无需任何更改，直接升级即可。

场景二：使用其他适配器

1. 在 Gemfile 中添加所需适配器 gem
2. 在代码中显式引入适配器

# Gemfile 示例
gem 'faraday'
gem 'faraday-net_http_persistent'

# 代码示例
require 'faraday'
require 'faraday/net_http_persistent'

中间件生态的演变

Faraday Middleware 的命运

Faraday 2.0 对中间件采取了与适配器相似的策略：

1. 不再维护集中式的 faraday_middleware gem
2. 鼓励将常用中间件拆分为独立 gem
3. JSON 处理中间件已纳入 Faraday 核心

核心中间件的调整

Faraday 2.0 将以下中间件移出核心库：

1. retry → faraday-retry gem
2. multipart → faraday-multipart gem

升级方法：

# Gemfile 示例
gem 'faraday-retry'
gem 'faraday-multipart'

# 代码示例
require 'faraday/retry'
require 'faraday/multipart'

conn = Faraday.new(url) do |f|
  f.request :multipart
  f.request :retry
  # 其他配置...
end

其他重要变更

自动加载与依赖管理

Faraday 2.0 简化了依赖管理系统：

1. 移除了动态依赖加载机制
2. 中间件注册采用新语法：

Faraday::Middleware.register_middleware(name: klass)

认证辅助方法变更

移除了 Connection 对象上的认证辅助方法：

• authorization
• basic_auth
• token_auth

替代方案是使用对应的中间件实现认证功能。

错误处理改进

Faraday 2.0 重构了错误处理体系：

1. 引入 Faraday::ServerError 专门处理 5xx 状态码
2. 新增多种具体错误类对应常见 HTTP 状态码
3. 调整了部分错误类的继承关系

升级建议

1. 评估依赖：检查项目中使用的适配器和中间件
2. 逐步升级：先处理适配器，再处理中间件
3. 测试验证：升级后全面测试关键功能
4. 关注日志：注意弃用警告和错误信息

结语

Faraday 2.0 的架构变革标志着项目向更模块化、更可持续的方向发展。虽然升级过程可能需要一些调整，但这些变化将为 Faraday 生态系统的长期健康发展奠定基础。通过遵循本文指南，开发者可以顺利完成升级，继续享受 Faraday 带来的高效 HTTP 客户端体验。

faraday Simple, but flexible HTTP client library, with support for multiple backends. 项目地址: https://gitcode.com/gh_mirrors/fa/faraday