69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# 关于本项目
|
||
|
||
本项目完全由 AI 维护。代码源自 github.com/ssgo/u 的重构。
|
||
|
||
# @go/time
|
||
|
||
`@go/time` 是一个致力于“零心智负担”的时间处理库。它通过极简的 API 屏蔽了 Go 原生 `time` 包中繁琐的 Layout 记忆与类型转换，让时间解析、格式化与加减操作变得直观且高效。
|
||
|
||
## 🎯 设计哲学
|
||
|
||
* **开箱即用**：所有核心功能均提供包级函数，默认操作本地时区，无需初始化。
|
||
* **强力解析**：`Parse(v)` 自动探测并解析几乎所有时间格式。
|
||
* **DSL 时间算术**：通过简洁的字符串表达式进行复杂的时间偏移计算。
|
||
* **时区上下文**：对于特定时区需求，通过 `time.New(loc)` 轻松扩展。
|
||
* **零摩擦防御**：输入非法格式时绝不 Panic，返回合理的默认值（`time.Now()`）。
|
||
|
||
## 🛠 API Reference
|
||
|
||
### 核心函数 (默认操作本地时区)
|
||
|
||
- `func Parse(v any) time.Time`：全能解析。结果归一化为 `time.Local`。
|
||
- `func Format(layout string, v any) string`：人性化格式化。
|
||
- `func Add(expr string, v any) time.Time`：时间计算 DSL。
|
||
- `func Now() time.Time`：获取当前本地时间。
|
||
|
||
### 时区上下文扩展
|
||
|
||
当需要处理特定时区（如 UTC 或特定区域）时：
|
||
|
||
- `func New(loc *time.Location) *TimeZone`：创建一个时区上下文对象。
|
||
- `func (tz *TimeZone) Parse(v any) time.Time`：在指定时区上下文内解析。
|
||
- `func (tz *TimeZone) Format(layout string, v any) string`：在指定时区下格式化。
|
||
- `func (tz *TimeZone) Add(expr string, v any) time.Time`：在指定时区下计算偏移。
|
||
|
||
### 计时器工具 (Timer)
|
||
|
||
- `func Start() *Timer`：开始计时。
|
||
- `func (t *Timer) Record(label string) time.Duration`：记录一段耗时。
|
||
- `func (t *Timer) Pause(label string)`：暂停计时。
|
||
- `func (t *Timer) Resume()`：恢复计时。
|
||
- `func (t *Timer) Stop() time.Duration`：结束计时。
|
||
- `func (t *Timer) Describe() string`：输出统计描述。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
go get apigo.cc/go/time
|
||
```
|
||
|
||
## 💡 快速开始
|
||
|
||
```go
|
||
import "apigo.cc/go/time"
|
||
|
||
// 1. 简单场景：直接使用（默认本地时区）
|
||
tm := time.Parse("2026-05-01 10:00:00")
|
||
nextMonth := time.Add("+1M", tm)
|
||
|
||
// 2. 复杂场景：特定时区处理
|
||
bj := time.New(time.LoadLocation("Asia/Shanghai"))
|
||
tmInBJ := bj.Parse("2026-05-01 10:00:00")
|
||
|
||
// 3. 性能计时
|
||
t := time.Start()
|
||
// ... 业务逻辑
|
||
t.Record("Step1")
|
||
fmt.Println(t.Describe())
|
||
```
|