47 lines
1.6 KiB
Markdown
47 lines
1.6 KiB
Markdown
# @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。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
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)
|
||
```
|