Дата и время

SmartMVC применяет единый набор правил к параметрам запроса, переменным пути, JSON во входящих запросах и JSON в ответах.

Поддерживаемые типы

Тип	Параметр запроса	JSON на входе	JSON на выходе	Использует `zone-id`
`LocalDateTime`	✓	✓	✓	—
`LocalDate`	✓	✓	✓	—
`LocalTime`	✓	✓	✓	—
`Instant`	✓	✓	✓	✓
`OffsetDateTime`	✓	✓	✓	✓
`ZonedDateTime`	✓	✓	✓	✓
`java.util.Date`	✓	✓	✓	✓

Отдельные форматы даты, времени и даты со временем

spring:
  smart:
    mvc:
      date-time:
        request-format: yyyy-MM-dd HH:mm:ss
        response-format: yyyy-MM-dd HH:mm:ss
        date-request-format: yyyy-MM-dd
        date-response-format: yyyy-MM-dd
        time-request-format: HH:mm:ss
        time-response-format: HH:mm:ss
        zone-id: Asia/Shanghai
        incomplete-input-policy: FILL_MISSING

LocalDateTime использует request-format и response-format;
LocalDate использует отдельные форматы даты;
LocalTime использует отдельные форматы времени;
Instant, OffsetDateTime, ZonedDateTime и Date преобразуются с учётом zone-id.

Пример параметров запроса

@GetMapping("/events")
public List<EventView> events(
        @RequestParam LocalDate day,
        @RequestParam Instant from) {
    return eventService.find(day, from);
}

GET /events?day=2026-08-06&from=2026-08-06%2009:30:00

Те же строковые форматы применяются к полям JSON.

Как применяется часовой пояс

LocalDate, LocalTime и LocalDateTime сами по себе не содержат часовой пояс, поэтому их значения не сдвигаются между поясами.

Типы, представляющие конкретный момент на временной шкале, например Instant, используют zone-id:

локальное время без смещения при разборе интерпретируется в настроенном часовом поясе и превращается в конкретный момент;
при выводе значение сначала преобразуется в настроенный часовой пояс, а затем форматируется с помощью response-format.

Значение по умолчанию system-default использует часовой пояс JVM. Если окружение развёртывания может меняться, лучше явно задать часовой пояс IANA.

Стандартный ввод ISO

Помимо настроенного формата, типы со смыслом момента времени поддерживают стандартную запись ISO. Допустимые формы зависят от целевого типа:

Целевой тип	`...Z`	`...+08:00`	`...+08:00[Asia/Shanghai]`
`Instant`	✓	✓	—
`OffsetDateTime`	✓	✓	—
`ZonedDateTime`	✓	✓	✓
`java.util.Date`	✓	✓	—

Например:

2026-08-06T01:30:00Z
2026-08-06T09:30:00+08:00
2026-08-06T09:30:00+08:00[Asia/Shanghai]

Правило для неполного ввода

При значении FILL_MISSING, если основной формат целевого типа не подошёл, SmartMVC пробует следующие фиксированные варианты. Каждый сокращённый вариант применим только к указанным типам:

Ввод	Целевые типы	Результат дополнения
`2026-08-06 09:30`	`LocalDateTime`, `Instant`, `OffsetDateTime`, `ZonedDateTime`, `Date`	Секунды становятся `00`
`2026-08-06`	`LocalDateTime`, `Instant`, `OffsetDateTime`, `ZonedDateTime`, `Date`	Время становится `00:00:00`
`2026-08`	`LocalDate` и перечисленные выше типы даты и времени	Используется первый день месяца; для типов со временем — полночь
`2026`	`LocalDate` и перечисленные выше типы даты и времени	Используется 1 января указанного года; для типов со временем — полночь
`09:30`	`LocalTime`	Секунды становятся `00`
`09`	`LocalTime`	Минуты и секунды становятся `00`

Значение REJECT запрещает такие дополнения:

spring.smart.mvc.date-time.incomplete-input-policy: REJECT

Резервный разбор ISO не зависит от этой настройки и продолжает работать для типов со смыслом момента времени.

Как выбрать тип

Для дня рождения, даты работы магазина и других чистых дат используйте LocalDate;
для локального времени ежедневной операции — LocalTime;
для даты и времени без семантики часового пояса — LocalDateTime;
для конкретного момента, передаваемого между регионами, предпочтителен Instant.