fuels-rs 中 Provider 请求重试配置详解RetryConfig 与 Backoff 间隔策略【免费下载链接】fuels-rsFuel Network Rust SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs在 fuels-rsFuel Network Rust SDK中Provider负责与 Fuel 节点的所有通信。网络抖动或节点瞬时故障时请求可能随机失败SDK 为此提供了可配置的重试机制当请求收到io::Error时Provider可以根据RetryConfig自动重试并支持线性、指数、固定三种间隔策略Backoff。阅读本文后你可以掌握如何为 Provider 配置重试次数与间隔策略、三种 Backoff 的计算规则以及底层retry函数的调用链与默认行为从而在连接不稳定节点或远程节点时编写更健壮的应用。重试机制的触发条件与重要前提Provider可以配置为在收到io::Error时重试请求。这里有一个必须了解的前提当前所有节点错误node error都是以io::Error的形式返回的。因此一旦配置了重试即使是类似“交易验证失败”这类业务性失败也会触发重试而不仅仅是网络层故障。在配置重试次数时需要考虑这一点——重试不会“变出”原本必然失败的结果只会增加请求的耗时。重试能力的作用范围可以从源码得到确认Provider内部通过CachedClientRetryableClient包裹客户端见 provider.rs所有发往节点的 RPC 调用都由RetryableClient的wrap方法统一包一层重试逻辑。配置重试RetryConfig重试行为通过向 Provider 传入一个自定义RetryConfig来改变。它封装了两个参数max_attempts放弃前的最大尝试次数类型是NonZeroU32从源码结构看必须大于 0RetryConfig::new对 0 值会返回错误 max_attemptsmust be greater than0interval来自Backoff枚举的间隔策略决定每次重试之间等待多久。结构定义位于 retry_util.rs#[derive(Clone, Debug)] pub struct RetryConfig { max_attempts: NonZeroU32, interval: Backoff, }构造函数会校验max_attempts并返回Result见 retry_util.rsimpl RetryConfig { pub fn new(max_attempts: u32, interval: Backoff) - ResultSelf { let max_attempts NonZeroU32::new(max_attempts) .ok_or_else(|| error!(Other, max_attempts must be greater than 0))?; Ok(RetryConfig { max_attempts, interval, }) } }默认值默认不重试RetryConfig实现了Default见 retry_util.rsimpl Default for RetryConfig { fn default() - Self { Self { max_attempts: NonZeroU32::new(1).expect(should not fail), interval: Default::default(), } } }也就是说默认最大尝试次数为 1——即只执行一次、不重试。这一点在Provider::connect_with_fallbacks中可以直接看到连接时传入的正是RetryConfig的Default::default()见 provider.rspub async fn connect_with_fallbacks(urls: [impl AsRefstr]) - ResultProvider { let client CachedClient::new( RetryableClient::connect_with_fallbacks(urls, Default::default()).await?, TtlConfig::default(), SystemClock, ); // ... }因此如果你想启用重试必须显式调用Provider::with_retry_config。该方法会透传到底层RetryableClient见 provider.rspub fn with_retry_config(mut self, retry_config: RetryConfig) - Self { self.uncached_client_mut().set_retry_config(retry_config); self }完整配置示例仓库中 examples/providers/src/lib.rs 给出了配置重试的示例代码对应文档锚点configure_retryuse std::time::Duration; // 最多尝试 3 次每次重试之间固定等待 2 秒 let retry_config RetryConfig::new(3, Backoff::Fixed(Duration::from_secs(2)))?; let provider setup_test_provider(coins.clone(), vec![], None, None) .await? .with_retry_config(retry_config);在实际项目中你可以把它替换为自己创建的 Provider例如let provider Provider::connect(http://127.0.0.1:4000) .await? .with_retry_config(RetryConfig::new(3, Backoff::Fixed(Duration::from_secs(2)))?);其中RetryConfig与Backoff均从fuels::accounts::provider路径导出见 provider.rs 中的pub use retry_util::{Backoff, RetryConfig};并经由fuels顶层 prelude 的accounts::provider::*再导出对外可见。间隔策略BackoffBackoff枚举定义了管理重试间隔的不同策略每种策略都允许你根据已进行的尝试次数来自定义下一次尝试前的等待时间。定义位于 retry_util.rs#[derive(Debug, Clone)] pub enum Backoff { Linear(Duration), Exponential(Duration), Fixed(Duration), }三个变体的语义如下变体说明默认Linear(Duration)等待时间随每次尝试线性增长是Default为Linear(10ms)Exponential(Duration)等待时间随每次尝试翻倍Fixed(Duration)尝试之间使用恒定等待时间具体的等待时间由wait_duration计算见 retry_util.rs其中attempt从 0 开始计数impl Backoff { pub fn wait_duration(self, attempt: u32) - Duration { match self { Backoff::Linear(base_duration) *base_duration * (attempt 1), Backoff::Exponential(base_duration) *base_duration * 2u32.pow(attempt), Backoff::Fixed(interval) *interval, } } }也就是说以基础时长b计Linear(b)第 1、2、3 次重试前分别等待b、2b、3bExponential(b)分别等待b、2b、4bb * 2^attemptFixed(b)恒定等待b。枚举的文档注释中同时给出了三种策略的构造示例let linear_backoff Backoff::Linear(Duration::from_secs(2)); let exponential_backoff Backoff::Exponential(Duration::from_secs(1)); let fixed_backoff Backoff::Fixed(Duration::from_secs(5));底层实现retry函数与RetryableClient::wrap重试循环的工作方式真正的重试循环实现在retry函数中见 retry_util.rspub(crate) async fn retryFut, T, ShouldRetry( mut action: impl FnMut() - Fut, retry_config: RetryConfig, should_retry: ShouldRetry, ) - T where Fut: FutureOutput T, ShouldRetry: Fn(T) - bool, { let mut last_result None; for attempt in 0..retry_config.max_attempts.into() { let result action().await; if should_retry(result) { last_result Some(result) } else { return result; } tokio::time::sleep(retry_config.interval.wait_duration(attempt)).await; } last_result.expect(should not happen) }从源码结构看有三个行为值得注意should_retry决定是否继续RetryableClient传入的谓词是|result| result.is_err()即任何Err都会触发重试返回最后一次结果即使所有尝试都失败函数也不会返回新的“重试耗尽”错误而是返回最后一次的原始结果last_result调用方拿到的是最后一次请求的真实错误信息最后一次失败后不再 sleep循环内每次失败后都会先 sleep 再进入下一次尝试这一点被单元测试严格验证见下文。哪些请求会被重试RetryableClient内部持有一个FuelClient、一份RetryConfig和一个可选的版本兼容警告见 retryable_client.rs。所有 RPC 方法都通过wrap走同一条路径见 retryable_client.rsasync fn wrapT, Fut(self, action: impl Fn() - Fut) - RequestResultT where Fut: FutureOutput io::ResultT, { retry_util::retry(action, self.retry_config, |result| result.is_err()) .await .map_err(|e| { let msg if let Some(warning) self.prepend_warning { format!({warning}. {e}) } else { e.to_string() }; RequestError::IO(msg) }) }委托列表覆盖了绝大多数节点交互包括health、chain_info、submit、submit_and_await_commit、await_transaction_commit、transaction_status、coins、coins_to_spend、balance、contract_balance、transactions、block、blocks、messages、message_proof、dry_run、estimate_predicates、estimate_gas_price等完整清单见 retryable_client.rs。重试失败后RequestError::IO会被转换为Error::Provider对外抛出。另外RetryableClient::connect_with_fallbacks支持传入多个 URL 作为连接回退底层由FuelClient::with_urls处理并会在连接时比对节点版本版本不兼容时会生成一段版本警告前缀追加到后续请求错误的信息中见 retryable_client.rs。测试用例验证的重试行为retry函数的单元测试位于 retry_util.rs它们恰好验证了上述实现细节可作为行为契约参考returns_last_received_response动作每次都失败返回err1、err2、err3时配置max_attempts 3最终返回最后一次的响应err3stops_retrying_when_predicate_is_satisfiedshould_retry谓词为|res| *res ! 2当动作返回2时立即停止重试不再耗尽剩余次数retry_respects_delay_between_attempts_fixed/_linear/_exponential分别用Fixed(100ms)、Linear(100ms)、Exponential(100ms)配置记录每次尝试的时间戳断言相邻两次尝试之间的间隔不小于base * (attempt1)线性、base * 2^attempt指数或固定值证明wait_duration的计算被严格遵守。实践建议综合文档与源码使用重试机制时可以遵循以下做法显式启用Provider::connect默认max_attempts 1不重试需要重试时必须调用with_retry_config控制总耗时Exponential增长很快max_attempts 5、基础 1 秒时最坏情况仅等待时间就累计约 1 2 4 8 15 秒对延迟敏感的路径建议用Fixed或较小的基数区分网络故障与业务失败由于节点错误目前都以io::Error呈现交易验证失败等确定性错误也会被重试避免为这类调用配置过大的重试预算多节点部署连接不稳定的环境可以结合Provider::connect_with_fallbacks传入多个节点 URL与重试机制叠加提升可用性max_attempts必须大于 0RetryConfig::new(0, ...)会返回错误而非 panic在初始化时做好?传播。相关的其他连接文档可参考 连接外部节点、查询区块链 与 RocksDB 存储重试功能的实现与测试集中在 packages/fuels-accounts/src/provider/retry_util.rs 与 packages/fuels-accounts/src/provider/retryable_client.rs。【免费下载链接】fuels-rsFuel Network Rust SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考