time/README.md

@go/time

@go/time 是一个致力于“零心智负担”的时间处理库。它通过极简的 API 屏蔽了 Go 原生 time 包中繁琐的 Layout 记忆与类型转换，让时间解析、格式化与加减操作变得直观且高效。

🎯 设计哲学

• 直观 Layout：使用 YYYY-MM-DD HH:mm:ss 等符合直觉的占位符。
• 强力解析：Parse(v) 自动探测并解析几乎所有时间格式。
• DSL 时间算术：通过简洁的字符串表达式进行复杂的时间偏移计算。
• 零摩擦防御：输入非法格式时绝不 Panic，返回合理的默认值（time.Now()）。

🛠 API Reference

核心函数

• func Parse(v any) time.Time：全能解析。支持时间戳(s/ms/us/ns)、ISO、RFC3339、中文、JS Date 等。结果统一归一化为 time.Local。
• func Format(layout string, v any) string：人性化格式化。支持 YYYY, MM, DD, HH, mm, ss, ms, ZZ 等占位符。
• func Add(expr string, v any) time.Time：时间计算 DSL。支持 Y, M, D, h, m, s, ms, us, ns 组合（如 +1Y-2M）。

快捷助手

• func Now() time.Time
• func Today() time.Time：今日 00:00:00。
• func Yesterday() time.Time：昨日 00:00:00。
• func Tomorrow() time.Time：明日 00:00:00。

📦 安装

go get apigo.cc/go/time

💡 快速开始

import "apigo.cc/go/time"

// 1. 自动解析
tm := time.Parse("2025-06-23T15:30:45Z") 

// 2. 直观格式化
fmt.Println(time.Format("YYYY-MM-DD HH:mm", tm))

// 3. 语义加减
nextMonth := time.Add("+1M", tm)