Aore.Toolkit 1.0.0

Aore.Toolkit

零依赖的 .NET 通用工具库：面向「函数处理 + 集合操作」，覆盖函数处理管线（防抖、节流、记忆化缓存、重试、限流、熔断器）、对象池、带缓存反射、线程安全单例、迭代器与双向链表 / 列表 / 队列 / 堆栈等集合工具。

• 零 NuGet 依赖：核心库不引用任何第三方包，算法、反射加速、并发原语一律本地实现。
• 7 个目标框架：netstandard2.0 / net462 / net472 / net48 / net8.0 / net9.0 / net10.0。
• 生产就绪基线：0 错误 0 警告编译、单元测试覆盖 net48 + net8.0、中文 XML 注释（IntelliSense 友好）。

本文档是 NuGet 包内嵌说明文档（PackageReadmeFile），每次新增模块后请同步更新本文档的「能力清单」「API 方法清单」「API 完整使用方法」与「注意事项」。

能力清单

安装

dotnet add package Aore.Toolkit

或从源码引用：将 src/Aore.Toolkit 工程作为项目引用加入解决方案。

快速上手

using Aore.Toolkit.Pooling;
using Aore.Toolkit.Reflection;
using Aore.Toolkit.Collections;
using Aore.Toolkit.Functions;
using Aore.Toolkit.Resilience;

// 迭代器工具：惰性序列 + 迭代器模式游标
Iterator.Range(1, 3);                  // 1, 2, 3（惰性）
Iterator.Window(items, 3);             // 滑动窗口
var cursor = Iterator.Create(items);   // 可重置读游标

// 双向链表：任意位置 O(1) 插入 / 移动（LRU 核心结构）
var order = new DoublyLinkedList<string>();
order.MoveToFront("A");

// 通用对象池：复用高频对象，减少内存分配
var sb = ObjectPool.StringBuilderPool.Rent();
try
{
  sb.Append("Aore").Append('.');
  // ...
}
finally
{
  ObjectPool.StringBuilderPool.Return(sb);   // 自动 Clear()
}

// 带缓存反射：命中后零反射分配
var getter = ReflectionCache.GetPropertyGetter(typeof(User), nameof(User.Name));
var userName = (string)getter(user);

// 函数缓存（记忆化）：LRU + 命中率统计
var cache = ((Func<string, Type>)ResolveType).Memoize(capacity: 128);
cache.Get("User");
Console.WriteLine(cache.HitRate);

// 限流与熔断：保护下游
if (!bucket.TryAcquire()) { return TooManyRequests(); }   // 令牌桶
var user = breaker.Execute(() => UserService.Get(1));    // 熔断保护

API 方法清单

ObjectPool（Aore.Toolkit.Pooling，通用对象池）

ReflectionCache（Aore.Toolkit.Reflection，带缓存反射工具）

单例（Aore.Toolkit.Patterns）

Iterator / EnumerableIterator（Aore.Toolkit.Collections，迭代器）

DoublyLinkedList（Aore.Toolkit.Collections，双向链表）

ListExtensions（Aore.Toolkit.Collections，列表操作与扩展）

QueueExtensions / Deque（Aore.Toolkit.Collections，队列工具）

StackExtensions / MinMaxStack（Aore.Toolkit.Collections，堆栈工具）

FuncExtensions（Aore.Toolkit.Functions，函数处理相关方法）

Debouncer / Throttle（Aore.Toolkit.Functions，防抖与节流）

Memoizer（Aore.Toolkit.Functions，函数缓存 / 记忆化）

IClock（Aore.Toolkit.Resilience，时间源）

Timing（Aore.Toolkit.Timing，时间与调度）

IRateLimiter（Aore.Toolkit.Resilience，限流机制）

CircuitBreaker（Aore.Toolkit.Resilience，熔断器模式）

集合选型速查

API 完整使用方法

ObjectPool（通用对象池）

// 1) 内置 StringBuilder 池（归还时自动 Clear）
var sb = ObjectPool.StringBuilderPool.Rent();
try
{
  sb.Append("Aore.Toolkit");
}
finally
{
  ObjectPool.StringBuilderPool.Return(sb);
}

// 2) 自定义池：工厂 + 复位回调 + 容量上限 + 预热
var pool = new ObjectPool<List<string>>(
  () => new List<string>(16),                 // 工厂
  list => list.Clear(),                        // 复位回调
  maxRetained: 64,
  preRent: 8);                                 // 预热 8 个（受 maxRetained 约束）

var list = pool.Rent();
list.Add("x");
pool.Return(list);                             // 复位后入池

// 3) 全局共享池：同一 T 只有一个池实例
var shared = ObjectPool.For<MemoryStream>();
ObjectPool.ClearSharedPools();                 // 内存压力回落 / 测试隔离

ReflectionCache（带缓存反射）

// 元数据查找（命中后不再触发反射）
var prop = ReflectionCache.GetProperty(typeof(User), nameof(User.Name));   // 不存在返回 null
var method = ReflectionCache.GetMethod(typeof(User), nameof(User.Save), new[] { typeof(string) });
var element = ReflectionCache.GetElementType(typeof(List<int>));          // int
ReflectionCache.GetDefaultValue(typeof(DateTime));                        // 0001-01-01

// 缓存的读写委托（表达式树编译，命中后接近字段访问速度）
var getter = ReflectionCache.GetPropertyGetter(typeof(User), nameof(User.Name));
var setter = ReflectionCache.GetPropertySetter(typeof(User), nameof(User.Name));
var user = new User();
setter!(user, "Aore");
string? name = (string?)getter(user);

// 链式扩展方法形态
user.SetPropertyValue(nameof(User.Name), "Willis");
var value = user.GetPropertyValue(nameof(User.Name));

// 只读属性 / 缺失成员
ReflectionCache.GetPropertySetter(typeof(User), nameof(User.Id));         // null（只读）
ReflectionCache.GetPropertyGetter(typeof(User), "NotExist");              // 抛 MissingMemberException

ReflectionCache.Clear();                                                  // 清空进程级缓存

// 插件卸载 / Collectible ALC：按类型精准清除，防止程序集被缓存条目钉住
ReflectionCache.Clear(typeof(User));

// 可选：启用条目总数预警水位（软上限，越线按 Type FIFO 自动驱逐最旧类型；默认 0 = 关闭）
ReflectionCache.HighWaterMark = 50_000;

单例

// 继承式单例基类（推荐：可加初始化钩子与释放逻辑）
public sealed class AppConfig : SingletonBase<AppConfig>
{
  public string Endpoint { get; private set; } = "https://default";

  protected override void OnSingletonCreated() => Endpoint = Environment.GetEnvironmentVariable("ENDPOINT") ?? Endpoint;
}

var config = AppConfig.Instance;

// 普通泛型单例（无需继承）
var helper = Singleton<JsonHelper>.Instance;

Iterator / EnumerableIterator（迭代器）

// 惰性序列
Iterator.Empty<int>();                                // 空序列（零分配共享单例）
Iterator.Repeat("A", 3);                              // A A A
Iterator.RepeatSequence(new[] { 1, 2 }, 2);           // 1 2 1 2
Iterator.Range(1, 3);                                 // 1 2 3
Iterator.Range(10, 0, -2);                            // 10 8 6
Iterator.Range(0, 10, -1);                            // 空（方向不匹配，不死循环）
Iterator.Range(int.MaxValue, 2);                      // 抛 ArgumentOutOfRangeException

Iterator.Batch(new[] { 1, 2, 3, 4, 5 }, 2);           // [1,2] [3,4] [5]
Iterator.Window(new[] { 1, 2, 3 }, 2);                // [1,2] [2,3]

// 无限序列需自行截断
Iterator.Repeat(1).Take(3);                           // 1 1 1
Iterator.Cycle(new[] { 1, 2 }).Take(3);               // 1 2 1

// 迭代器模式游标：HasNext 不推进位置
var cursor = Iterator.Create(new[] { 1, 2, 3 });
cursor.HasNext;                                       // true（位置仍为 0）
while (cursor.MoveNext())
{
  var item = cursor.Current;
}
cursor.Position;                                      // 3
cursor.Reset();                                       // 可重复遍历

// 游标同时是 IEnumerable<T>，可直接接 LINQ
var even = ((EnumerableIterator<int>)Iterator.Create(Enumerable.Range(1, 5))).Where(x => x % 2 == 0);

DoublyLinkedList（双向链表）

using Aore.Toolkit.Collections;

// 头尾插入，节点可被外部持有
var list = new DoublyLinkedList<string>();
var node = list.AddLast("B");
list.AddFirst("A");
list.AddAfter(node, "C");              // A, B, C
list[node] = "BB";                      // 按节点读写：A, BB, C

// 任意位置 O(1) 移动（保持同一节点实例，外部引用不失效）
list.MoveToFirst(node);                // BB, A, C
list.MoveBefore(node, list.Last!);      // A, BB, C

// 遍历（含反向）
list.ForEach(x => Console.WriteLine(x));
list.ForEachBackward(x => Console.WriteLine(x));   // C, BB, A

// 节点移出后导航清空，避免悬挂引用
list.Remove(node);
Console.WriteLine(node.List);          // null
Console.WriteLine(node.Previous);      // null

LRU 缓存（双向链表 + 字典，两行核心逻辑）

var order = new DoublyLinkedList<string>();      // 最近使用在前
var store = new Dictionary<string, byte>();

void Touch(string key)
{
  if (store.ContainsKey(key))
  {
    order.MoveToFront(key);                       // 命中 → 提到最前
  }
  else
  {
    store[key] = 0;
    order.MoveToBack(key);                        // 新增 → 放到最后（最旧）

    if (order.Count > 3)                          // 超容量 → 淘汰最旧
    {
      var oldest = order.Last!.Value;
      order.RemoveLast();
      store.Remove(oldest);
    }
  }
}

ListExtensions（列表操作与扩展）

IList<int> numbers = new List<int> { 5, 3, 8, 1, 9, 2 };

numbers.RemoveWhere(x => x < 3);           // 5, 8, 9, 2（返回删除数）
numbers.Swap(0, numbers.Count - 1);        // 2, 8, 9, 5
numbers.ReverseInPlace();                  // 5, 9, 8, 2
numbers.InsertRange(0, new[] { 0 });       // 0, 5, 9, 8, 2
numbers.ReplaceRange(1, new[] { 7, 8 });   // 0, 7, 8, 8, 2
numbers.Fill(-1, 1, 2);                    // 0, -1, -1, 8, 2

var blocks = numbers.Chunk(2);             // 惰性分块
numbers.ShuffleInPlace(new Random(42));    // 原地洗牌（Fisher-Yates）
var sorted = numbers.Shuffled().OrderBy(x => x);

numbers.At(99);                            // 越界安全取值 → default(T) = 0
numbers.IsInRange(0);                      // true
numbers.TryEnsureCapacity(1024);           // List<T> 专用，返回是否扩容

var sortedList = new List<int> { 1, 3, 5, 7 };
sortedList.BinarySearchIndex(5);           // 2（命中）
sortedList.BinarySearchIndex(6);           // 负数（~插入点）

QueueExtensions / Deque（队列工具）

var queue = new Queue<int>();
queue.EnqueueRange(new[] { 1, 2, 3, 4 });  // 批量入队
queue.DequeueWhile(x => x < 3);            // 出队 1, 2（返回 2），剩余 3, 4
queue.DequeueRange(10);                    // 取尽 → [3, 4]
queue.DequeueAll();                        // []

// 双端队列
var deque = new Deque<string>();
deque.PushBack("B");
deque.PushFront("A");
deque.PushBack("C");
deque.PeekFront();                        // A
deque.PopBack();                          // C
deque.TryPopBack(out var tail);           // B → true（空时返回 false）

StackExtensions / MinMaxStack（堆栈工具）

var stack = new Stack<int>();
stack.PushRange(new[] { 1, 2, 3 });       // 栈顶为 3
stack.PopWhile(x => x > 2);               // 弹出 3（返回 1）
stack.TryPop(out var top);                // 2 → true

// O(1) 最值栈（滑动窗口最值场景）
var window = new MinMaxStack<int>();
foreach (var v in new[] { 4, 2, 9, 6 })
{
  window.Push(v);
}

window.GetMin();                          // 2
window.GetMax();                          // 9
window.Pop();
window.GetMax();                          // 6（自动回退）

// 自定义比较器（降序）
var desc = new MinMaxStack<int>(Comparer<int>.Create((x, y) => y.CompareTo(x)));

FuncExtensions（函数处理）

using Aore.Toolkit.Functions;

// 安全调用：捕获可恢复异常，OutOfMemory 等致命异常仍会抛出
if (!((Action)DoWork).TryInvoke(out var error))
{
  Console.WriteLine(error!.Message);
}

// 事件回调：异常交给处理器，不向外抛
((Action)DoWork).InvokeSafely(ex => Console.WriteLine(ex.Message));

// 兜底取值 / 条件调用
Func<int> parse = () => throw new FormatException("bad");
int value = parse.InvokeOrDefault(-1);
parse.InvokeIf(false, -1);            // -1（不执行 parse）

// 超时调用：超时抛 TimeoutException（返回值版本返回兜底值）
((Func<int>)SlowCall).InvokeWithTimeout(TimeSpan.FromSeconds(2), fallback: -1);

// 同步重试：第 3 次成功；耗尽后重抛最后一次异常
Func<string> call = () => RemoteGet();
var body = call.Retry(maxAttempts: 3, delay: TimeSpan.FromMilliseconds(200));

// 自定义重试条件：不可恢复的错误立即抛出
call.Retry(maxAttempts: 5, shouldRetry: ex => ex is TimeoutException);

// 异步重试（支持取消）
await ((Func<Task<string>>)RemoteGetAsync).RetryAsync(maxAttempts: 3, cancellationToken: ct);

// 函数组合
Func<string, string> mark = s => s + "?";
Func<string, int> length = s => s.Length;
Func<string, int> composed = mark.Compose(length);   // s => (s + "?").Length

// 无参工厂的单键记忆化（异常也会被缓存）
var loadConfig = ((Func<string>)ReadConfigFile).MemoizeOnce();

Debouncer（防抖）

// 搜索框：连续输入只在停止 300ms 后请求一次
string keyword = string.Empty;
using var debouncer = new Debouncer(() => Search(keyword), TimeSpan.FromMilliseconds(300));

keyword = "aore"; debouncer.Invoke();
keyword = "aore t"; debouncer.Invoke();   // 计时被重置
// ... 300ms 后 Search 只被调用一次，keyword 已是最终值

debouncer.IsPending;   // 是否有待执行动作
debouncer.Flush();      // 立即执行（返回 true），并取消后续定时触发
debouncer.Cancel();     // 放弃本次防抖

Throttle（节流）

// 滚动加载：100ms 内最多触发一次
int offset = 0;
using var throttle = new Throttle(() => LoadMore(offset), TimeSpan.FromMilliseconds(100));

throttle.Invoke();   // true（首次前导执行）
throttle.Invoke();   // false（窗口内被丢弃）
throttle.Invoke();   // false

// 后置模式：窗口结束才执行，适合埋点 / 自动保存
using var saver = new Throttle(() => Save(), TimeSpan.FromMilliseconds(500), ThrottleMode.Trailing);
saver.Invoke();      // false（不立即执行）
// 500ms 内多次调用只会在窗口结束时执行一次

Memoizer（函数缓存 / 记忆化）

// 得到可管理的缓存对象：查看命中率、失效、清空
Func<string, Type> resolve = name => AssemblyScan(name);
var cache = resolve.Memoize(capacity: 256);

cache.Get("User"); cache.Get("User");
Console.WriteLine(cache.HitRate);        // 0.5
cache.Invalidate("User");               // 强制下次重算
cache.Clear();

// 简洁用法：直接拿到替换后的委托
Func<string, Type> cachedResolve = resolve.Memoized(capacity: 256);

// 自定义比较器（大小写不敏感）
var insensitive = resolve.Memoize(capacity: 256, StringComparer.OrdinalIgnoreCase);

// 带有效期：惰性过期（访问时判定，无后台线程）；ttlSelector 可按 key / 值定制每项有效期
var expiring = resolve.Memoize(capacity: 256, ttl: TimeSpan.FromMinutes(5));
var perKey = resolve.Memoize(capacity: 256, ttlSelector: (key, _) => key.StartsWith("temp:") ? TimeSpan.FromSeconds(30) : TimeSpan.FromMinutes(10));

IClock（时间源，可确定性测试）

using Aore.Toolkit.Resilience;

// 系统时钟（默认）
IClock clock = SystemClock.Instance;

// 手动时钟：让所有「等一段时间」的场景变成纯逻辑断言，零 sleep、零偶发
var fake = new ManualClock();
var limiter = new FixedWindowRateLimiter(limit: 2, window: TimeSpan.FromSeconds(1), fake);
limiter.TryAcquire();
limiter.TryAcquire();
limiter.TryAcquire();      // false

fake.Advance(TimeSpan.FromSeconds(1));
limiter.TryAcquire();      // true（窗口已重置）

时间与调度（高精度计时 / 单调预算 / 调度定时器）

using Aore.Toolkit.Timing;

// 高精度计时器（struct 零分配，复制即独立快照）：亚毫秒整数读数 + 全 TFM 可用的 Restart
var stopwatch = ValueStopwatch.StartNew();
DoWork();
stopwatch.Stop();
Console.WriteLine($"{stopwatch.ElapsedMilliseconds}ms / {stopwatch.ElapsedMicroseconds}µs");
stopwatch.Restart();                                    // 清零重新走表（ns2.0 也有）

// 时间戳差值与作用域测量（.NET 7+ GetElapsedTime 下放全 TFM）
var start = Monotonic.GetTimestamp();
await Task.Delay(100);
var elapsed = Monotonic.GetElapsedTime(start);
var measured = Monotonic.Measure(() => Thread.Sleep(50));   // 一行测耗时

// 单调截止预算：跨多次 await 的超时检查（与 CancellationTokenSource 墙钟超时互补）
var deadline = MonotonicDeadline.FromNow(TimeSpan.FromSeconds(5));
foreach (var item in items)
{
    deadline.ThrowIfExpired();                              // 到期抛 TimeoutException
    await ProcessAsync(item);
}

// 调度定时器：回调永不重叠、异常不击穿进程、支持异步回调
using var timer = new ScheduleTimer(
    async token => await HeartbeatAsync(token),
    TimeSpan.FromSeconds(10),                               // FixedDelay：上次完成后隔 10s 再跑
    options: new ScheduleOptions { Name = "heartbeat", OnError = ex => Log(ex) });

// 固定速率防漂移：错过节拍跳过不补发（SkippedCount 累计）
using var meter = new ScheduleTimer(PollAsync, TimeSpan.FromMilliseconds(250), ScheduleMode.FixedRate);

// 一次性延迟执行
var once = ScheduleTimer.ScheduleOnce(() => Console.WriteLine("40ms 后"), TimeSpan.FromMilliseconds(40));

// PeriodicTimer 风格的 awaitable 接口（全 TFM 可用）
while (await timer.WaitForNextTickAsync(cancellationToken))
{
    await HandleTickAsync();
}

限流（4 种算法）

// 令牌桶：允许 capacity 突发，长期按 permitsPerSecond 均速
var bucket = new TokenBucketRateLimiter(capacity: 100, permitsPerSecond: 50);
if (!bucket.TryAcquire())
{
  // 降级：返回缓存 / 排队 / 提示稍后重试
}
var wait = bucket.WaitTimeFor();      // 建议等待时长（Zero = 当前可获得）

// 固定窗口：开销最小，窗口边界可 2 倍突发
var fixedWindow = new FixedWindowRateLimiter(limit: 100, window: TimeSpan.FromSeconds(1));

// 滑动窗口：精确计数，边界平滑；内存 O(limit)
var sliding = new SlidingWindowRateLimiter(limit: 100, window: TimeSpan.FromSeconds(1));

// 并发限制：限制同时在途请求数
var slots = new ConcurrencyRateLimiter(maxConcurrency: 8);
if (slots.TryAcquire())
{
  try
  {
    CallDownstream();
  }
  finally
  {
    slots.Release();     // 必须配对归还
  }
}

// 阻塞 / 异步等待
bucket.Acquire(timeout: TimeSpan.FromSeconds(2));       // 超时抛 TimeoutException
await bucket.WaitAsync(cancellationToken: ct);          // 异步等待

// 按配置统一创建
IRateLimiter limiter = RateLimiterFactory.Create(new RateLimitOptions
{
  Algorithm = RateLimiterAlgorithm.TokenBucket,
  Permits = 100,
  Window = TimeSpan.FromSeconds(1),
});

熔断器（快速失败）

using Aore.Toolkit.Resilience;

var breaker = new CircuitBreaker(new CircuitBreakerOptions
{
  FailureThreshold = 5,                       // 连续 5 次失败后打开
  BreakDuration = TimeSpan.FromSeconds(30),   // 打开持续 30s
  HalfOpenTrialCount = 2,                     // 半开放行 2 个试探
  SuccessThreshold = 2,                       // 成功 2 次后闭合
  OnStateChanged = state => Metrics.Track("circuit", state),   // 锁内同步，别做耗时操作
});

try
{
  var user = breaker.Execute(() => UserService.Get(1));        // 自动上报
}
catch (CircuitOpenException ex)
{
  // ex.State / ex.RetryAfter 告诉你「现在别打，稍后再来」
  return Fallback();
}
catch (HttpRequestException ex)
{
  // 业务异常原样透传，已计入失败
}

// 异步版：取消（OperationCanceledException）不计入失败
var user = await breaker.ExecuteAsync(() => UserService.GetAsync(1));

// 手动模式（自定义判定逻辑）
if (breaker.TryAcquire())
{
  try
  {
    DoWork();
    breaker.ReportSuccess();
  }
  catch
  {
    breaker.ReportFailure();
    throw;
  }
}

// 指标快照
var snap = breaker.Snapshot;
Console.WriteLine($"{snap.State} calls={snap.TotalCalls} fails={snap.TotalFailures} rejected={snap.RejectedCalls}");

// 按下游隔离状态
var registry = new CircuitBreakerRegistry(new CircuitBreakerOptions { FailureThreshold = 2 });
registry.Get("user-service").Execute(() => CallUserService());
registry.Get("order-service").Execute(() => CallOrderService());

// 容量软上限：超限按创建序只淘汰 Closed 态（Open / HalfOpen 与本次新建绝不淘汰）；下游下线可手动移除
var bounded = new CircuitBreakerRegistry(new CircuitBreakerOptions { FailureThreshold = 2 }, maxBreakers: 32);
bounded.Remove("offline-service");

注意事项

1. null 约定：本库不提供公共参数校验与字符串扩展工具（模板示例模块已移除）。参数校验请直接使用 ArgumentNullException.ThrowIfNull（net6+）或手写 if (x is null) throw new ArgumentNullException(nameof(x));；字符串判空请用 string.IsNullOrWhiteSpace。本库各方法的 null 语义差异（null 安全 / 要求非 null）均在 XML 注释标注。

2. 异常约定：公共 API 优先抛标准异常（ArgumentNullException / ArgumentException / ArgumentOutOfRangeException / MissingMemberException / AmbiguousMatchException / TimeoutException / InvalidOperationException），并尽量携带 paramName；唯一专用异常是熔断快速失败的 CircuitOpenException（携带 State / RetryAfter）。

3. 对象池不释放实例：Trim / Clear 只丢弃不调用 IDisposable.Dispose，池不擅自释放以避免二次释放；需要清理请放在复位回调中。

4. 对象池容量：maxRetained = 0 表示关闭池化（每次都新建）；preRent 会被 maxRetained 截断。命中率 = 1 - CreatedCount / 租用总次数。

5. 反射缓存是进程级共享：ReflectionCache.Clear() 供动态程序集卸载 / 插件热重载 / 测试隔离使用；缓存持有 Type 引用，请勿在卸载场景下依赖默认行为。

6. 反射方法查找范围：GetMethod 依赖 Type.GetMethods 语义，可查到继承的 public / protected 方法，但不包含基类的 private 方法；属性与字段查找则显式遍历基类全链。

7. Aore.Toolkit.Reflection 命名空间与 System.Reflection 同名段：在该命名空间内请统一写 using System.Reflection; 并使用 Type / MethodInfo 等裸类型名，不要写 Reflection.Xxx。

8. 单例 Reset() 仅供测试：SingletonBase<T>.Reset() / Singleton<T>.Reset() 会破坏单例语义（外部可能仍持有旧实例），生产代码禁止调用；释放资源请用 DisposeInstance()。

9. 无限序列：Iterator.Repeat(value) 与 Iterator.Cycle(source) 返回无限序列，必须自行截断（例如 Take(n)），否则 foreach 不会结束。

10. 游标线程安全：EnumerableIterator<T> 与 BCL 枚举器一致，非线程安全，请勿跨线程共享。

11. 集合容器线程安全：DoublyLinkedList<T> / Deque<T> / MinMaxStack<T> 均非线程安全（与 BCL 集合一致），需要并发安全请由调用方加锁。

12. 扩展方法同名遮蔽：部分扩展方法在 net6+ 会被同名 BCL 实例方法遮蔽（实例方法优先）——GetRange / InsertRange / TryPop 等。库内已对齐语义与异常类型；调用方若需明确指定，请用静态调用形式（如 ListExtensions.TryPop(stack, out var v)）。

13. 反向/原地语义：ReverseInPlace / ShuffleInPlace / Shuffled（前者就地修改，后者返回副本）。

14. 超时不能中止：InvokeWithTimeout 只保证「调用方不再等待」，已启动的工作会继续在后台运行（异常会被观察，不会触发 UnobservedTaskException）。需要真正中止请自行传入 CancellationToken。

15. 定时器必须释放：Debouncer / Throttle 的 Timer 懒建但生命周期跟随实例，请用 using / Dispose() 释放；动作异常<b>默认被吞</b>，强烈建议传 onError 回调。

16. 记忆化与防抖的适用边界：MemoizeOnce 只适用于无参工厂（带参数请用 Memoize / Memoized）；Memoizer 并发同 key 允许重复计算，工厂应无副作用；Retry 的 Thread.Sleep 会阻塞调用线程，长耗时场景请用 RetryAsync。

17. 目标框架：所有 API 在 7 个 TFM 上行为一致；垫片（Compatibility/NullableAttributes.cs）保证旧框架下的可空注解编译，无运行时开销。net462 不内置 ValueTuple，本库缓存键使用自定义结构体以保持零依赖。

18. 限流只返回 false：TryAcquire 被拒时不抛异常（避免异常风暴）；只有 Acquire 在超时后才抛 TimeoutException。permits 大于限流器配额属配置错误，会一直拿不到许可。

19. 熔断器不含重试：CircuitBreaker.Execute* 不内置重试——熔断期间重试只会放大下游压力。重试用 FuncExtensions.Retry* 组合，且只对「非 CircuitOpenException」重试。

20. 熔断状态是惰性迁移：State 读取本身不触发迁移，Open → HalfOpen 的迁移发生在 TryAcquire 中，因此判定权威入口是 TryAcquire。

21. 时间行为可测：限流与熔断的全部时间判定走 IClock，传入 ManualClock 即可在零 sleep的前提下确定性验证（库自身的测试即如此）。

22. 仅单进程生效：限流与熔断都是进程内状态，集群下每个实例各限各的；分布式场景需外部存储（属非目标）。

23. 线程安全：无状态静态工具（Iterator / ReflectionCache / FuncExtensions）天然线程安全；ObjectPool 加锁、SingletonBase 用 Lazy<T>、Debouncer / Throttle / Memoizer / 全部限流器 / CircuitBreaker / CircuitBreakerRegistry 均为线程安全实现；集合容器与游标除外（见第 10 / 11 条）。

24. 内部类型不是公共 API：Aore.Toolkit.Internal 命名空间下的类型（如参数守卫）属实现细节，随版本可变更，不保证向后兼容。

25. 重试不重试取消异常：Retry / Retry<T> / RetryAsync / RetryAsync<T> 遇到 OperationCanceledException（含 TaskCanceledException）立即原样抛出，不消耗剩余重试次数；需重试取消场景请自行在 shouldRetry 之外处理。

26. 熔断中的取消不计成功也不计失败：CircuitBreaker.ExecuteAsync* 遇到 OperationCanceledException 只清零连续失败并原样抛出，不会被记为下游成功（避免 InvokeWithTimeout 产生的超时把熔断计数清零）。

27. Acquire 的超时是真实墙钟：IRateLimiter.Acquire(permits, timeout) 的 timeout 由内部 Stopwatch 判定，不受注入的 IClock 影响（否则传入 ManualClock 会永不超时）；单次等待时长仍由 IClock 决定。

28. 限流请求量不得超过配额：SlidingWindowRateLimiter 的 WaitTimeFor(permits > Limit) / Acquire 会抛 ArgumentOutOfRangeException（该请求量本质不可满足，快速失败而非空转）；其余限流器 TryAcquire 一律返回 false 不抛异常。

29. CircuitBreaker.Execute 重载选择：() => Foo() 这类有返回值的表达式体 lambda 会按 C# 规则绑定到 Execute<T> 而非 Execute(Action)；需明确执行 Action 版本请写成 Action act = () => Foo();。

30. 枚举器耗尽安全：全部 struct 枚举器（DoublyLinkedList<T>.Enumerator / Deque<T>.Enumerator / MinMaxStack<T>.Enumerator）在未开始或已越界时 Current 返回 default(T)，不抛异常。

31. ReflectionCache 不适用于裁剪 / NativeAOT：属性 / 字段 / 方法在裁剪后可能被移除，GetProperty 等会返回 null、GetValue 会抛 MissingMemberException；Expression.Compile() 在不支持动态代码的平台已自动降级为反射访问（性能下降但功能正确）。

32. EnumerableIterator<T> 双重身份：类型同时是游标（IIterator<T>）与序列（IEnumerable<T>）。作为序列枚举（foreach / LINQ）时返回独立新游标，不会重置本实例的 Position / Current。

33. DoublyLinkedList<T> 自定义比较器：如需非默认比较（如大小写不敏感），用 new DoublyLinkedList<T>(source, comparer)；Find / Remove(T) / Contains 均按该比较器判定。

34. SingletonBase<T>.Dispose() 会重置单例：释放的正是当前单例实例时会原子丢弃缓存引用，下次 Instance 重新构造（等价于 DisposeInstance()）。

35. 缓存键空间由调用方控制：ReflectionCache（按 Type / 成员）、ObjectPool 共享池（按泛型实参）、CircuitBreakerRegistry（按名称）的条目随使用增长，键空间有限时收敛；以动态键（动态生成类型、per-user / per-request 命名）访问会导致条目无限增长。管控选型：手动清理是地基（ReflectionCache.Clear(type) / Registry.Remove(name) / Clear() / ObjectPool.RemoveShared<T>()），容量管控是无人运维场景的兜底（ReflectionCache.HighWaterMark / Registry 的 maxBreakers，均为默认关闭的软上限），TTL 只属于业务值缓存（Memoizer）；本库不内置定时清扫线程。

36. Collectible AssemblyLoadContext 卸载前先清缓存：ReflectionCache 条目持有 Type / MemberInfo / 编译委托引用，只要条目存在，可卸载程序集就被钉住无法卸载。插件卸载前调用 ReflectionCache.Clear(pluginType)（或全量 Clear()）；被清条目后续访问自动重反射，正确性不受影响。ObjectPool.RemoveShared(type) 可同步退场插件创建的共享池。

37. 自动管控是软上限且有驱逐语义：HighWaterMark 越线按 Type 插入序 FIFO 驱逐（每 64 次访问摊销检查，被驱逐条目重新反射 + 重编译，一次性性能毛刺）；maxBreakers 超限按创建序只淘汰 Closed 态（Open / HalfOpen 与本次新建绝不淘汰，无可淘汰条目时暂时超限，被淘汰熔断器状态丢失、同名重建归零）。

38. Memoizer TTL 语义：ttl（默认有效期）与 ttlSelector（按 key / 值定制，优先于 ttl）均缺省 = 永不过期（与旧版行为一致）；惰性过期无后台线程——访问时按注入 IClock 的单调毫秒判定，过期条目视同不存在并顺带移除，Get 重新计算并计入 Misses；容量压力下优先淘汰已过期条目；有效期必须为正时间跨度，选择器返回非正抛 ArgumentOutOfRangeException；测试注入 ManualClock 可零 sleep 确定性验证。

39. Timing 的刻度不是 TimeSpan 刻度：Monotonic.GetTimestamp / ValueStopwatch.ElapsedTicks 为 Stopwatch 刻度（平台频率相关），跨度换算必须经由 Monotonic.TimestampToNanoseconds / GetElapsedTime；ValueStopwatch 为 struct——赋值 / 传参即独立快照（非引用共享）；Monotonic.Resolution 按 100ns 粒度量化（GHz 级计数器下为 1 tick 下限）。静态门面类名为 Monotonic 而非 Timing（避开与命名空间同名）。

40. ScheduleTimer 的防重叠与防漂移：FixedDelay 上次回调完成后再计间隔（推荐默认，天然防重叠）；FixedRate 按节拍点排程，回调未完成错过节拍时跳过不补发（SkippedCount 累计，补发会造成突发风暴）；回调（含 async）永不重叠；异常交给 OnError（缺省吞掉并计 ErrorCount）绝不击穿进程；间隔为亚毫秒时取 1ms 下限；全部节拍判定基于单调毫秒（无 49 天回绕）。Dispose 幂等不抛（与 Debouncer / Throttle 的 ObjectDisposed 语义刻意不同）并取消在途回调令牌。

41. WaitForNextTickAsync 是多播语义：同一节拍唤醒当前全部等待者；节拍在「回调开始执行」与「跳过节拍」时发生（不以回调完成为准）；未等到节拍的调用方不保留历史节拍；Dispose / 达到 MaxExecutions 后返回 false 结束循环。

支持框架：netstandard2.0、net462、net472、net48、net8.0、net9.0、net10.0。