time/README.md

@go/time

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

🎯 设计哲学

• 直观 Layout：不再需要记忆 2006-01-02 15:04:05。使用 YYYY-MM-DD HH:mm:ss 等符合直觉的占位符。
• 强力解析：Parse(v) 几乎能吞下任何你丢给它的时间数据（时间戳、ISO、RFC3339、中文、JS Date 字符串等），并自动归一化为本地时间。
• DSL 时间算术：通过简洁的字符串表达式（如 +1Y-2M）进行复杂的时间偏移计算。
• 零摩擦防御：即使输入非法格式，也绝不 Panic，而是返回合理的默认值（如 time.Now()），确保服务高可用。

🚀 核心特性

1. 强力解析 Parse(v any)

不再需要 layout，Parse 会自动探测以下格式并返回 time.Time。

支持格式清单：

• 时间戳: 10位(秒)、13位(毫秒)、16位(微秒)、19位(纳秒) 自动识别。
• 标准日期: YYYY-MM-DD, YYYY/MM/DD, YYYY.01.02 (支持短年份如 24-01-02)。
• 标准时间: YYYY-MM-DD HH:mm:ss, YYYY-MM-DDTHH:mm:ss.SSS (支持空格或 T 分隔)。
• ISO/RFC3339: 2024-01-01T00:00:00Z, 2024-01-01T00:00:00+08:00。
• 紧凑格式: 20240101153045, 20240101。
• 中文格式: 2024年01月01日 15点30分, 下午3点, 15时30分 (缺失部分自动补全)。
• 常见 Web 格式: JS Date 字符串, HTTP Header (RFC1123)。

时区处理规则：

• 归一化: 所有带时区信息的输入（如 UTC 或 +08:00）在解析后都会自动转换为当前服务器的 time.Local。
• 无时区输入: 默认视为 time.Local。

2. 语义化格式化 Format(layout, v)

支持直观占位符：YYYY, MM, DD, HH, mm, ss, ms, ZZ (时区偏移)。

3. 时间加减 DSL Add(expr, v)

• 单位: Y(年), M(月), D(天), h, m, s, ms, us, ns。
• 示例: +1Y-2M (加一年减两个月), -1D (昨天), +1h30m (90分钟后)。

📦 安装

go get apigo.cc/go/time

💡 快速开始

import "apigo.cc/go/time"

// 自动探测并转为本地时间
tm := time.Parse("2025-06-23T15:30:45Z") 

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

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