Golang 自然语言日期时间解析插件 when 的使用

when 是一个强大的自然语言日期时间解析库，可以将人类可读的日期时间字符串转换为 time.Time 对象。它支持多种语言和格式，非常适合处理用户输入的非结构化日期时间信息。

安装

go get -u github.com/olebedev/when

基本使用

package main

import (
	"fmt"
	"time"
	
	"github.com/olebedev/when"
	"github.com/olebedev/when/rules/common"
	"github.com/olebedev/when/rules/en"
)

func main() {
	// 创建 when 解析器
	w := when.New(nil)
	
	// 添加英文规则
	w.Add(en.All...)
	w.Add(common.All...)
	
	// 解析自然语言日期时间
	text := "Meet me at 3pm tomorrow"
	r, err := w.Parse(text, time.Now())
	if err != nil {
		panic(err)
	}
	
	if r == nil {
		fmt.Println("No date/time found in text")
		return
	}
	
	fmt.Println("Matched text:", r.Text)           // "3pm tomorrow"
	fmt.Println("Parsed time:", r.Time)           // 具体的 time.Time 对象
	fmt.Println("Index in text:", r.Index)        // 匹配文本的起始位置
	fmt.Println("Source string:", text)           // 原始字符串
}

高级用法

1. 自定义解析规则

package main

import (
	"fmt"
	"time"
	
	"github.com/olebedev/when"
	"github.com/olebedev/when/rules"
)

// 自定义规则：解析 "next week" 为下周
type NextWeek struct{}

func (n *NextWeek) Apply(text string, t time.Time, opts rules.Options) *rules.MatchResult {
	if text == "next week" {
		return &rules.MatchResult{
			Text: text,
			Time: t.AddDate(0, 0, 7),
			Index: 0,
		}
	}
	return nil
}

func main() {
	w := when.New(nil)
	w.Add(&NextWeek{})
	
	text := "Let's meet next week"
	r, _ := w.Parse(text, time.Now())
	
	fmt.Println("Parsed time:", r.Time) // 当前时间 + 7天
}

2. 多语言支持

package main

import (
	"fmt"
	"time"
	
	"github.com/olebedev/when"
	"github.com/olebedev/when/rules/common"
	"github.com/olebedev/when/rules/ru" // 俄语规则
)

func main() {
	w := when.New(nil)
	w.Add(ru.All...)
	w.Add(common.All...)
	
	text := "встретимся через 2 дня" // 俄语"两天后见面"
	r, _ := w.Parse(text, time.Now())
	
	fmt.Println("Parsed time:", r.Time) // 当前时间 + 2天
}

3. 处理多个日期时间

package main

import (
	"fmt"
	"time"
	
	"github.com/olebedev/when"
	"github.com/olebedev/when/rules/common"
	"github.com/olebedev/when/rules/en"
)

func main() {
	w := when.New(nil)
	w.Add(en.All...)
	w.Add(common.All...)
	
	text := "The event starts at 3pm tomorrow and ends at 5pm the day after"
	base := time.Now()
	
	// 查找所有匹配
	var results []*rules.MatchResult
	for {
		r, err := w.Parse(text, base)
		if err != nil || r == nil {
			break
		}
		results = append(results, r)
		text = text[r.Index+len(r.Text):] // 继续解析剩余文本
	}
	
	for i, r := range results {
		fmt.Printf("Match %d: %q -> %v\n", i+1, r.Text, r.Time)
	}
}

常见用例

1. 解析相对时间

text := "in 2 hours"
r, _ := w.Parse(text, time.Now())
fmt.Println(r.Time) // 当前时间 + 2小时

2. 解析绝对时间

text := "January 15, 2023 at 3pm"
r, _ := w.Parse(text, time.Now())
fmt.Println(r.Time) // 2023-01-15 15:00:00 +0000 UTC

3. 解析模糊时间

text := "next Monday"
r, _ := w.Parse(text, time.Now())
fmt.Println(r.Time) // 下周一 00:00:00

性能优化

对于需要频繁解析的场景，可以重用 when 实例：

var parser *when.Parser

func init() {
	parser = when.New(nil)
	parser.Add(en.All...)
	parser.Add(common.All...)
}

func ParseDateTime(text string) (time.Time, error) {
	r, err := parser.Parse(text, time.Now())
	if err != nil || r == nil {
		return time.Time{}, fmt.Errorf("could not parse date/time")
	}
	return r.Time, nil
}

注意事项

1. 解析器对输入文本的大小写不敏感
2. 对于模糊匹配，结果可能不是用户预期的，需要适当验证
3. 复杂的日期时间表达式可能需要自定义规则
4. 不同语言规则可能需要单独添加

when 库为处理自然语言日期时间提供了强大而灵活的工具，特别适合聊天机器人、日历应用等需要处理用户自由输入日期时间的场景。