Привет, Хабр!

Сегодня я хочу поговорить об управлении временем в Java приложениях: зачем это нужно, и как это можно делать.

В реальном коде часто требуется сохранять дату и время в базу данных. Это может быть фиксация времени создания\последней модификации какого-либо объекта или указание срока действия документа, билета и т.п. Думаю, многие из вас решали эту задачу в своих проектах: сама по себе она несложная. Трудности возникают, когда мы хотим подобную систему протестировать и оценить, как она будет вести себя, скажем, через полгода или год. В будущем.

Конечно, можно накручивать системные часы на вашей машине, build-агенте, тестовом сервере, но это неудобно, а иногда физически невозможно (банальное отсутствие доступа или автоматическая синхронизация времени). А ещё это абсолютно не инженерный подход. Ниже я покажу несколько простых и изящных приёмов, которые позволят вам почувствовать себя доктором Стрэнджем…

А что там на уровне СУБД?

Сначала давайте посмотрим, как устроена работа с датой и временем на уровне СУБД, например, PostgreSQL. Это пригодится для дальнейшего понимания концепции, которую я продемонстрирую.

В PostgreSQL метку времени можно получить с помощью функции now() — в пределах одной транзакции она всегда возвращает один и тот же результат. Таким образом, если вы добавляете или изменяете несколько записей в одной транзакции, то у всех из них будет одинаковое время создания/модификации. Это удобно и классно опять же до того момента, пока вам не нужно протестировать поведение системы в другой момент времени.

Современная разработка ПО должна быть управляемой и предсказуемой, а это невозможно без автоматизированного тестирования. Именно по этой причине мы вынуждены отказаться от работы с датой временем на уровне СУБД и вынести её на уровень приложения.

Больше никаких вызов now() без параметров

Начиная с 8-й версии Java, нам доступен современный и удобный API для работы со временем. Эта тема неоднократно рассматривалась на Хабре. Подробнее можно почитать тут и тут.

Типовой подход в Java для получения даты или времени заключается в использовании статических методов now(). Я видел такой код сотни раз в разных проектах.

И вот первая рекомендация: откажитесь от использования now() без параметров в вашем коде. Всегда и везде нужно использовать перегруженную версию, принимающую на вход объект Clock:

Clock clock = Clock.systemUTC();
LocalDate date = LocalDate.now(clock);
LocalDateTime time = LocalDateTime.now(clock);
OffsetDateTime offsetTime = OffsetDateTime.now(clock);

Теперь дата и время зависят от используемых часов: если изменим часы и их поведение, то изменим получение времени внутри всего приложения! Всё гениальное просто, а разработчики JDK о нас уже позаботились.

Часы должны быть одни и только одни

Следующая задача, которую предстоит решить, это получение и использование одного и того же экземпляра часов внутри всего нашего приложения.

На текущий момент в стандартной автоконфигурации Spring Boot’а нет bean’а с часами, и в ближайшее время он точно не появится, поэтому всё приходится делать самостоятельно.

Если вы используете Spring без JPA (или с JPA, но без EntityListeners), то можно использовать следующий вариант:

@Configuration
public class ClockConfig {

  @Bean
  public Clock clock() {
    return Clock.systemDefaultZone();
  }
}

Где-нибудь в сервисе просто инжектим и используем этот bean:

@Service
@Transactional(readOnly = true)
@RequiredArgsConstructor
public class EmployeeService {

    private final Clock clock;
    private final EmployeeRepository employeeRepository;
    ...
}

Если вы активно используете Bean Validation API, то, возможно, вы захотите использовать его интерфейс ClockProvider. Лично я считаю его применение избыточным: использование Clock проще и очевиднее (core team Spring’а считает так же).

Однако, их можно совмещать:

@Bean
public ClockProvider clockProvider(@Nonnull final Clock clock) {
    return () -> clock;
}

Ситуация несколько осложняется случае активного использования JPA и EntityListeners (@PrePersist/@PreUpdate и т.п.), поскольку инжектить бины в entity как-то... не принято. Именно так было на проекте, куда я пришёл несколько месяцев назад. В этом случае мы выбрали использование отдельного класса ClockHolder:

@Slf4j
@UtilityClass
public final class ClockHolder {

    private static final AtomicReference<Clock> CLOCK_REFERENCE = new AtomicReference<>(Clock.systemDefaultZone());

    @Nonnull
    public static Clock getClock() {
        return CLOCK_REFERENCE.get();
    }

    /**
     * Atomically sets the value to {@code newClock} and returns the old value.
     *
     * @param newClock the new value
     * @return the previous value of clock
     */
    @Nonnull
    public static Clock setClock(@Nonnull final Clock newClock) {
        Objects.requireNonNull(newClock, "newClock cannot be null");
        final Clock oldClock = CLOCK_REFERENCE.getAndSet(newClock);
        log.info("Set new clock {}. Old clock is {}", newClock, oldClock);
        return oldClock;
    }
}

И пример его использования:

@Getter
@Setter
@SuperBuilder
@NoArgsConstructor
@MappedSuperclass
public abstract class BaseEntity {

    @Id
    @NotNull
    @Column(updatable = false, nullable = false)
    private UUID id;

    @Column(name = "created_at", updatable = false, nullable = false)
    private LocalDateTime createdAt;

    @PrePersist
    public void beforePersist() {
        createdAt = LocalDateTime.now(ClockHolder.getClock());
    }
}

В Spring-конфигурацию bean clock в этом случае лучше не добавлять: везде следует использовать ClockHolder.

@Component
@NoArgsConstructor
public class ClockAwareEntityListener {

    // Couldn't use constructor injection here
    @Autowired
    private Clock clock;

    @PrePersist
    public void initCreatedAt(@Nonnull final BaseEntity entity) {
        if (entity.getCreatedAt() == null) {
            entity.setCreatedAt(LocalDateTime.now(clock));
        }
    }
}

@Getter
@Setter
@SuperBuilder
@NoArgsConstructor
@MappedSuperclass
@EntityListeners(ClockAwareEntityListener.class)
public abstract class BaseEntity {

    @Id
    @NotNull
    @Column(updatable = false, nullable = false)
    private UUID id;

    @Column(name = "created_at", updatable = false, nullable = false)
    private LocalDateTime createdAt;
}

Фиксируйте время в тестах

Итак, теперь мы имеем в коде единые часы, от которых зависит получение времени во всём приложении, но в тестах эти часы по-прежнему будут выдавать монотонно возрастающий недетерминированный результат при каждом запуске. Вероятно, это не совсем то, чего бы нам хотелось. К счастью, мы можем «остановить» время в тестах, используя Clock.fixed, например так:

@ActiveProfiles("test")
@SpringBootTest(classes = {ClockConfig.class, CustomConfigurationExampleTest.CustomClockConfiguration.class})
class CustomConfigurationExampleTest {

    private static final LocalDateTime MILLENNIUM = LocalDateTime.of(2000, Month.JANUARY, 1, 0, 0, 0);

    @Autowired
    private Clock clock;

    @Test
    void clockAlsoShouldBeFixed() {
        final LocalDateTime realNow = LocalDateTime.now(Clock.systemDefaultZone());

        assertThat(LocalDateTime.now(clock))
                .isBefore(realNow)
                .isEqualTo(LocalDateTime.of(2000, Month.JANUARY, 1, 0, 0, 0));
    }

    @TestConfiguration
    static class CustomClockConfiguration {

        @Bean
        @Primary
        public Clock fixedClock() {
            return Clock.fixed(MILLENNIUM.toInstant(ZoneOffset.UTC), ZoneOffset.UTC);
        }
    }
}

В случае использования ClockHolder время можно зафиксировать в базовом классе:

@ActiveProfiles("test")
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public abstract class TestBase {

    protected static final LocalDateTime BEFORE_MILLENNIUM = LocalDateTime.of(1999, Month.DECEMBER, 31, 23, 59, 59);

    @BeforeAll
    static void setUpClock() {
        final Clock fixed = Clock.fixed(BEFORE_MILLENNIUM.toInstant(ZoneOffset.UTC), ZoneOffset.UTC);
        ClockHolder.setClock(fixed);
    }
}

А в тестах это будет выглядеть следующим образом:

class EmployeeRepositoryTest extends TestBase {

    @Autowired
    private EmployeeRepository employeeRepository;

    @Test
    void createdAtShouldBeSetAutomaticallyOnSave() {
        final Employee notSaved = prepareIvanIvanov();
        assertThat(notSaved.getCreatedAt())
                .isNull();
        final Employee saved = employeeRepository.save(notSaved);
        assertThat(saved)
                .isNotNull()
                .satisfies(e -> assertThat(e.getCreatedAt())
                        .isEqualTo(LocalDateTime.now(ClockHolder.getClock()))
                        .isEqualTo(LocalDateTime.of(1999, Month.DECEMBER, 31, 23, 59, 59))
                        .isBefore(LocalDateTime.now(Clock.systemDefaultZone())));
    }
}

В конкретном тесте время можно изменить следующим образом:

@Test
void canBeSavedInFuture() {
    final LocalDateTime distantFuture = LocalDateTime.of(3000, Month.JANUARY, 1, 0, 0, 0);
    final Clock fixed = Clock.fixed(distantFuture.toInstant(ZoneOffset.UTC), ZoneOffset.UTC);
    final Clock oldClock = ClockHolder.setClock(fixed);
    try {
        final Employee notSaved = prepareIvanIvanov();
        assertThat(notSaved.getCreatedAt())
                .isNull();
        final Employee saved = employeeRepository.save(notSaved);
        assertThat(saved)
                .isNotNull()
                .satisfies(e -> assertThat(e.getCreatedAt())
                        .isEqualTo(LocalDateTime.now(ClockHolder.getClock()))
                        .isEqualTo(LocalDateTime.of(3000, Month.JANUARY, 1, 0, 0, 0))
                        .isAfter(LocalDateTime.now(Clock.systemDefaultZone())));
    } finally {
        ClockHolder.setClock(oldClock);
    }
}

Получается многословно, не правда ли?

Используйте в тестах MutableClock

Стандартные часы Clock из JDK являются неизменяемыми (иммутабельными). Это очень классно, но только не в тестах: там было бы удобнее иметь возможность манипулировать временем. К счастью, уже есть ряд готовых решений для этого. Я остановил свой выбор на имплементации MutableClock из ThreeTen-Extra.

В коде это будет выглядеть примерно так: объявляем bean с изменяемым часами, переопределяем через него bean clock и после каждого теста восстанавливаем исходное значение фиксированных часов (чтобы в других тестах не заботиться об этом).

@ActiveProfiles("test")
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@ContextConfiguration(classes = TestBase.CustomClockConfiguration.class)
public abstract class TestBase {

    protected static final LocalDateTime BEFORE_MILLENNIUM = LocalDateTime.of(1999, Month.DECEMBER, 31, 23, 59, 59);

    @Autowired
    protected MutableClock mutableClock;

    @Autowired
    protected Clock clock;

    @AfterEach
    void resetClock() {
        mutableClock.setInstant(getTestInstant());
    }

    static Instant getTestInstant() {
        return BEFORE_MILLENNIUM.toInstant(ZoneOffset.UTC);
    }

    @TestConfiguration
    static class CustomClockConfiguration {

        @Bean
        public MutableClock mutableClock() {
            return MutableClock.of(getTestInstant(), ZoneOffset.UTC);
        }

        @Bean
        @Primary
        public Clock fixedClock(@Nonnull final MutableClock mutableClock) {
            return mutableClock;
        }
    }
}

Зато в тестах теперь очень легко изменять время как в прошлое, так и в будущее:

@Test
void clockCanBeChangedLocally() {
    mutableClock.add(1_000L, ChronoUnit.YEARS); // Назад в будущее!

    assertThat(LocalDateTime.now(clock))
            .isAfter(LocalDateTime.now(Clock.systemDefaultZone()))
            .isEqualTo(LocalDateTime.of(2999, Month.DECEMBER, 31, 23, 59, 59));
}

Эмулируйте поведение СУБД, если нужно

Помните, про поведение функции now() в PostgreSQL? Такого же поведения вы можете добиться внутри своих методов/транзакций. Это нужно далеко не всегда, но может быть полезно при выявлении аномалий/разборе инцидентов. Простейший вариант этого добиться — получить текущее время в начале транзакции, запомнить его и затем пробрасывать во все последующие методы как параметр. Если вариант с параметром кажется многословным, то посмотрите в сторону ThreadLocal/MDC.

Не забывайте о различиях в точности

Точность времени зависит от используемой платформы. Я уже упоминал об этом в одной из своих предыдущих статей: на macOS (M1, Monterey), например, секунды измеряются с точностью до 6 знаков после запятой, а на build-агенте под управлением Linux — 9 знаков после запятой. Иногда это мешает в тестах. Решение простое: транкейтить до 6 знаков.

@Nonnull
public static LocalDateTime localDateTimeNow() {
    return LocalDateTime.now(clock()).truncatedTo(ChronoUnit.MICROS);
}

@Nonnull
public static Instant instantNow() {
    return Instant.now(clock()).truncatedTo(ChronoUnit.MICROS);
}

Как приучить разработчиков, правильно работать с датой/временем?

Ключевой момент, который может помешать вам достичь успеха в управлении временем внутри вашего приложения, это использование метода now() без указания часов.

Разумеется, все ваши разработчики в команде должны об этом знать и использовать правильную перегруженную версию. Также вы можете контролировать этот момент на этапе code review, но я предпочитаю другой вариант — запрет на уровне Checkstyle, используя правило IllegalMethodCall:

<module name="IllegalMethodCall">
    <property name="illegalMethodNames" value="now" />
</module>

В этом случае для получения времени должны использоваться статические методы, описанные в предыдущем пункте (с усечением времени). Такой подход решает сразу несколько проблем. И, да, он весьма кардинальный.

* * *

На этом у меня всё. Итоговые примеры кода можно найти на GitHub.