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：输出统计描述。

📦 安装

go get apigo.cc/go/time

💡 快速开始

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())