Ruby 调用 REST API：net/http、HTTParty 与 Faraday 实战
本文讲解 Ruby 消费 REST API 的三种主流方式：标准库 net/http、轻量封装 HTTParty 和灵活的 Faraday，涵盖认证、JSON 解析、错误处理与超时设置等生产级写法。
简单脚本用标准库 net/http 即可，零依赖；想要简洁接口选 HTTParty；需要中间件、连接复用、统一错误处理等复杂能力时用 Faraday。三者都要记得显式设置超时并处理非 2xx 响应，这是生产代码与示例代码的分水岭。
Ruby 的 HTTP 工具箱
Ruby 标准库自带三件套：Net::HTTP 负责请求，URI 负责地址解析，JSON 负责编解码。生态里的 gem 则在此基础上提供更友好的封装：HTTParty 主打"一行一个请求"，Faraday 主打中间件和适配器架构。
用 net/http 发出第一个请求
标准库写法稍显啰嗦，但胜在无外部依赖：
require 'net/http'
require 'json'
uri = URI('https://api.github.com/users/ruby')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.open_timeout = 3
http.read_timeout = 10
response = http.get(uri.request_uri, { 'User-Agent' => 'my-app' })
if response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)
puts data['name']
else
puts "请求失败：#{response.code}"
end
几个要点：必须显式设置超时（默认 60 秒太长，网络故障时会拖垮整个进程）；必须检查响应状态，get 返回 404/500 不会抛异常。
处理 POST 与认证
request = Net::HTTP::Post.new(uri)
request['Authorization'] = "Bearer #{token}"
request['Content-Type'] = 'application/json'
request.body = JSON.generate({ name: 'demo' })
response = http.request(request)
Bearer Token、Basic Auth（request.basic_auth(user, pass)）、自定义 Header 都是这个套路。
HTTParty：更顺手的封装
require 'httparty'
response = HTTParty.get(
'https://api.github.com/users/ruby',
headers: { 'User-Agent' => 'my-app' },
timeout: 10
)
puts response.parsed_response['name'] if response.success?
HTTParty 自动解析 JSON（parsed_response）、提供 success? 判断，还能通过 include HTTParty 把 API 封装成类，集中管理 base_uri 和默认 Header。
Faraday：面向复杂场景
Faraday 的核心是中间件栈：重试、日志、JSON 编解码都可以插拔：
conn = Faraday.new(url: 'https://api.example.com') do |f|
f.request :json
f.request :retry, max: 3, interval: 0.5
f.response :json
f.response :raise_error
f.adapter Faraday.default_adapter
end
conn.headers['Authorization'] = "Bearer #{token}"
user = conn.get('/users/1').body
连接对象可复用，配合 raise_error 中间件把 4xx/5xx 统一转成异常，错误处理逻辑只写一处。
错误处理的完整姿势
一次健壮的 API 调用要覆盖三层异常：网络层（连接拒绝、超时，捕获 Net::OpenTimeout、Errno::ECONNREFUSED 等）、HTTP 层（4xx/5xx 状态码）、数据层（JSON 解析失败、字段缺失）。批量调用第三方 API 时还应考虑限流退避，避免触发对方风控。
常见问题（FAQ）
Q：net/http 和 gem 比性能差很多吗？
单次请求差异可忽略，瓶颈在网络本身。差距体现在高并发场景：gem 生态（如 Faraday 配 typhoeus 适配器）支持并行请求和 keep-alive 连接复用，标准库则需要自己管理。
先升级系统 CA 证书包（macOS 上 brew install ca-certificates）。绝不要用 VERIFY_NONE 关掉验证——那等于放弃 HTTPS 的安全保障。
Q：需要调用内部大量微服务，选哪个？
选 Faraday。统一封装连接对象，把认证、重试、日志、熔断做成中间件，所有服务调用走同一套规范，后续接监控和链路追踪也容易。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
