time — 时间处理

now := time.Now()
now.Format("2006-01-02")          // → 2024-01-15
now.Format("15:04:05")            // → 10:30:00
now.Format("2006年01月02日")      // → 2024年01月15日
now.Format("Mon Jan 2 15:04:05")  // → Mon Jan 15 10:30:00

// 常用的预定义格式
now.Format(time.RFC3339)    // 2006-01-02T15:04:05Z07:00
now.Format(time.DateTime)   // 2006-01-02 15:04:05（Go 1.20+）
now.Format(time.RFC3339Nano)// 带纳秒、且去尾零

// 创建 Duration
d := 10 * time.Second
d = time.Duration(500) * time.Millisecond  // 先转成 Duration 再乘

// 常量（纳秒基准）
time.Nanosecond   // 1
time.Microsecond  // 1e3
time.Millisecond  // 1e6
time.Second       // 1e9
time.Minute       // 6e10
time.Hour         // 3.6e12

type Duration time.Duration

func (d Duration) MarshalJSON() ([]byte, error) {
    return json.Marshal(time.Duration(d).String()) // "5s"
}

func (d *Duration) UnmarshalJSON(b []byte) error {
    var s string
    if err := json.Unmarshal(b, &s); err != nil {
        return err
    }
    dur, err := time.ParseDuration(s)
    if err != nil {
        return err
    }
    *d = Duration(dur)
    return nil
}

// 认知 1: time.Now() 返回的时间带本地时区信息
now := time.Now()
fmt.Println(now)  // 2024-01-15 10:30:00 +08:00 CST

// 认知 2: time.Parse 默认返回 UTC（除非格式中有时区信息）
t, _ := time.Parse("2006-01-02 15:04:05", "2024-01-15 10:30:00")
fmt.Println(t) // 2024-01-15 10:30:00 +0000 UTC ← 注意！

// 认知 3: 正确做法是使用 ParseInLocation
loc, _ := time.LoadLocation("Asia/Shanghai")
t, _ = time.ParseInLocation("2006-01-02 15:04:05", "2024-01-15 10:30:00", loc)
fmt.Println(t) // 2024-01-15 10:30:00 +0800 CST

// In(loc) 返回"同一时刻"在不同时区的表示
shanghai, _ := time.LoadLocation("Asia/Shanghai")
nyc, _ := time.LoadLocation("America/New_York")

t := time.Date(2024, 1, 15, 12, 0, 0, 0, shanghai)
fmt.Println(t.In(nyc)) // 2024-01-14 23:00:00 -0500 EST
// 同一时刻，纽约还是前一天晚上

now := time.Now()

// 加法（返回新值，不修改原值——Time 是不可变值类型）
tomorrow := now.Add(24 * time.Hour)

// AddDate — 处理日历意义上的年月日
nextMonth := now.AddDate(0, 1, 0)  // 加 1 个月

// 时间差
diff := tomorrow.Sub(now) // 返回 Duration

// 截断/舍入（基于绝对时间轴）
now.Truncate(time.Hour)  // 截断到整点
now.Round(time.Hour)     // 四舍五入到整点

t1 := time.Date(2024, 1, 15, 12, 0, 0, 0, time.UTC)
t2 := time.Date(2024, 1, 15, 20, 0, 0, 0, time.FixedZone("CST", 8*3600))

// Before / After / Compare — 比较时刻先后，忽略时区表示差异
t1.Before(t2)              // false
t1.Equal(t2)               // true —— 同一时刻
fmt.Println(t1.Compare(t2)) // 0 —— Go 1.20+，返回 -1/0/+1，适合排序

var t time.Time          // 零值 = January 1, year 1, 00:00:00 UTC
fmt.Println(t.IsZero())  // true —— 还未被赋值

t2 := time.Now()
fmt.Println(t2.IsZero()) // false

// 常见用法：可选时间字段用零值表示"未设置"
type Event struct {
    Title     string
    StartTime time.Time
    EndTime   time.Time
}

func (e Event) HasSchedule() bool {
    return !e.StartTime.IsZero() && !e.EndTime.IsZero()
}

// 判断是否 UTC：Time 没有 IsUTC() 方法，比较 Location
t := time.Now().UTC()
fmt.Println(t.Location() == time.UTC) // true

// IsDST — 是否处于夏令时
loc, _ := time.LoadLocation("America/New_York")
summer := time.Date(2024, 7, 1, 12, 0, 0, 0, loc)
fmt.Println(summer.IsDST()) // true

// YearDay — 一年中的第几天
fmt.Println(time.Date(2024, 2, 1, 0, 0, 0, 0, time.UTC).YearDay()) // 32

// Weekday — 星期几（从 Sunday 开始）
weekday := time.Now().Weekday() // time.Monday 等
fmt.Println(weekday)            // Monday

// Unix / UnixMilli / UnixMicro / UnixNano — 时间戳
fmt.Println(time.Now().Unix())      // 秒
fmt.Println(time.Now().UnixMilli()) // 毫秒
fmt.Println(time.Now().UnixMicro()) // 微秒
fmt.Println(time.Now().UnixNano())  // 纳秒

// 方式 1：创建 Timer
timer := time.NewTimer(2 * time.Second)
<-timer.C
timer.Stop()

// 方式 2：After（不能 Stop，适合一次性等待）
<-time.After(2 * time.Second)

// 方式 3：AfterFunc（触发后执行函数）
tf := time.AfterFunc(2*time.Second, func() {
    fmt.Println("fired")
})
defer tf.Stop() // 可取消；注意函数体可能已在别的 goroutine 跑起来

ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop() // 不 Stop，ticker 及其 goroutine 要等 GC 才能回收

for {
    select {
    case t := <-ticker.C:
        fmt.Println("tick at", t)
    case <-ctx.Done():
        return
    }
}

// 模式 1：context + timeout（首选——能一路透传到下游调用）
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
result, err := doWork(ctx)

// 模式 2：select + After（一次性等待，简洁）
select {
case result := <-workCh:
    fmt.Println("done:", result)
case <-time.After(3 * time.Second):
    fmt.Println("timeout")
}

// 模式 3：Timer + Reset（循环场景，高效；Go 1.23+ 不需要排空）
timer := time.NewTimer(3 * time.Second)
defer timer.Stop()
for {
    select {
    case result := <-workCh:
        timer.Reset(3 * time.Second) // 1.23+：直接 Reset，不会有旧值残留
    case <-timer.C:
        fmt.Println("timeout")
        return
    }
}

// 模式 4：time.Sleep 不可中断——select + After 才是可取消的等待
select {
case <-time.After(2 * time.Second):
    // 到期
case <-ctx.Done():
    return ctx.Err()
}