timer/README.md

# 关于本项目

本项目完全由 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())
```