go-str2duration 库使用指南

go-str2duration 是一个用于将字符串转换为时间间隔(time.Duration)的 Go 语言库。它支持人类可读的时间字符串格式，如"1h30m"、"2 days 5 hours"等。

安装

go get github.com/xhit/go-str2duration/v2

基本用法

1. 字符串转Duration

package main

import (
	"fmt"
	"time"

	str2duration "github.com/xhit/go-str2duration/v2"
)

func main() {
	// 简单时间字符串
	duration, err := str2duration.ParseDuration("2h30m")
	if err != nil {
		panic(err)
	}
	fmt.Printf("Duration: %v\n", duration) // 输出: Duration: 2h30m0s

	// 更自然的语言表达
	duration, err = str2duration.ParseDuration("2 hours and 30 minutes")
	if err != nil {
		panic(err)
	}
	fmt.Printf("Duration: %v\n", duration) // 输出: Duration: 2h30m0s

	// 复杂表达式
	duration, err = str2duration.ParseDuration("1 year 2 months 3 weeks 4 days 5 hours 6 minutes 7 seconds")
	if err != nil {
		panic(err)
	}
	fmt.Printf("Duration: %v\n", duration)
}

2. 支持的时间单位

该库支持以下时间单位：

• 纳秒(ns/nanosecond/nanoseconds)
• 微秒(us/microsecond/microseconds)
• 毫秒(ms/millisecond/milliseconds)
• 秒(s/second/seconds)
• 分钟(m/minute/minutes)
• 小时(h/hour/hours)
• 天(d/day/days)
• 周(w/week/weeks)
• 月(month/months) - 按30天计算
• 年(y/year/years) - 按365天计算

3. 实际应用示例

package main

import (
	"fmt"
	"time"

	str2duration "github.com/xhit/go-str2duration/v2"
)

func main() {
	// 计算未来时间
	now := time.Now()
	duration, _ := str2duration.ParseDuration("3 days 2 hours")
	futureTime := now.Add(duration)
	fmt.Printf("当前时间: %v\n3天2小时后的时间: %v\n", now, futureTime)

	// 定时器应用
	duration, _ = str2duration.ParseDuration("30 seconds")
	timer := time.NewTimer(duration)
	fmt.Println("等待30秒...")
	<-timer.C
	fmt.Println("30秒已过!")

	// 配置文件读取时间间隔
	config := map[string]string{
		"timeout": "5m30s",
		"delay":   "2 hours 15 minutes",
	}
	
	timeout, _ := str2duration.ParseDuration(config["timeout"])
	delay, _ := str2duration.ParseDuration(config["delay"])
	
	fmt.Printf("超时设置: %v\n延迟设置: %v\n", timeout, delay)
}

4. 错误处理

package main

import (
	"fmt"
	"log"

	str2duration "github.com/xhit/go-str2duration/v2"
)

func main() {
	// 无效时间字符串
	_, err := str2duration.ParseDuration("invalid time string")
	if err != nil {
		log.Printf("解析错误: %v", err)
	}

	// 部分无效的情况
	duration, err := str2duration.ParseDuration("2 hours and invalid")
	if err != nil {
		log.Printf("解析错误: %v", err)
	} else {
		fmt.Printf("解析成功: %v", duration)
	}
}

高级特性

1. 自定义解析器

package main

import (
	"fmt"

	str2duration "github.com/xhit/go-str2duration/v2"
)

func main() {
	parser := str2duration.NewParser()
	
	// 可以添加自定义转换规则
	parser.AddUnit("fortnight", 14*24*time.Hour)
	
	duration, err := parser.Parse("2 fortnight")
	if err != nil {
		panic(err)
	}
	fmt.Printf("Duration: %v\n", duration) // 输出: 672h0m0s
}

2. 反向转换(Duration转字符串)

package main

import (
	"fmt"
	"time"

	str2duration "github.com/xhit/go-str2duration/v2"
)

func main() {
	duration := 2*time.Hour + 30*time.Minute + 45*time.Second
	
	// 转换为标准字符串
	str := str2duration.String(duration)
	fmt.Println(str) // 输出: 2h30m45s
	
	// 转换为更易读的格式
	str = str2duration.StringHuman(duration)
	fmt.Println(str) // 输出: 2 hours 30 minutes 45 seconds
}

性能考虑

对于高性能场景，建议复用Parser实例：

package main

import (
	"fmt"
	"time"

	str2duration "github.com/xhit/go-str2duration/v2"
)

func main() {
	parser := str2duration.NewParser()
	
	start := time.Now()
	for i := 0; i < 10000; i++ {
		_, err := parser.Parse("1h30m")
		if err != nil {
			panic(err)
		}
	}
	fmt.Printf("解析10000次耗时: %v\n", time.Since(start))
}

总结

go-str2duration 库提供了灵活的时间字符串解析功能，特别适合需要处理用户输入或配置文件中的时间间隔的场景。它的主要优点包括：

1. 支持自然语言时间表达式
2. 支持多种时间单位
3. 提供双向转换功能
4. 可扩展的自定义单位支持

对于需要更复杂时间处理的项目，这是一个非常实用的工具库。