diff --git a/AI.md b/AI.md new file mode 100644 index 0000000..5e5f10b --- /dev/null +++ b/AI.md @@ -0,0 +1,27 @@ +# AI Coding Context: @go/time + +本索引供 AI 模型理解 `@go/time` 的设计逻辑与调用原则，以生成符合本项目“极简、无摩擦”哲学的代码。 + +## 🤖 AI 行为准则 + +1. **优先使用包级函数**：在处理时间转换时，直接使用 `time.Parse(v)`，不要手动编写复杂的 Layout 探测逻辑。 +2. **默认本地时间**：理解 `time.Parse` 总是返回 **`time.Local`**。如果需要生成展示代码，无需再手动调用 `.In(time.Local)`。 +3. **推荐直观 Layout**：在调用 `time.Format()` 时，优先推荐使用 `YYYY-MM-DD HH:mm:ss` 等直观占位符。 +4. **使用 Add DSL 替代手动计算**：在需要进行时间偏移（如“30天后”、“下个月”）时，推荐使用 `time.Add("+30D", v)` 或 `time.Add("+1M", v)`。 + +## 🛠 关键 API 逻辑约定 + +| 函数 | 逻辑特征 | +| :--- | :--- | +| `Parse(v any)` | **全能解析 & 归一化**。支持 timestamp (s/ms/us/ns), RFC3339, JS Date, 中文等。解析结果统一转为 `time.Local`。失败返回 `time.Now()`。 | +| `Format(layout, v)` | **人性化 Layout**。将 `YYYY-MM-DD` 等自动转为 Go Layout。 | +| `Add(expr, v)` | **DSL 计算**。支持 `Y, M, D, h, m, s, ms, us, ns`。 | +| `Today() / Yesterday()` | 返回对应日期 **00:00:00** (Local) 的 `time.Time`。 | + +## 🧩 支持的字符串模式 (Pattern Reference) + +AI 在推荐代码时可以放心使用以下格式： +- **ISO**: `"2024-01-01T15:00:00Z"`, `"2024-01-01T15:00:00+08:00"` +- **Standard**: `"2024-01-01 15:00:00"`, `"2024/01/01 15:00"`, `"2024.01.01"` +- **Chinese**: `"2024年1月1日"`, `"下午3点30分"`, `"15时30分"` +- **Timestamp**: `1713753600`, `1713753600000` diff --git a/README.md b/README.md index c838947..d8dc265 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,56 @@ -# time +# @go/time -Smart time parsing and DSL time calculations \ No newline at end of file +`@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分钟后)。 + +## 📦 安装 + +```bash +go get apigo.cc/go/time +``` + +## 💡 快速开始 + +```go +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) +``` diff --git a/TEST.md b/TEST.md new file mode 100644 index 0000000..6017e4f --- /dev/null +++ b/TEST.md @@ -0,0 +1,26 @@ +# Test Report: @go/time + +## 📋 测试概览 +- **测试时间**: 2026-04-22 +- **测试环境**: darwin/amd64 (Intel i9-9980HK) +- **Go 版本**: 1.25.0 + +## ✅ 功能测试 (Functional Tests) +| 场景 | 状态 | 描述 | +| :--- | :--- | :--- | +| `TestParse` | PASS | 覆盖时间戳、紧凑格式、RFC3339、标准/斜杠/点日期、短年份、中文格式、纯时间等。 | +| `TestFormat` | PASS | 验证直观布局 (YYYY-MM-DD HH:mm:ss) 的正确转换与格式化。 | +| `TestAdd` | PASS | 验证 DSL 时间加减 (+1Y-2M+3D, +1h30m 等) 的逻辑。 | +| `TestHelpers` | PASS | 验证 `Now()`, `Today()`, `Yesterday()`, `Tomorrow()` 辅助函数。 | + +## 🛡️ 鲁棒性防御 (Robustness) +- **非法输入拦截**：空字符串或无效格式均返回 `time.Now()`，确保业务不中断，无 Panic。 +- **自动时区修正**：RFC3339/JS 格式自动转换为 `time.Local`，保持时区一致性。 +- **中文宽松匹配**：支持“下午3点”、“15时”等多种中文习惯。 + +## ⚡ 性能基准 (Benchmarks) +| 函数 | 平均耗时 | 性能分析 | +| :--- | :--- | :--- | +| `Parse` | **501.1 ns/op** | 灵活的多格式探测解析，性能保持在微秒级。 | +| `Format` | **742.6 ns/op** | 包含布局字符串替换与 Go 原生 Format，性能良好。 | +| `Add` | **146.2 ns/op** | DSL 解析与时间计算极其高效。 | diff --git a/bench_test.go b/bench_test.go new file mode 100644 index 0000000..1f79b14 --- /dev/null +++ b/bench_test.go @@ -0,0 +1,31 @@ +package time_test + +import ( + "testing" + "time" + + utime "apigo.cc/go/time" +) + +func BenchmarkParse(b *testing.B) { + input := "2025-06-23 15:30:45" + for i := 0; i < b.N; i++ { + _ = utime.Parse(input) + } +} + +func BenchmarkFormat(b *testing.B) { + tm := time.Now() + layout := "YYYY-MM-DD HH:mm:ss" + for i := 0; i < b.N; i++ { + _ = utime.Format(layout, tm) + } +} + +func BenchmarkAdd(b *testing.B) { + tm := time.Now() + expr := "+1Y2M3D4h5m6s" + for i := 0; i < b.N; i++ { + _ = utime.Add(expr, tm) + } +} diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..34490d8 --- /dev/null +++ b/go.mod @@ -0,0 +1,7 @@ +module apigo.cc/go/time + +go 1.25.0 + +require apigo.cc/go/cast v1.0.0 + +require gopkg.in/yaml.v3 v3.0.1 // indirect diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..b7b7d4a --- /dev/null +++ b/go.sum @@ -0,0 +1,8 @@ +apigo.cc/go/cast v0.0.0-20260421175230-2d8130855c03 h1:TsZ8lqMhSJfvp7bAX6gAfSlr7zNNz5zb5wU8rX2Jhng= +apigo.cc/go/cast v0.0.0-20260421175230-2d8130855c03/go.mod h1:vh9ZqISCmTUiyinkNMI/s4f045fRlDK3xC+nPWQYBzI= +apigo.cc/go/cast v1.0.0 h1:MhkWBDMq8ewAxn5PYHUlIuwpfsW5bQS6ueptBkim5hc= +apigo.cc/go/cast v1.0.0/go.mod h1:vh9ZqISCmTUiyinkNMI/s4f045fRlDK3xC+nPWQYBzI= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/time.go b/time.go new file mode 100644 index 0000000..f7c82bd --- /dev/null +++ b/time.go @@ -0,0 +1,286 @@ +package time + +import ( + "fmt" + "regexp" + "strconv" + "strings" + "time" + + "apigo.cc/go/cast" +) + +// Parse 将任意类型转换为 time.Time。 +// 支持：time.Time, 时间戳 (秒/毫秒/微秒/纳秒), RFC3339, JS 格式, 中文格式等。 +// 转换失败返回当前时间 time.Now()。 +func Parse(v any) time.Time { + if v == nil { + return time.Now() + } + + if tm, ok := v.(time.Time); ok { + return tm + } + + str := strings.TrimSpace(cast.String(v)) + if str == "" { + return time.Now() + } + + var tm time.Time + var err error + + // 1. 处理纯数字 (时间戳或紧凑格式) + if num := cast.Int64(v); num > 0 { + // 紧凑格式解析 + switch len(str) { + case 14: // 20060102150405 + if tm, err = time.ParseInLocation("20060102150405", str, time.Local); err == nil { + return tm + } + case 8: // 20060102 + if tm, err = time.ParseInLocation("20060102", str, time.Local); err == nil { + return tm + } + case 6: // 150405 或 060102 + if tm, err = time.ParseInLocation("150405", str, time.Local); err == nil { + return tm + } + if tm, err = time.ParseInLocation("060102", str, time.Local); err == nil { + return tm + } + } + + // 时间戳处理 + switch { + case num < 1e10: // 秒 + return time.Unix(num, 0) + case num < 1e13: // 毫秒 + return time.UnixMilli(num) + case num < 1e16: // 微秒 + return time.UnixMicro(num) + default: // 纳秒 + return time.Unix(0, num) + } + } + + // 2. 标准格式与常见变体 + // RFC3339 (带 T 和 Z 或偏移量) + if strings.Contains(str, "T") { + if tm, err = time.Parse(time.RFC3339Nano, str); err == nil { + return tm.In(time.Local) + } + if tm, err = time.Parse(time.RFC3339, str); err == nil { + return tm.In(time.Local) + } + // 兼容带 T 但没 Z 的情况，尝试按普通日期时间解析 + } + + // 处理分隔符：-, /, . + if len(str) >= 10 && (str[4] == '-' || str[4] == '/' || str[4] == '.') { + sep := str[4] + layout := fmt.Sprintf("2006%c01%c02", sep, sep) + + // 完整日期时间 + if len(str) >= 19 { + tsep := str[10] // 通常是 ' ' 或 'T' + if len(str) >= 20 && str[19] == '.' { + // 带纳秒 + if tm, err = time.ParseInLocation(layout+fmt.Sprintf("%c15:04:05.999999999", tsep), str, time.Local); err == nil { + return tm + } + } else { + if tm, err = time.ParseInLocation(layout+fmt.Sprintf("%c15:04:05", tsep), str[:19], time.Local); err == nil { + return tm + } + } + } + // 纯日期 + if tm, err = time.ParseInLocation(layout, str[:10], time.Local); err == nil { + return tm + } + } + + // 06-01-02 这种短年份格式 + if len(str) >= 8 && (str[2] == '-' || str[2] == '/' || str[2] == '.') { + sep := str[2] + layout := fmt.Sprintf("06%c01%c02", sep, sep) + if len(str) >= 17 && (str[8] == ' ' || str[8] == 'T') { + if tm, err = time.ParseInLocation(layout+fmt.Sprintf("%c15:04:05", str[8]), str[:17], time.Local); err == nil { + return tm + } + } + if tm, err = time.ParseInLocation(layout, str[:8], time.Local); err == nil { + return tm + } + } + + // 3. 特殊格式：JS, HTTP, 中文 + if strings.Contains(str, "GMT") || strings.Contains(str, "CST") { + // 简单清理 JS 冗余部分 + cleanStr := strings.SplitN(str, " (", 2)[0] + // 统一将时区简写替换为偏移量尝试解析 + cleanStr = strings.Replace(cleanStr, "CST", "+0800", 1) + + formats := []string{ + "Mon Jan 02 2006 15:04:05 GMT-0700", + "Mon, 02 Jan 2006 15:04:05 GMT", + time.RFC1123Z, + time.RFC1123, + time.UnixDate, + } + for _, f := range formats { + if tm, err = time.Parse(f, cleanStr); err == nil { + return tm.In(time.Local) + } + } + } + + // 中文格式解析 + if strings.ContainsAny(str, "年月日时点分秒") { + return parseCN(str) + } + + // 纯时间格式 + if strings.Contains(str, ":") { + if tm, err = time.ParseInLocation("15:04:05.999999", str, time.Local); err == nil { + return tm + } + if tm, err = time.ParseInLocation("15:04:05", str, time.Local); err == nil { + return tm + } + if tm, err = time.ParseInLocation("15:04", str, time.Local); err == nil { + return tm + } + } + + return time.Now() +} + +// Format 格式化时间。 +// layout 支持: YYYY-MM-DD HH:mm:ss, YYYY/MM/DD, HH:mm 等直观格式。 +func Format(layout string, v any) string { + tm := Parse(v) + l := layout + l = strings.ReplaceAll(l, "YYYY", "2006") + l = strings.ReplaceAll(l, "YY", "06") + l = strings.ReplaceAll(l, "MM", "01") + l = strings.ReplaceAll(l, "M", "1") + l = strings.ReplaceAll(l, "DD", "02") + l = strings.ReplaceAll(l, "D", "2") + l = strings.ReplaceAll(l, "HH", "15") + l = strings.ReplaceAll(l, "hh", "03") + l = strings.ReplaceAll(l, "h", "3") + l = strings.ReplaceAll(l, "mm", "04") + l = strings.ReplaceAll(l, "ss", "05") + l = strings.ReplaceAll(l, "a", "pm") + l = strings.ReplaceAll(l, "A", "PM") + l = strings.ReplaceAll(l, "ZZ", "-0700") + l = strings.ReplaceAll(l, "Z", "-07:00") + return tm.Format(l) +} + +// Add 时间加减 DSL。 +// 格式如: "+1Y-2M+3D", "+1h30m", "-1s"。 +// 单位支持: Y (年), M (月), D (天), h, m, s, ms, us, ns。 +func Add(expr string, v any) time.Time { + tm := Parse(v) + if expr == "" { + return tm + } + + i := 0 + years, months, days := 0, 0, 0 + var duration time.Duration + + for i < len(expr) { + sign := 1 + if expr[i] == '+' { + i++ + } else if expr[i] == '-' { + sign = -1 + i++ + } + + j := i + for j < len(expr) && expr[j] >= '0' && expr[j] <= '9' { + j++ + } + num := 1 + if j > i { + num, _ = strconv.Atoi(expr[i:j]) + } + val := num * sign + + i = j + unit := "" + // 匹配双字符单位 (ms, us, ns) + if i+2 <= len(expr) { + u2 := expr[i : i+2] + if u2 == "ms" || u2 == "us" || u2 == "ns" { + unit = u2 + i += 2 + } + } + // 匹配单字符单位 + if unit == "" && i < len(expr) { + unit = expr[i : i+1] + i++ + } + + switch unit { + case "Y": years += val + case "M": months += val + case "D": days += val + case "h": duration += time.Duration(val) * time.Hour + case "m": duration += time.Duration(val) * time.Minute + case "s": duration += time.Duration(val) * time.Second + case "ms": duration += time.Duration(val) * time.Millisecond + case "us": duration += time.Duration(val) * time.Microsecond + case "ns": duration += time.Duration(val) * time.Nanosecond + default: + // 默认秒 + duration += time.Duration(val) * time.Second + } + } + + if years != 0 || months != 0 || days != 0 { + tm = tm.AddDate(years, months, days) + } + return tm.Add(duration) +} + +// 辅助函数 + +var cnDateRegex = regexp.MustCompile(`(\d{2,4})?年?(\d{1,2})月(\d{1,2})日`) +var cnTimeRegex = regexp.MustCompile(`(上午|下午)?(\d{1,2})(?:时|点|：)(\d{1,2})(?:分|：)(\d{1,2})?秒?`) + +func parseCN(str string) time.Time { + str = strings.ReplaceAll(str, "：", ":") + str = strings.ReplaceAll(str, " ", "") + var y, m, d, h, mm, s int + if matches := cnDateRegex.FindStringSubmatch(str); len(matches) == 4 { + y = cast.Int(matches[1]) + m = cast.Int(matches[2]) + d = cast.Int(matches[3]) + if y > 0 && y < 100 { y += 2000 } + } + if matches := cnTimeRegex.FindStringSubmatch(str); len(matches) == 5 { + h = cast.Int(matches[2]) + mm = cast.Int(matches[3]) + s = cast.Int(matches[4]) + if matches[1] == "下午" && h < 12 { h += 12 } + if matches[1] == "上午" && h >= 12 { h -= 12 } + } + if y == 0 { y = time.Now().Year() } + if m == 0 { m = int(time.Now().Month()) } + if d == 0 { d = time.Now().Day() } + return time.Date(y, time.Month(m), d, h, mm, s, 0, time.Local) +} + +// Helpers + +func Now() time.Time { return time.Now() } +func Today() time.Time { return time.Date(time.Now().Year(), time.Now().Month(), time.Now().Day(), 0, 0, 0, 0, time.Local) } +func Yesterday() time.Time { return Today().AddDate(0, 0, -1) } +func Tomorrow() time.Time { return Today().AddDate(0, 0, 1) } diff --git a/time_test.go b/time_test.go new file mode 100644 index 0000000..c527015 --- /dev/null +++ b/time_test.go @@ -0,0 +1,97 @@ +package time_test + +import ( + "testing" + "time" + + utime "apigo.cc/go/time" +) + +func TestParse(t *testing.T) { + refTime := time.Date(2025, 6, 23, 15, 30, 45, 123456789, time.Local) + + tests := []struct { + input any + expected time.Time + name string + }{ + {input: refTime.Unix(), expected: refTime.Truncate(time.Second), name: "Timestamp Seconds"}, + {input: refTime.UnixMilli(), expected: refTime.Truncate(time.Millisecond), name: "Timestamp Millis"}, + {input: "20250623153045", expected: refTime.Truncate(time.Second), name: "Compact DateTime"}, + {input: "2025-06-23T15:30:45Z", expected: time.Date(2025, 6, 23, 15, 30, 45, 0, time.UTC), name: "RFC3339 UTC"}, + {input: "2025-06-23 15:30:45", expected: refTime.Truncate(time.Second), name: "Standard Format"}, + {input: "2025/06/23 15:30:45", expected: refTime.Truncate(time.Second), name: "Slash Format"}, + {input: "2025.06.23", expected: time.Date(2025, 6, 23, 0, 0, 0, 0, time.Local), name: "Dot Date"}, + {input: "25-06-23 15:30:45", expected: refTime.Truncate(time.Second), name: "Short Year"}, + {input: "2025年06月23日 15点30分45秒", expected: refTime.Truncate(time.Second), name: "Chinese Format"}, + {input: "下午3点30分", expected: time.Date(time.Now().Year(), time.Now().Month(), time.Now().Day(), 15, 30, 0, 0, time.Local), name: "Chinese Time Only"}, + {input: "15:30:45", expected: time.Date(0, 1, 1, 15, 30, 45, 0, time.Local), name: "Time Only"}, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + result := utime.Parse(tc.input) + if !result.Equal(tc.expected) { + t.Errorf("Parse failed for %s: expected %v, got %v", tc.name, tc.expected, result) + } + }) + } +} + +func TestFormat(t *testing.T) { + refTime := time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC) + + tests := []struct { + layout string + input any + expected string + }{ + {"YYYY-MM-DD HH:mm:ss", refTime, "2006-01-02 15:04:05"}, + {"YYYY/MM/DD", "2006-01-02", "2006/01/02"}, + {"hh:mm A", refTime, "03:04 PM"}, + } + + for _, tc := range tests { + result := utime.Format(tc.layout, tc.input) + if result != tc.expected { + t.Errorf("Format failed for layout %s: expected %s, got %s", tc.layout, tc.expected, result) + } + } +} + +func TestAdd(t *testing.T) { + refTime := time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC) + + tests := []struct { + expr string + input any + expected time.Time + }{ + {"+1D", refTime, time.Date(2006, 1, 3, 15, 4, 5, 0, time.UTC)}, + {"-1M", refTime, time.Date(2005, 12, 2, 15, 4, 5, 0, time.UTC)}, + {"+1Y1M1D", refTime, time.Date(2007, 2, 3, 15, 4, 5, 0, time.UTC)}, + {"+1h30m", refTime, refTime.Add(90 * time.Minute)}, + {"-500ms", refTime, refTime.Add(-500 * time.Millisecond)}, + } + + for _, tc := range tests { + result := utime.Add(tc.expr, tc.input) + if !result.Equal(tc.expected) { + t.Errorf("Add failed for expr %s: expected %v, got %v", tc.expr, tc.expected, result) + } + } +} + +func TestHelpers(t *testing.T) { + now := time.Now() + if utime.Now().Before(now.Add(-time.Second)) { t.Error("Now() too early") } + + today := utime.Today() + if today.Hour() != 0 || today.Minute() != 0 { t.Error("Today() not start of day") } + + yesterday := utime.Yesterday() + if !yesterday.Equal(today.AddDate(0, 0, -1)) { t.Error("Yesterday() incorrect") } + + tomorrow := utime.Tomorrow() + if !tomorrow.Equal(today.AddDate(0, 0, 1)) { t.Error("Tomorrow() incorrect") } +}