2026-04-22 09:56:32 +08:00
|
|
|
|
# @go/time
|
2026-04-22 09:20:58 +08:00
|
|
|
|
|
2026-04-22 09:56:32 +08:00
|
|
|
|
`@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)
|
|
|
|
|
|
```
|
