Faraday 使用教程：从安装到发起第一个请求

Faraday 是 Ruby 中用来发 HTTP 请求的库，适合在脚本、Rails 项目或后台服务里调用第三方 API。
这篇教程从安装开始，逐步写出 GET、POST 请求，并说明连接配置和常见报错的处理方式。

安装 Faraday 与项目准备

先确认本机 Ruby 和 Bundler 可用：

ruby -v
bundle -v

新建目录并初始化：

mkdir faraday-demo && cd faraday-demo
bundle init

打开 Gemfile，加入 Faraday：

source "https://rubygems.org"
gem "faraday"

安装依赖：

bundle install

如果不想用 Bundler，也可以直接执行 gem install faraday。
安装完成后，在 ruby -e 'require "faraday"; puts Faraday::VERSION' 中能看到版本号，说明环境就绪。

发起第一个 GET 请求

新建 get_demo.rb：

require "faraday"

conn = Faraday.new(url: "https://httpbin.org") do |f|
  f.options.timeout = 10
  f.options.open_timeout = 5
end

response = conn.get("/get", { foo: "bar" })
puts response.status
puts response.body

运行 ruby get_demo.rb。
如果返回 200 并看到包含 "foo": "bar" 的 JSON，说明请求成功。Faraday.new 里的 url 是基础地址，后续 get 传入的路径会拼接到它后面。

用 POST 提交数据并处理响应

Faraday 的 POST 有两种常见写法：表单提交和 JSON 提交。

表单提交：

response = conn.post("/post", { name: "test", age: "20" })

JSON 提交需要手动设置请求头：

response = conn.post("/post") do |req|
  req.headers["Content-Type"] = "application/json"
  req.body = { name: "test", age: 20 }.to_json
end

拿到响应后，先看 response.status 判断状态码，再用 response.body 读取内容。
如果接口返回 JSON，可以用 JSON.parse(response.body) 转成 Ruby 哈希。

连接、超时与错误处理

实际调用外部 API 时，网络抖动和超时很常见。
建议在创建连接时显式设置超时：

conn = Faraday.new(url: "https://httpbin.org") do |f|
  f.options.timeout = 15
  f.options.open_timeout = 5
end

open_timeout 控制建立连接的时间，timeout 控制读取响应的时间。
捕获异常可以避免脚本直接崩溃：

begin
  response = conn.get("/delay/20")
rescue Faraday::TimeoutError => e
  puts "请求超时: #{e.message}"
rescue Faraday::ConnectionFailed => e
  puts "连接失败: #{e.message}"
end

常见报错排查方向：

• Faraday::ConnectionFailed：检查域名解析、网络连通性和端口是否开放。
• Faraday::TimeoutError：适当增大 timeout，或检查目标服务是否响应过慢。
• SSL_connect 相关错误：确认系统 CA 证书是否完整，不要随意关闭 SSL 验证。
• 返回 404 或 401：核对请求路径、请求头和认证信息。

验证请求是否真正成功

不要只看程序有没有报错。
建议在脚本里同时打印状态码和关键字段：

puts "status=#{response.status}"
puts "content-type=#{response.headers['content-type']}"
puts "body=#{response.body[0, 200]}"

如果状态码是 2xx，并且 body 包含预期数据，才算调用成功。
对生产脚本，还可以把状态码和耗时写入日志，方便后续排查。

几个容易踩的坑

• 基础地址末尾是否带 / 会影响路径拼接，建议统一写成不带末尾斜杠的形式。
• 默认不会自动解析 JSON，需要自己调用 JSON.parse。
• 发送 JSON 时忘记设置 Content-Type，服务端可能按表单解析导致参数为空。
• 不要在循环里反复 Faraday.new，复用连接对象可以减少握手开销。

Faraday 本身不绑定具体 HTTP 适配器，默认使用 Ruby 标准库。
如果需要更高并发或连接池，可以再引入 faraday-net_http_persistent 等适配器，但普通脚本场景下默认配置已经够用。