后端网络通信【免费下载链接】faradaySimple, but flexible HTTP client library, with support for multiple backends.项目地址https://gitcode.com/gh_mirrors/fa/faraday点击查看免费下载Faraday 作为一款简单而灵活的 Ruby HTTP 客户端库其核心用法之一就是通过Faraday.new传入一个选项哈希options hash来定制连接行为。本文以官方文档 connection-options.md 为主体逐一剖析:request、:proxy、:ssl、:url、:parallel_manager、:params、:headers、:builder_class、:builder这九个连接级选项的含义、类型与默认值并结合仓库源码connection.rb、connection_options.rb说明它们是如何被解析和落地的。读完后你将能够根据业务场景超时控制、代理转发、TLS 校验、自定义中间件栈正确配置一个 Faraday 连接并理解配置项在底层的作用机制。一、选项总览一张表看清九个连接选项通过Faraday.new初始化连接时可以传入一个选项哈希来定制连接。文档明确指出所有选项都是可选的。下表完整列出官方文档中的九个选项OptionTypeDefaultDescription:requestHashnilHash of request options. Will be use to build RequestOptions.:proxyURI, String, HashnilProxy options, either as a URL or as a Hash of ProxyOptions.:sslHashnilHash of SSL options. Will be use to build SSLOptions.:urlURI, StringnilURI or String base URL. This can also be passed as positional argument.:parallel_managernilDefault parallel manager to use. This is normally set by the adapter, but you have the option to override it.:paramsHashnilURI query unencoded key/value pairs.:headersHashnilHash of unencoded HTTP header key/value pairs.:builder_classClassRackBuilderA custom class to use as the middleware stack builder.:builderObjectRackbuilder.newAn instance of a custom class to use as the middleware stack builder.从源码结构看这九个选项在Faraday::ConnectionOptions中被正式定义。查看 connection_options.rb 可以看到其声明方式ConnectionOptions Options.new(:request, :proxy, :ssl, :builder, :url, :parallel_manager, :params, :headers, :builder_class) do options request: RequestOptions, ssl: SSLOptions memoized(:request) { self.class.options_for(:request).new } memoized(:ssl) { self.class.options_for(:ssl).new } memoized(:builder_class) { RackBuilder } ... end这里有两个值得注意的实现细节嵌套选项自动转换:request和:ssl分别声明为RequestOptions与SSLOptions类型当传入 Hash 时会被自动构建成对应的 Options 子类实例转换逻辑位于 options.rb 的update方法中。默认值惰性生成memoized表示request、ssl、builder_class的默认值在首次访问时才创建RackBuilder是:builder_class的默认值避免无谓的对象分配。二、:url基础 URL 的两种传法:url用于设置连接的基础地址base URL支持URI或String类型。它既可以放在选项哈希里也可以作为Faraday.new的位置参数传入两种方式完全等价# 方式一位置参数 conn Faraday.new(https://example.com) # 方式二选项哈希 conn Faraday.new(url: https://example.com) # 方式三位置参数 选项哈希混用 conn Faraday.new(https://example.com, params: { page: 1 })关于:url的处理Faraday.new的入口代码位于 faraday.rbdef new(url nil, options {}, block) options Utils.deep_merge(default_connection_options, options) Faraday::Connection.new(url, options, block) end而在 connection.rb 的initialize中当第一个参数是 Hash 时它会被视为选项哈希并合并到选项中最终统一通过url_prefix设置def initialize(url nil, options nil) options ConnectionOptions.from(options) if url.is_a?(Hash) || url.is_a?(ConnectionOptions) options Utils.deep_merge(options, url) url options.url end ... self.url_prefix url || http:/ ... end进阶细节url_prefixconnection.rb并不只是保存一个字符串。它会做三件额外的事把 URL 中携带的查询参数如?tokenabc合并进连接的params如果 URL 中带有user:passwordhost形式的凭据会自动设置 Basic Auth 请求头在没有显式配置代理的情况下根据该 URL 重新探测环境代理。因此url: https://user:passapi.example.com?tokenabc一条配置就能同时完成基础地址、认证和默认查询参数的初始化。三、:request请求级选项的容器:request接受一个 Hash会被构造成RequestOptions并作为所有请求的默认请求选项。它的详细字段超时、编码器、绑定地址等在独立文档 request-options.md 中说明此处是官方给出的连接级配置示例options { request: { open_timeout: 5, timeout: 5 }, # ... 其他连接选项 } conn Faraday.new(options) do |faraday| # ... end从源码看request_options.rb 定义了完整的请求选项字段RequestOptions Options.new(:params_encoder, :proxy, :bind, :timeout, :open_timeout, :read_timeout, :write_timeout, :boundary, :oauth, :context, :on_data) do其中与上面示例直接对应的是:timeout— 请求完成的最长等待秒数Integer 或 Float默认 nil即使用适配器默认值:open_timeout— 建立连接的最长等待秒数。逐请求覆盖连接级request选项只是默认值每个请求仍可在 block 中覆盖例如req.options.timeout 10详见 request-options.md 的示例。四、:proxy代理配置的三种形态:proxy是连接选项中类型最灵活的一个支持URI、String、Hash三种形态最终统一转换成ProxyOptions。官方示例使用 Hash 形态proxy: { uri: https://proxy.com, user: proxy_user, password: proxy_password }ProxyOptions 只有三个字段:uri代理 URL、:user代理用户名、:password代理密码。源码级转换逻辑ProxyOptions.from在 proxy_options.rb 中实现了一整套类型归一化def self.from(value) case value when value nil when String # 没有 scheme 的 URI 默认补全为 http如 example:123 value http://#{value} unless value.include?(://) value { uri: Utils.URI(value) } when URI value { uri: value } when Hash, Options if value[:uri] value value.dup.tap do |duped| duped[:uri] Utils.URI(duped[:uri]) end end end super end这段代码意味着你可以直接写proxy: https://proxy.com字符串或proxy: URI(https://proxy.com)URI 对象而不仅仅是 Hash。同时memoized(:user)/memoized(:password)proxy_options.rb允许从 URI 中的凭据惰性提取用户名密码例如proxy: https://user:passproxy.com。代理探测顺序在 connection.rb 的initialize_proxy中如果未显式传入:proxyFaraday 会调用proxy_from_env从环境变量http_proxy读取代理只有当你显式设置:proxy时manual_proxy true才会跳过环境探测。如果希望完全忽略环境代理可以设置Faraday.ignore_env_proxy true见 faraday.rb 与 connection.rb。五、:sslTLS 证书校验与加密配置:ssl接受一个 Hash会被构造成SSLOptions用于控制 HTTPS 场景下的证书校验、TLS 版本与密码套件。官方示例ssl: { ca_file: /path/to/ca_file, ca_path: /path/to/ca_path, verify: true }这三个字段的含义完整字段表见 ssl-options.md:ca_file— PEM 格式 CA 证书文件路径:ca_path— CA 证书目录路径:verify— 是否校验 SSL 证书默认true。ssl_options.rb 声明了完整的字段列表共 16 项verify、verify_hostname、hostname、ca_file、ca_path、verify_mode、cert_store、client_cert、client_key、certificate、private_key、verify_depth、version、min_version、max_version、ciphers。其中certificate与private_key是 Excon 适配器专用。源码中的快捷方法ssl_options.rbdef verify? verify ! false end def disable? !verify? end def verify_hostname? verify_hostname ! false end从这些方法可以推断verify与verify_hostname的语义是「只要不是显式设为false就视为开启」因此默认均为true证书校验与主机名校验默认开启只有显式传verify: false才会关闭。六、:params与:headers全局默认查询参数与请求头:params接收「未编码的 URI 查询键值对」Hash:headers接收「未编码的 HTTP 请求头键值对」Hash。两者会作为连接级默认值被复制到每一次请求中。官方示例params: { foo: bar }, headers: { X-Api-Key secret, X-Api-Version 2 }源码中的底层容器在 connection.rb 中它们分别存储在专用的容器类中headers Utils::Headers.new params Utils::ParamsHash.new随后在 connection.rb 中把选项哈希更新进去params.update(options.params) if options.params headers.update(options.headers) if options.headers而每次请求时build_requestconnection.rb会通过req.params params.dup和req.headers headers.dup把连接级的默认值复制到每个请求对象上实现「连接级默认 请求级覆盖」的效果。注意headers[:user_agent]在初始化末尾还会被默认设置为Faraday v#{VERSION}connection.rb。七、Faraday.new与Faraday::Connection.new的差异官方文档开头提到 When initializing a new Faraday connection withFaraday.new。事实上Faraday.newfaraday.rb会先执行一步Utils.deep_merge(default_connection_options, options)把Faraday.default_connection_options中预设的默认选项与你的显式选项合并再转交给Faraday::Connection.new完成真正的初始化。也就是说Faraday.new(options)适合日常使用会自动叠加全局默认连接选项Faraday::Connection.new(url, options)是底层构造器不会叠加全局默认值适合需要完全掌控配置的场景。conn Faraday.new(url: https://example.com, params: { page: 1 }) # 等价于 conn Faraday::Connection.new(https://example.com, params: { page: 1 })八、:builder_class与:builder自定义中间件栈构建器:builder_class和:builder都用于替换默认的中间件栈构建器两者仅存在「类 vs 实例」的差异选项类型默认值说明:builder_classClassRackBuilder用作中间件栈构建器的自定义类:builderObjectRackBuilder.new用作中间件栈构建器的自定义实例在 connection.rb 中可以看到二者协作的初始化逻辑builder options.builder || begin # 传入空 block 以便 Builder 不加载默认中间件 options.new_builder(block_given? ? proc { |b| } : nil) end而new_builder在 connection_options.rb 中定义def new_builder(block) builder_class.new(block) end即如果提供了:builder实例则直接使用否则用:builder_class默认RackBuilder新建一个构建器并把Faraday.new后跟的 block如do |faraday| ... end交给它去配置中间件栈。也就是说Faraday.new(...) do |faraday| faraday.request :json; faraday.adapter :net_http end这类写法本质就是在往builder_class生成的实例上注册中间件。九、:parallel_manager默认并行管理器:parallel_manager用于设置默认的并行管理器官方文档特别说明它通常由适配器adapter设置但你也可以覆盖它。在 connection.rb 与 connection.rb 中可以看到其默认行为default_parallel_manager options.parallel_manager def default_parallel_manager default_parallel_manager || begin adapter builder.adapter.klass if builder.adapter if support_parallel?(adapter) adapter.setup_parallel_manager elsif block_given? yield end end end从中可以推断只有当底层适配器支持并行实现supports_parallel?时才会自动调用adapter.setup_parallel_manager创建并行管理器否则调用in_parallel时会发出警告connection.rb。如果你需要强行使用某个并行管理器就可以通过:parallel_manager传入覆盖适配器默认行为。并行请求的具体用法参见 parallel-requests.md。十、完整示例把九个选项组合起来官方文档给出的完整示例同时覆盖了超时、代理、SSL、基础 URL、查询参数与请求头六个核心维度此处原样保留并补充逐行注释使其可直接复制运行options { request: { open_timeout: 5, # 建立连接的超时秒 timeout: 5 # 整个请求完成的超时秒 }, proxy: { uri: https://proxy.com, user: proxy_user, password: proxy_password }, ssl: { ca_file: /path/to/ca_file, # PEM 格式 CA 文件 ca_path: /path/to/ca_path, # CA 证书目录 verify: true # 校验证书默认即 true }, url: https://example.com, # 基础 URL也可作位置参数 params: { foo: bar }, # 全局默认查询参数 headers: { X-Api-Key secret, X-Api-Version 2 } # 全局默认请求头 } conn Faraday.new(options) do |faraday| # 在这里通过 faraday.request / faraday.response / faraday.adapter # 注册中间件与适配器不写 block 时使用默认中间件栈 # faraday.request :json # faraday.adapter :net_http end十一、与相关文档的衔接本文覆盖的是连接级connection-level选项。Faraday 将配置项划分为三个层次各有独立文档连接级请求选项:request内部的 timeout、params_encoder 等→ request-options.md代理选项:uri、:user、:password的完整定义 → proxy-options.mdSSL 选项 16 个字段的完整表格 → ssl-options.md连接级选项一经设置即作用于该连接上的所有请求而请求级选项则允许在每次请求的 block 中逐请求覆盖。理解「连接级默认 请求级覆盖」这一分层模型是高效使用 Faraday 的关键把稳定的公共配置认证头、超时、CA 证书、代理放在Faraday.new的选项哈希中把临时差异单次超时、单次请求头放在每次调用的 block 里即可。小结连接选项是 Faraday 面向用户的第一层配置面。通过本文你可以掌握九大连接选项各自的类型、默认值与作用:url的三种传法以及它附带查询参数提取、Basic Auth 设置、代理重探测三个副作用:proxy的 URI/String/Hash 三种形态及字符串代理自动补全http://的转换细节SSL 校验默认开启的语义verify ! false即视为开启与常用字段:builder_class与:builder的区别前者是类默认RackBuilder后者是实例优先使用实例并行管理器的默认来源通常由适配器提供:parallel_manager用于显式覆盖。如果需要深入某个子选项请直接查阅 request-options.md、proxy-options.md 与 ssl-options.md 三份文档相关实现的完整源码可进一步阅读 connection.rb、connection_options.rb 以及底层的 options.rb。赞分享后端网络通信【免费下载链接】faradaySimple, but flexible HTTP client library, with support for multiple backends.项目地址https://gitcode.com/gh_mirrors/fa/faraday点击查看免费下载相关推荐MXNet.jl 参数初始化器Initializer完全指南从 Uniform、Normal 到 Xavier 的源码级剖析MXNet.jl 参数初始化器Initializer完全指南从 Uniform、Normal 到 Xavier 的源码级剖析 本指南以 Apache MX深度学习机器学习人工智能BetterScroll 配置项完全指南从初始化参数到源码级实现原理BetterScroll 配置项完全指南从初始化参数到源码级实现原理 本文基于 BetterScroll 官方中文文档《配置项》编写系统梳理 BetterS前端UI组件RQ 连接管理完全指南connection 参数、Redis Sentinel 与超时机制详解RQ 连接管理完全指南connection 参数、Redis Sentinel 与超时机制详解 导读 本文基于 RQ 官方连接文档 https://link.任务调度后端消息队列上一篇OpenCompass LLM 评判器GenericLLMEvaluator / CascadeEvaluator使用指南以 LLM 为评判器的模型评估实战下一篇Plate 编辑器行为批次启动命令 launch-next-ralph-batch 解析从已批准计划到运行时执行的落地指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考