Go go-chart 怎样为图表设置时间轴

我在给监控数据补时间轴时，最容易把问题想简单：以为给 XAxis 填一个日期格式就完成了。实际上，go-chart/v2 的时间轴由两层组成：TimeSeries 负责把 []time.Time 和 []float64 配成一条线，XAxis 再负责横轴名称、范围、刻度和标签格式。先把这两层分开，时间轴就不容易出现回折、日期丢失或标签挤成一团。

官方文档：https://pkg.go.dev/github.com/wcharczuk/go-chart/v2

最稳妥的做法是：时间点与数值成对准备，提交图表前按时间升序排列并统一时区，然后在 XAxis.ValueFormatter 中根据跨度选择日期时间格式。格式化器只改变标签显示，不会替你修复乱序数据或不一致的时间语义。

先理解 TimeSeries 和 XAxis 各自负责什么

官方 API 中，TimeSeries 有 XValues []time.Time 和 YValues []float64，它代表一条以时间为横坐标的折线。XAxis 是水平轴，包含名称、范围、刻度、网格线和 ValueFormatter 等配置。也就是说，前者回答“每个点是什么”，后者回答“横轴怎样被读懂”。

这一区分很有用：如果折线回折，先检查输入时间顺序；如果折线正常但标签不可读，再检查格式化器和刻度跨度；如果点数异常，回到两组切片是否一一对应。

用 TimeSeries 提供时间点和数值

下面的示例用固定时区构造几条观测数据，并让 XAxis 显示“月-日 时:分”。示例重点不是业务数据，而是把时间值和数值放入同一个序列，并在渲染前完成文件关闭与错误处理。

package main

import (
	"log"
	"os"
	"time"

	chart "github.com/wcharczuk/go-chart/v2"
)

func main() {
	// 固定展示时区，避免同一批数据在不同机器上出现不同的日期标签。
	loc := time.FixedZone("CST", 8*60*60)
	base := time.Date(2026, 10, 31, 9, 0, 0, 0, loc)

	// XValues 与 YValues 按下标配对：第 i 个时间点对应第 i 个数值。
	xValues := []time.Time{
		base,
		base.Add(30 * time.Minute),
		base.Add(60 * time.Minute),
		base.Add(90 * time.Minute),
	}
	yValues := []float64{18, 23, 21, 29}

	series := chart.TimeSeries{
		Name:    "请求量",
		XValues: xValues,
		YValues: yValues,
		Style: chart.Style{
			StrokeColor: chart.GetDefaultColor(0),
			StrokeWidth: 2,
		},
	}

	graph := chart.Chart{
		XAxis: chart.XAxis{
			Name: "时间",
			// 只控制刻度文本的显示格式，不改变 XValues 的实际时间。
			ValueFormatter: chart.TimeValueFormatterWithFormat("01-02 15:04"),
		},
		Series: []chart.Series{series},
	}

	file, err := os.Create("time-axis.png")
	if err != nil {
		log.Fatalf("创建图表文件失败: %v", err)
	}
	defer file.Close() // 延迟关闭文件，确保渲染器写完后释放描述符。

	if err := graph.Render(chart.PNG, file); err != nil {
		log.Fatalf("渲染时间轴图表失败: %v", err)
	}
}

TimeValueFormatterWithFormat 的作用是把横轴的时间值格式化成可读文本；它不会把时间点排序，也不会替你把不同地点的时间换算成同一时区。若想显示完整日期，可以把格式改成 2006-01-02 15:04；若数据只跨几个小时，01-02 15:04 通常更紧凑。

把排序和时区放在格式化之前

时间轴最隐蔽的错误是“标签看起来像时间，但顺序并不代表真实时间”。采集数据时应把时间点和数值封装成同一个结构，排序时按时间排序整行，而不是只排序 XValues。否则图表虽能渲染，点与点的业务含义已经错位。

type sample struct {
	at    time.Time
	value float64
}

// 先按时间排序完整样本，保持时间点和数值的配对关系。
sort.Slice(samples, func(i, j int) bool {
		return samples[i].at.Before(samples[j].at)
})

// 排序完成后再拆成图表需要的两组切片。
xValues := make([]time.Time, 0, len(samples))
yValues := make([]float64, 0, len(samples))
for _, item := range samples {
	xValues = append(xValues, item.at)
	yValues = append(yValues, item.value)
}

如果原始记录来自多个地区，先约定一个展示时区，再用 t.In(loc) 转换。不要在一张图里让一部分时间用本地时区、另一部分时间用 UTC；那样横轴的日期边界可能被误读为业务事件。

根据跨度选择刻度格式

格式选择可以按读者要回答的问题来定，而不是盲目追求最完整的时间字符串：

标签过密时，先考虑减少横轴展示的信息量或缩短时间跨度，再考虑调整画布尺寸。不要把每个采样点都强行变成一个标签；点可以很多，刻度只需要帮助读者建立时间参照。

时间轴异常时按三层排查

1. 数据层：确认 len(XValues) == len(YValues)，每个时间点都有对应数值，并检查时间是否有意外回退。
2. 语义层：确认所有时间是否已经转换到同一地点或 UTC，避免夏令时或跨日边界造成误解。
3. 显示层：确认 XAxis.ValueFormatter 的布局与跨度匹配；日期信息缺失或标签过密，通常属于显示配置问题。

如果线条位置正确但刻度文字不符合预期，优先查看格式化器；如果刻度顺序与业务时间不一致，优先查看原始数据和排序。把这三层分开，通常比不断更换日期格式更快。

常见问题

go-chart 会自动把时间点排序吗？

不要把绘图库当成数据整理器。准备 TimeSeries 时应由业务代码保证时间顺序，并把时间点与数值作为一条记录一起排序。

只设置 XAxis 的格式化器能修复时区吗？

不能。格式化器只负责把值展示成文本；时区转换要在准备 XValues 时明确完成。

为什么日期标签挤在一起？

通常是时间跨度、画布宽度和标签格式不匹配。优先缩短格式或减少刻度信息，不要把每个数据点都当成一个刻度标签。

TimeSeries 的时间点和数值长度不一致怎么办？

在构造序列前就拒绝这批数据，并记录缺失点或补值策略；不要依赖渲染阶段猜测哪一个数组应该被截断。

总结一下，Go go-chart 的时间轴可以按“数据配对—时间语义—轴格式”三层处理：TimeSeries 放入成对的数据，排序并统一时区后，再用 XAxis.ValueFormatter 选择适合跨度的标签。这样设置出来的横轴不仅能显示时间，更能让读者相信它表达的顺序和边界。