Java InstantSource 怎样为测试提供可替换的当前时间

如果代码里到处调用 Instant.now() 或 System.currentTimeMillis()，测试就很容易被真实日期、跨天和时钟推进影响。更稳妥的做法是把“现在是什么时刻”变成一个依赖：生产环境注入系统时间源，测试环境注入固定时间源。

官方地址：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/time/InstantSource.html

Java 的 InstantSource 正是这个抽象。它只负责提供当前 Instant，不承诺一定是真实世界的当前时刻，因此可以使用 fixed、offset 和 tick 构造可控来源。

先把当前时间变成可注入依赖

业务类不要在方法内部自行获取系统时间，而是保存一个 InstantSource。这样，业务逻辑只关心“从来源读取一个时间点”，不需要知道这个时间点来自操作系统还是测试夹具。

import java.time.Instant;
import java.time.InstantSource;

final class ExpiringToken {
    private final InstantSource timeSource;

    // 把时间来源作为依赖保存，避免在方法内部硬编码系统时钟。
    ExpiringToken(InstantSource timeSource) {
        this.timeSource = timeSource;
    }

    boolean isExpired(Instant expiresAt) {
        // 业务只读取一个时间点，比较规则仍然由调用方传入。
        return !timeSource.instant().isBefore(expiresAt);
    }
}

这里的关键不是把 Instant.now() 换成另一个静态方法，而是让时间来源成为对象边界的一部分。以后需要测试“刚好过期”时，只需替换构造参数。

生产用 system，测试用 fixed

正式运行时使用 InstantSource.system()，它基于可用的系统时钟提供当前时间。测试时使用 InstantSource.fixed(Instant)，每次读取都会返回同一个时刻，断言不会随着执行时间变化。

import java.time.Instant;
import java.time.InstantSource;

class ExpiringTokenTestExample {
    void testExpiredAtBoundary() {
        // 固定时间让边界测试可重复，避免依赖测试机当前日期。
        Instant fixedNow = Instant.parse("2026-11-08T00:00:00Z");
        InstantSource testSource = InstantSource.fixed(fixedNow);
        ExpiringToken token = new ExpiringToken(testSource);

        // 到达 expiresAt 的瞬间应视为已过期，验证等号边界。
        boolean expired = token.isExpired(fixedNow);
        if (!expired) {
            throw new AssertionError("到期时刻应该返回 true");
        }
    }

    ExpiringToken productionObject() {
        // 生产对象使用系统来源，业务类本身无需感知环境差异。
        return new ExpiringToken(InstantSource.system());
    }
}

fixed 的价值是控制测试输入，不是模拟一个会自动流逝的时钟。如果测试需要观察时间推进，应显式替换依赖或使用偏移来源，不要让测试偷偷读取机器时间。

用 offset 模拟未来和过去

到期、提前续期和历史数据回放经常需要把“现在”向前或向后移动。InstantSource.offset(baseSource, duration) 会在基础来源上增加偏移量，负偏移代表过去，适合构造时间场景而不修改操作系统时钟。

import java.time.Duration;
import java.time.Instant;
import java.time.InstantSource;

final class TimeScenarios {
    static void run() {
        // 先固定一个基准，确保未来和过去场景彼此可复现。
        InstantSource base = InstantSource.fixed(Instant.parse("2026-11-08T00:00:00Z"));
        InstantSource future = InstantSource.offset(base, Duration.ofHours(2));
        InstantSource past = InstantSource.offset(base, Duration.ofHours(-2));

        // 偏移只改变读取到的时间点，不会改变 base 的定义。
        Instant futureNow = future.instant();
        Instant pastNow = past.instant();
        System.out.println(futureNow + " / " + pastNow);
    }
}

生产代码通常不需要把偏移源暴露给业务对象；把它放在测试装配层，就能覆盖“提前两小时”“回到历史时刻”等分支，同时避免把测试逻辑塞进业务实现。

用 tick 固定时间粒度

有些逻辑并不需要纳秒级变化，例如按整秒生成缓存键、按一分钟切换窗口。此时可以用 InstantSource.tick(baseSource, tickDuration) 截断时间。刻度必须为正，且过细的纳秒粒度还要满足 Java API 对整秒可除的限制。

import java.time.Duration;
import java.time.InstantSource;

final class WindowKey {
    private final InstantSource source;

    // 让窗口判断只观察整分钟，减少同一窗口内的时间抖动。
    WindowKey(InstantSource baseSource) {
        this.source = InstantSource.tick(baseSource, Duration.ofMinutes(1));
    }

    String currentKey() {
        // 只把约定粒度的时间转换成键，具体格式按业务决定。
        return source.instant().toString();
    }
}

tick 不是让时间停止，而是让来源只暴露截断后的时间。若业务需要判断严格的过期瞬间，就继续使用原始来源；若业务需要稳定的窗口键，再在边界上使用 tick。

InstantSource 和 Clock 不要混用

InstantSource 只回答“当前的时间点是什么”，接口方法是 instant()。Clock 在此基础上再携带 ZoneId，因此当业务需要生成 ZonedDateTime、读取本地日期或格式化带时区时间时，再把来源转换成时钟。

import java.time.Clock;
import java.time.InstantSource;
import java.time.ZoneId;

final class LocalDateReader {
    static String today(InstantSource source, ZoneId zone) {
        // 只有需要时区解释时才转换为 Clock，避免时间点依赖被扩大。
        Clock clock = source.withZone(zone);
        return clock.instant().atZone(clock.getZone()).toLocalDate().toString();
    }
}

因此可以按依赖需要选择：只做过期比较、签发时间和持久化时传 InstantSource；需要时区语义时传 Clock 或在边界处调用 withZone。不要为了方便在所有类里都传入时区钟。

一张表记住选择边界

最小原则是：先把时间依赖放在边界，再按测试场景选择来源。这样过期判断、时间窗口和本地日期都能使用明确的输入，测试也不会因运行当天不同而改变结果。

相关问题

InstantSource.fixed 会自动推进吗？

不会。它始终返回传入的同一个 Instant，适合稳定断言；需要推进时应替换来源，或在测试装配层使用偏移来源重新构造对象。

InstantSource 能替代所有 System.currentTimeMillis 吗？

不能机械替换。若业务确实需要毫秒长整型，可以调用 millis()；新设计更适合尽早使用 Instant，避免在业务层丢失时间类型信息。

tick 适合严格过期判断吗？

通常不适合。tick 会截断可见时间，适合窗口或缓存键；严格的到期比较应使用系统来源或测试中明确固定的精确来源。