From 553e717bb9670f666e701a4286de2e5402b17bba Mon Sep 17 00:00:00 2001 From: Star Date: Wed, 22 Apr 2026 10:45:15 +0800 Subject: [PATCH] docs: finalize docs and sync cast dependency to v1.0.1 --- README.md | 44 +++++++++++++++++--------------------------- go.mod | 2 +- go.sum | 6 ++---- 3 files changed, 20 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index d8dc265..ad235ab 100644 --- a/README.md +++ b/README.md @@ -4,35 +4,25 @@ ## 🎯 设计哲学 -* **直观 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()`），确保服务高可用。 +* **直观 Layout**：使用 `YYYY-MM-DD HH:mm:ss` 等符合直觉的占位符。 +* **强力解析**：`Parse(v)` 自动探测并解析几乎所有时间格式。 +* **DSL 时间算术**：通过简洁的字符串表达式进行复杂的时间偏移计算。 +* **零摩擦防御**：输入非法格式时绝不 Panic，返回合理的默认值（`time.Now()`）。 -## 🚀 核心特性 +## 🛠 API Reference -### 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)。 +- `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`）。 -**时区处理规则：** -- **归一化**: 所有带时区信息的输入（如 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分钟后)。 +- `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。 ## 📦 安装 @@ -45,12 +35,12 @@ go get apigo.cc/go/time ```go 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) ``` diff --git a/go.mod b/go.mod index 34490d8..9b44fd3 100644 --- a/go.mod +++ b/go.mod @@ -2,6 +2,6 @@ module apigo.cc/go/time go 1.25.0 -require apigo.cc/go/cast v1.0.0 +require apigo.cc/go/cast v1.0.1 require gopkg.in/yaml.v3 v3.0.1 // indirect diff --git a/go.sum b/go.sum index b7b7d4a..1e0bebf 100644 --- a/go.sum +++ b/go.sum @@ -1,7 +1,5 @@ -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= +apigo.cc/go/cast v1.0.1 h1:OCQepSPf+wQBawUc4LB0hv4WegWyyz66qELsKuzzl6I= +apigo.cc/go/cast v1.0.1/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=