README.md

Zongsoft.Externals.Polly 扩展插件库

English | 简体中文

---

概述

该插件库基于 Polly 开源库的插件化适配，并针对相关回调方法做了统一的抽象和映射：

• RetryFeature ⇢ Polly.RetryStrategyOptions
• TimeoutFeature ⇢ Polly.TimeoutStrategyOptions
• BreakerFeature ⇢ Polly.CircuitBreakerStrategyOptions
• ThrottleFeature ⇢ ThrottleStrategyOptions (重写)
• FallbackFeature ⇢ FallbackStrategyOptions (重写)

模式

核心库 的 执行器 根据执行方法的 参数 和 返回值类型 定义了三种执行模式：

• 同步 执行

  1. 无参 且 无返回：
     • IExecutor Build(Action execute);
     • IExecutor Build(Action<Parameters> execute);
  2. 有参 且 无返回：
     • IExecutor<TArgument> Build<TArgument>(Action<TArgument> execute);
     • IExecutor<TArgument> Build<TArgument>(Action<TArgument, Parameters> execute);
  3. 有参 且 有返回：
     • IExecutor<TArgument, TResult> Build<TArgument, TResult>(Func<TArgument, TResult> execute);
     • IExecutor<TArgument, TResult> Build<TArgument, TResult>(Func<TArgument, Parameters, TResult> execute);

• 异步 执行

  1. 无参 且 无返回：
     • IExecutor Build(Func<CancellationToken, ValueTask> execute);
     • IExecutor Build(Func<Parameters, CancellationToken, ValueTask> execute);
  2. 有参 且 无返回：
     • IExecutor<TArgument> Build<TArgument>(Func<TArgument, CancellationToken, ValueTask> execute);
     • IExecutor<TArgument> Build<TArgument>(Func<TArgument, Parameters, CancellationToken, ValueTask> execute);
  3. 有参 且 有返回：
     • IExecutor<TArgument, TResult> Build<TArgument, TResult>(Func<TArgument, CancellationToken, ValueTask<TResult>> execute);
     • IExecutor<TArgument, TResult> Build<TArgument, TResult>(Func<TArgument, Parameters, CancellationToken, ValueTask<TResult>> execute);

以上三种执行模式分别对应了三种 执行管线 IFeaturePipeline，本插件库的 FeaturePipeline (0, 1, 2) 则依次对应了三种执行管线的实现。

由于 Polly 库 8.6.5 版本 在相应策略回调中并没有包含原始执行参数，所以在 BreakerFeature<TArgument> 和 BreakerFeature<TArgument, TResult> 的 Opened 回调函数中的，是无法获得对应 BreakerOpenedArgument<TArgument>.Value 和 BreakerOpenedArgument<TArgument, TResult>.Value 属性值，其 Closed 回调函数亦同样如此。

由于本插件库重写了 限流 和 回退 两种策略，因此可以在它们的回调方法中获取到原始执行参数的值，即通过 Argument<T>.Value 或 Argument<T, TResult>.Value 属性。

• ThrottleFeature<TArgument>.Rejected 和 ThrottleFeature<TArgument, TResult>.Rejected
• FallbackFeature<TArgument>.Fallback 和 FallbackFeature<TArgument, TResult>.Fallback

💡 提示： 限流的 Rejected 回调方法返回 true，表示已经处理完成，即执行器不会再抛出限流被拒绝异常。

其他说明

🚨 注意： 相关回调方法的签名应与执行方法的签名模式一致，因为 Polly 库底层的 ResiliencePipelineBuilder 与 ResiliencePipelineBuilder<T> 限制，因为如果不同模式的 IFeaturePipeline 无法构建不兼容的 Features，具体实现请参考：

• FeaturePipeline 类的构造函数 与 FeatureExtension 类的
  AddStrategy(ResiliencePipelineBuilder builder, IFeature feature) 方法。
• FeaturePipeline~1 类的构造函数 与 FeatureExtension 类的
  AddStrategy<TArgument>(ResiliencePipelineBuilder builder, IFeature feature) 方法。
• FeaturePipeline~2 类的构造函数 与 FeatureExtension 类的
  AddStrategy<TArgument, TResult>(ResiliencePipelineBuilder<TResult> builder, IFeature feature) 方法。

💡 提示： 根据上述实现，可观察到带返回值的模式不兼容无返回值的两种执行模式 (有参或无参)；但无返回值模式中的无参和有参两种执行模式则彼此兼容。

使用范例

请参考本插件库的 samples 范例的 README.md 文档。