TimeProvider 是 .NET 6 引入的官方时间抽象，通过封装 DateTime.UtcNow 等静态时间源实现解耦；它支持构造函数注入、TestTimeProvider 测试控制及 Task.Delay/Timer 的适配，确保全链路时间可模拟。
TimeProvider 是什么，为什么它能解耦时间依赖
TimeProvider 是 .NET 6 引入的抽象类型（位于 System.TimeProvider 命名空间），用于统一访问系统时钟。它把 DateTime.UtcNow、DateTimeOffset.UtcNow、Stopwatch.GetTimestamp() 等硬编码时间源封装成可替换的接口，让依赖“当前时间”的逻辑不再绑定具体实现。
过去写单元测试时，常靠反射修改静态属性、用 DateTime.Now + 可配置偏移量、或引入自定义 IClock 接口——这些都属于“自己造轮子”。而 TimeProvider 是官方标准抽象，.NET 内置类（如 Timer、Task.Delay 的重载）已逐步支持它，意味着你只需改一处注入点，就能控制整个调用链的时间行为。
如何在业务类中正确使用 TimeProvider
关键不是“用不用”，而是“怎么注入”和“是否漏掉隐式依赖”。推荐构造函数注入 TimeProvider，并避免在方法体内直接调用静态时间属性。
- ✅ 正确：将
TimeProvider作为构造函数参数传入，保存为只读字段 - ❌ 错误：在方法里写
DateTime.UtcNow或TimeProvider.System—— 这会绕过注入，导致测试失效 - ⚠️ 注意：
TimeProvider.System是默认实现，但它是单例且不可 mock；测试时必须显式传入TestTimeProvider或自定义实现
示例：
public class ExpiryChecker
{
private readonly TimeProvider _timeProvider;
private readonly TimeSpan _validDuration;
public ExpiryChecker(TimeProvider timeProvider, TimeSpan validDuration = default)
{
_timeProvider = timeProvider;
_validDuration = validDuration == default ? TimeSpan.FromHours(1) : validDuration;
}
public bool IsExpired(DateTimeOffset created) =>
_timeProvider.GetUtcNow() > created + _validDuration;
}
用 TestTimeProvider 控制时间推进
TestTimeProvider 是 .NET 提供的专用于测试的 TimeProvider 实现，核心能力是“冻结时间”和“手动推进”。它不依赖系统时钟，所有时间操作都基于内部偏移量，因此测试可完全确定、可重复。
- 创建实例后，默认时间是
DateTimeOffset.MinValue，需先调用SetUtcNow()初始化 - 用
Advance(TimeSpan)模拟时间流逝，所有后续GetUtcNow()调用都会返回推进后的时间 - 注意：它不自动触发基于时间的回调（如
Timer），若测试涉及定时器，需配合Timer构造函数中传入该TestTimeProvider
测试片段：
[Fact]
public void IsExpired_returns_true_after_duration()
{
var provider = new TestTimeProvider();
provider.SetUtcNow(new DateTimeOffset(2024, 1, 1, 12, 0, 0, TimeSpan.Zero));
var checker = new ExpiryChecker(provider, TimeSpan.FromMinutes(30));
var created = new DateTimeOffset(2024, 1, 1, 12, 0, 0, TimeSpan.Zero);
Assert.False(checker.IsExpired(created));
provider.Advance(TimeSpan.FromMinutes(31));
Assert.True(checker.IsExpired(created));
}
容易忽略的陷阱：异步延迟与 Timer 的适配
很多时间敏感逻辑藏在异步等待或定时任务里，比如 Task.Delay(5000) 或 new Timer(...)。它们默认使用系统时钟，不会自动感知你注入的 TimeProvider。
-
Task.Delay有重载接受TimeProvider，务必使用：Task.Delay(timeout, cancellationToken, timeProvider) -
Timer构造函数支持传入TimeProvider，但仅限 .NET 7+；旧版本需自行包装或升级 - 第三方库（如 Hangfire、Quartz）通常不识别
TimeProvider，此时仍需 mock 其调度接口，不能指望TestTimeProvider全局生效 - 警惕日志中打印的
DateTime.Now—— 即便业务逻辑用了TimeProvider，日志时间戳若没统一处理，仍会造成测试断言漂移
真正难的不是写一个 TestTimeProvider 实例，而是确保从入口到最深的异步分支，所有时间获取路径都被同一抽象覆盖。漏掉任意一层，测试就可能偶然通过、难以复现失败。
