time в Golang: Now, Sleep, Format, Parse и Duration

Основы в одной программе

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Now()

	time.Sleep(50 * time.Millisecond)

	elapsed := time.Since(start)
	fmt.Println("slept at least 50ms:", elapsed >= 50*time.Millisecond)

	t := time.Date(2026, time.September, 23, 14, 30, 0, 0, time.UTC)
	fmt.Println(t)
	fmt.Println(t.Format("2006-01-02 15:04"))
	fmt.Println(t.Format("Monday, January 2, 2006"))
	fmt.Println("in 90 minutes:", t.Add(90*time.Minute).Format(time.Kitchen))
}

time.Now() возвращает текущее местное время, time.Sleep приостанавливает текущую горутину, time.Since измеряет прошедшее время, а time.Date создаёт конкретный момент. Дальше на странице каждая часть разобрана по очереди. Примеры используют фиксированные даты и UTC, чтобы вывод был одинаковым, где бы вы их ни запускали.

Sleep и Duration

time.Duration это int64, содержащий число наносекунд. В пакете есть константы для записи читаемых значений:

time.Day нет, потому что день не всегда длится 24 часа, когда пояс переходит на летнее время. Для календарных дней используйте AddDate (см. ниже).

package main

import (
	"fmt"
	"time"
)

func main() {
	d := 90 * time.Minute
	fmt.Println(d)                      // 1h30m0s
	fmt.Println(d.Hours(), d.Minutes()) // float64 values
	fmt.Println(2*time.Hour + 15*time.Second)

	// Multiplying by a variable needs a conversion: int * Duration does not compile.
	retries := 3
	backoff := time.Duration(retries) * 200 * time.Millisecond
	fmt.Println("backoff:", backoff)

	// Parse a duration from a string (for flags and config files).
	timeout, err := time.ParseDuration("1m30s")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("timeout:", timeout, "=", timeout.Seconds(), "seconds")

	// Round and truncate a measured duration for display.
	measured := 1234567891 * time.Nanosecond
	fmt.Println(measured, measured.Round(time.Millisecond), measured.Truncate(time.Second))
}

Две частые ошибки происходят оттого, что Duration это целое число:

• time.Sleep(5) спит 5 наносекунд. Всегда умножайте на единицу: time.Sleep(5 * time.Second).
• time.Sleep(n * time.Second) не компилируется, когда n это переменная типа int. Преобразуйте её: time.Duration(n) * time.Second. Константа вроде 5 работает без преобразования, потому что нетипизированные константы подстраиваются под тип Duration.

ParseDuration принимает ns, us (или µs), ms, s, m и h в сочетаниях вроде "2h45m" или "1.5s". Единицы для дней у неё нет.

Форматирование: эталонная раскладка 2006-01-02

Go не использует %Y-%m-%d или yyyy-MM-dd. Раскладка это эталонное время

Mon Jan 2 15:04:05 MST 2006

записанное так, как должен выглядеть ваш вывод. Значения подобраны так, чтобы каждое было уникальным: месяц 1, день 2, час 3 (или 15), минута 4, секунда 5, год 6 (2006), смещение пояса -7 (-0700). Читайте это как 01/02 03:04:05PM '06 -0700.

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2026, time.March, 5, 9, 7, 3, 250_000_000, time.UTC)

	layouts := []string{
		"2006-01-02",
		"02/01/2006",
		"01/02/06",
		"Jan 2, 2006",
		"Monday 2 January 2006",
		"15:04:05",
		"3:04 PM",
		"2006-01-02T15:04:05.000Z07:00",
		time.RFC3339,
		time.DateTime,
		time.RFC1123,
	}
	for _, l := range layouts {
		fmt.Printf("%-32q %s\n", l, t.Format(l))
	}
}

Токены раскладки, которые понадобятся чаще всего:

Предопределённые раскладки:

Классическая ошибка: раскладка с не теми числами, например "2023-01-01". Go её не отвергает. Незнакомые символы он копирует, а знакомые подставляет: каждая 2 это день, 3 это час в 12-часовом формате, а оба 01 это месяц, поэтому 5 марта в 9:07 форматируется как 5059-03-03. Раскладка вроде "YYYY-MM-DD" вообще не содержит токенов и печатает сама себя. Если отформатированные даты выглядят странно, проверьте, что раскладка использует ровно эталонные значения.

Разбор строк во время

time.Parse(layout, value) использует те же раскладки и возвращает ошибку, которую нужно проверять:

package main

import (
	"fmt"
	"time"
)

func main() {
	t, err := time.Parse("2006-01-02 15:04", "2026-09-23 18:45")
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t, "| location:", t.Location())

	// A string with an offset keeps that offset.
	t2, err := time.Parse(time.RFC3339, "2026-09-23T18:45:00+02:00")
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t2, "| in UTC:", t2.UTC())

	// Interpret a zone-less string in a specific zone.
	tokyo := time.FixedZone("JST", 9*60*60)
	t3, err := time.ParseInLocation(time.DateTime, "2026-09-23 18:45:00", tokyo)
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t3, "| in UTC:", t3.UTC())

	// A wrong input produces a descriptive error.
	_, err = time.Parse(time.DateOnly, "23/09/2026")
	fmt.Println("error:", err)
}

Если во вводе нет пояса, Parse возвращает UTC. Одна и та же строка с временем на часах может означать разные моменты в зависимости от пояса, поэтому и существует ParseInLocation. Сообщение об ошибке называет часть, которая не совпала, и это помогает при отладке раскладки.

Часовые пояса

time.Time это момент плюс пояс, используемый для отображения. Смена пояса через In меняет то, как значение печатается, но не то, какой это момент.

package main

import (
	"fmt"
	"time"
	_ "time/tzdata" // embed the zone database so LoadLocation works anywhere
)

func main() {
	meeting := time.Date(2026, time.September, 23, 15, 0, 0, 0, time.UTC)

	ny, err := time.LoadLocation("America/New_York")
	if err != nil {
		fmt.Println("load location:", err)
		return
	}
	india := time.FixedZone("IST", 5*60*60+30*60) // +05:30, no DST rules

	fmt.Println("UTC:     ", meeting.Format(time.RFC1123))
	fmt.Println("New York:", meeting.In(ny).Format(time.RFC1123))
	fmt.Println("India:   ", meeting.In(india).Format(time.RFC1123))
	fmt.Println("same instant:", meeting.Equal(meeting.In(ny)))
}

• time.UTC доступен всегда. Храните и передавайте время в UTC (или в RFC 3339 со смещением), а преобразуйте только для отображения.
• time.Local это пояс машины. На серверах и в контейнерах это часто UTC, а на ноутбуке нет, так что код, который от него зависит, ведёт себя в разных местах по-разному.
• time.LoadLocation("Europe/Berlin") читает базу IANA из операционной системы. В минимальных образах контейнеров её часто нет, и тогда вызов возвращает ошибку. Пустой импорт _ "time/tzdata" встраивает базу в ваш бинарник (около 450 КБ), так что всё работает всегда. Всегда обрабатывайте ошибку.
• time.FixedZone(name, offsetSeconds) создаёт пояс с постоянным смещением. Правил перехода на летнее время у него нет, поэтому используйте его для полученных смещений, а не для именованных регионов.

Арифметика и сравнение

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Date(2026, time.January, 31, 10, 0, 0, 0, time.UTC)
	end := time.Date(2026, time.March, 1, 12, 30, 0, 0, time.UTC)

	fmt.Println("difference:", end.Sub(start))
	fmt.Println("in days:   ", int(end.Sub(start).Hours()/24))

	fmt.Println("+36h:      ", start.Add(36*time.Hour).Format(time.DateTime))
	fmt.Println("-1 week:   ", start.AddDate(0, 0, -7).Format(time.DateOnly))
	fmt.Println("+1 month:  ", start.AddDate(0, 1, 0).Format(time.DateOnly)) // Jan 31 + 1 month

	fmt.Println("before:", start.Before(end), "after:", start.After(end), "equal:", start.Equal(end))

	// Start of the day, and parts of a date.
	y, m, d := end.Date()
	midnight := time.Date(y, m, d, 0, 0, 0, 0, end.Location())
	fmt.Println("midnight:", midnight.Format(time.DateTime))
	fmt.Println("weekday:", end.Weekday(), "day of year:", end.YearDay())

	// Unix timestamps.
	fmt.Println("unix:", start.Unix(), "ms:", start.UnixMilli())
	fmt.Println("from unix:", time.Unix(1_790_000_000, 0).UTC())
}

Что заметить в выводе:

• AddDate(0, 1, 0) от 31 января даёт 3 марта, а не 28 февраля. Go прибавляет месяц, получает «31 февраля» и нормализует переполнение. Если нужно «тот же день следующего месяца, но не дальше конца месяца», напишите эту логику сами.
• Sub возвращает Duration, у которой потолок примерно 292 года. Для разницы в календарных днях сравнивайте даты в полночь UTC и делите на 24 часа.
• Чтобы получить начало дня, соберите время заново из Date(). t.Truncate(24 * time.Hour) округляет относительно нулевого времени в UTC, поэтому для любого пояса, кроме UTC, даёт неверный ответ.

Сравнивайте через Equal, Before, After и никогда через ==. time.Now() включает показание монотонных часов, чтобы time.Since оставался правильным, даже если системные часы переведут. == сравнивает это показание и пояс, поэтому два значения Time для одного момента могут быть неравны. По той же причине не используйте time.Time как ключ мапы без предварительной нормализации (t.UTC().Round(0) убирает монотонное показание).

Нулевой time.Time это 1 января 1 года, 00:00 UTC. Проверяйте его через t.IsZero().

Измерение прошедшего времени

start := time.Now()
doWork()
log.Printf("doWork took %v", time.Since(start))

time.Since(start) это time.Now().Sub(start), а time.Until(deadline) это deadline.Sub(time.Now()). Обе функции используют монотонные часы, когда они доступны, поэтому переводы системных часов им не страшны. Для бенчмарков используйте поддержку бенчмарков Go в пакете testing, а не ручные замеры.

Таймеры и тикеры

time.After(d) возвращает канал, который получает значение один раз через d. time.Timer это то же самое с методом Stop. time.Ticker выдаёт значение каждый период, пока вы его не остановите.

package main

import (
	"fmt"
	"time"
)

func main() {
	ticker := time.NewTicker(20 * time.Millisecond)
	defer ticker.Stop()

	done := time.NewTimer(110 * time.Millisecond)
	defer done.Stop()

	ticks := 0
	for {
		select {
		case <-ticker.C:
			ticks++
			fmt.Println("tick", ticks)
			if ticks == 3 {
				fmt.Println("got three ticks, stopping early")
				return
			}
		case <-done.C:
			fmt.Println("timer fired first")
			return
		}
	}
}

Три тика на 20, 40 и 60 мс приходят задолго до таймера на 110 мс, поэтому программа останавливается после третьего тика. time.AfterFunc(d, f) запускает f в отдельной горутине через d, что удобно для разовой отложенной работы.

Начиная с Go 1.23 таймеры и тикеры, на которые больше никто не ссылается, собираются сборщиком мусора, даже если вы так и не вызвали Stop, а канал остановленного или сброшенного таймера больше не выдаёт устаревшее значение. Вызов Stop через defer всё равно остаётся понятным способом сказать, что жизнь тикера закончена. Когда ограничение по времени касается всей операции, а не одного ожидания, context.WithTimeout обычно читается лучше таймера.

Время в JSON

time.Time автоматически кодируется в JSON строкой RFC 3339 и декодируется из неё, с точностью до наносекунд:

type Event struct {
	Name string    `json:"name"`
	At   time.Time `json:"at"`
}
// {"name":"deploy","at":"2026-09-23T14:30:00Z"}

Строка JSON в другом формате не декодируется. Для Unix-времени или своих форматов храните int64 или строку и преобразуйте, либо определите тип со своим UnmarshalJSON.

Частые ошибки

• time.Sleep(1) или time.Sleep(n) с голым числом. Это наносекунды.
• Раскладки с не теми цифрами. "2023-01-01" или "YYYY-MM-DD" не раскладки. Используйте "2006-01-02".
• Путаница минут и месяцев. Минуты это 04, месяцы 01. "15:01" печатает час, а затем месяц, а не минуту.
• Сравнение через ==. Используйте Equal.
• Расчёт на time.Local. Он разный на разных машинах. Указывайте явно time.UTC или загруженный пояс.
• Игнорирование ошибки от LoadLocation или Parse. Обе функции падают на реальном вводе. Неудачный Parse возвращает нулевое время, которое печатается как 1 год, а неудачный LoadLocation возвращает nil-пояс, из-за которого t.In(loc) паникует.