Go 怎样把时间格式化追加到已有字节切片

如果日志、协议字段或缓存键本来就是一段 []byte，不必先调用 time.Time.Format 得到临时字符串，再把字符串转回字节。Go 标准库提供的 Time.AppendFormat 可以把格式化后的时间直接追加到已有字节切片，并返回扩展后的切片。

官方资料：https://pkg.go.dev/time#Time.AppendFormat

一句话用法：dst = t.AppendFormat(dst, layout)。左侧的 dst = 不能省略，因为追加可能复用原数组，也可能返回一个已经扩容的新切片。

先用 AppendFormat 追加时间

AppendFormat 的签名是 func (t Time) AppendFormat(b []byte, layout string) []byte。它接收目标切片和 Go 的时间布局字符串，把文本追加到目标末尾。下面的例子先放入固定前缀，再追加一个 RFC 3339 时间。

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2026, time.October, 17, 16, 30, 0, 0, time.FixedZone("CST", 8*60*60))

	// 先把固定字段放入目标切片，后面的时间文本会接在它后面。
	line := []byte("created_at=")

	// AppendFormat 返回追加后的切片，必须接住返回值。
	line = t.AppendFormat(line, time.RFC3339)

	fmt.Println(string(line))
}

created_at=2026-10-17T16:30:00+08:00

这里的布局仍然遵循 Go 的参考时间规则。若要输出日期加时间，直接使用 time.RFC3339；若是自定义协议字段，则传入类似 "20060102-150405" 的布局。AppendFormat 只负责格式化并追加，不会替你决定时区。

为什么一定要接住返回的切片

切片只是数组的一段描述，包含指针、长度和容量。追加时，如果原切片的容量足够，运行时可以继续使用同一个底层数组；如果容量不够，append 语义允许分配新数组并返回新的切片描述。AppendFormat 也遵循同一规则。

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2026, time.October, 17, 16, 30, 0, 0, time.UTC)

	// 预留空间只是给追加提供复用机会，不代表永远不会扩容。
	line := make([]byte, 0, 40)
	line = append(line, "ts="...)

	// 接住返回值，才能同时覆盖复用底层数组和扩容两种情况。
	line = t.AppendFormat(line, time.RFC3339)

	fmt.Printf("%s\\n", line)
}

常见错误是只调用方法而丢弃返回值：

// 错误示例：调用结果没有写回 line，后续仍看不到追加内容。
line = []byte("ts=")
t.AppendFormat(line, time.RFC3339)
fmt.Println(string(line)) // 仍然只有 ts=

即使这次调用碰巧复用了底层数组，长度也仍然由切片头中的 len 决定；不接返回值就不会把新的长度交给调用方。

用容量复用减少临时字符串

当一行内容本来就要继续用字节切片拼接时，AppendFormat 可以省掉“先得到格式化字符串”的中间步骤。下面把时间、级别和消息一起组成一行日志，调用方只维护一个目标切片。

package logline

import "time"

func AppendLine(dst []byte, ts time.Time, level, message string) []byte {
	// 追加固定分隔符和级别，保持日志字段顺序稳定。
	dst = append(dst, '[')
	dst = ts.AppendFormat(dst, time.RFC3339Nano)
	dst = append(dst, "] ["...)
	dst = append(dst, level...)
	dst = append(dst, "] "...)
	dst = append(dst, message...)
	dst = append(dst, '\n')
	return dst
}

调用方可以把返回结果继续交给下一个追加步骤，也可以在一轮写入完成后交给文件或网络层。是否真的减少分配，取决于目标切片的容量、布局长度以及后续代码是否又创建了别的临时对象。

Format 和 AppendFormat 怎么选

两者的格式规则相同，区别主要在结果形态和拼接路径：

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2026, time.October, 17, 16, 30, 0, 0, time.UTC)
	layout := "2006-01-02 15:04:05"

	// 需要 string 时，Format 的返回值更直接。
	text := t.Format(layout)
	fmt.Println(text)

	// 需要拼接多个字节字段时，直接沿着 []byte 追加。
	buf := make([]byte, 0, 32)
	buf = append(buf, "time="...)
	buf = t.AppendFormat(buf, layout)
	fmt.Println(string(buf))
}

不要把“使用 AppendFormat”理解成“这个路径一定零分配”。目标容量不足时可能扩容；如果使用 AppendFormat(nil, layout)，也只是得到一段新切片，并没有复用外部缓冲区。性能结论应由真实调用路径和基准测试决定。

布局和时区要在调用前确定

AppendFormat 不会改变 time.Time 的时区。相同的瞬时时间在 UTC 和本地时区下可能产生不同文本，因此协议、日志和缓存键应在边界处明确时区，再把确定后的时间传给格式化函数。

package main

import (
	"fmt"
	"time"
)

func main() {
	instant := time.Date(2026, time.October, 17, 8, 30, 0, 0, time.UTC)

	// 协议字段固定使用 UTC，避免机器本地时区造成文本漂移。
	utcText := make([]byte, 0, 32)
	utcText = instant.UTC().AppendFormat(utcText, time.RFC3339)

	// 展示给本地用户时，再显式转换到目标地点。
	loc, err := time.LoadLocation("Asia/Shanghai")
	if err != nil {
		// 时区数据不可用时返回错误，避免静默写出错误时间。
		panic(err)
	}
	localText := make([]byte, 0, 32)
	localText = instant.In(loc).AppendFormat(localText, time.RFC3339)

	fmt.Println(string(utcText))
	fmt.Println(string(localText))
}

布局字符串本身也应当集中管理。不要在多个调用点随意混用 time.RFC3339、time.RFC3339Nano 和自定义布局，否则下游解析、排序或签名逻辑可能因为精度和分隔符不同而出现不一致。

共享缓冲区时要区分切片和时间值

time.Time 可以按值传递，但用于接收追加结果的 []byte 仍然是可变数据。多个 goroutine 不能同时把同一目标切片当作自己的工作缓冲区；正确做法是每个请求拥有自己的切片，或由明确的池化策略借出和归还。

package logline

import "time"

func NewLine(ts time.Time, message string) []byte {
	// 每次调用创建独立的工作切片，避免调用者之间共享可变后备数组。
	line := make([]byte, 0, 64)
	line = ts.AppendFormat(line, time.RFC3339)
	line = append(line, ' ')
	line = append(line, message...)
	return line
}

如果使用 sync.Pool 复用缓冲区，要在归还前把切片重置为零长度，并确认不会把仍被异步写入或发送的数据放回池中。AppendFormat 只解决格式化追加这一段，不会替你管理缓冲区生命周期。

用小用例固定最终字节序列

接入日志或协议编码前，可以用一个固定时间检查前缀、布局和时区是否都符合预期。测试关注输出字节序列，不要只测切片容量。

package timebytes

import (
	"testing"
	"time"
)

func TestAppendFormat(t *testing.T) {
	tm := time.Date(2026, time.October, 17, 8, 30, 0, 0, time.UTC)
	buf := []byte("created_at=")

	// 用固定 UTC 时间锁定布局结果，避免测试受本机时区影响。
	buf = tm.AppendFormat(buf, time.RFC3339)

	want := "created_at=2026-10-17T08:30:00Z"
	if string(buf) != want {
		t.Fatalf("got %q, want %q", buf, want)
	}
}

若以后改成纳秒布局、改用本地时区或调整前缀，测试会直接暴露协议文本变化。若要评估性能，再单独编写基准，让基准数据服务于真实的缓冲区大小和字段组合，而不是把单独一次格式化调用当成最终结论。

采用前可以记住这份清单

1. 已有 []byte 且还要继续拼字段时，优先考虑 dst = t.AppendFormat(dst, layout)。
2. 一定接住返回值，因为追加可能扩容并返回新的切片描述。
3. 预留容量可以减少扩容机会，但不能把 AppendFormat 宣称为无条件零分配。
4. 需要 string 时继续使用 Format，不要为了追求 API 名称改变结果类型。
5. 在调用前固定布局和时区，并避免多个并发任务共享同一个可变工作切片。

常见问题

AppendFormat 会修改原来的时间吗？

不会。它读取 time.Time 的值，把格式化文本追加到传入的字节切片，并返回切片结果。时间值本身不会因为格式化而改变。

为什么调用 AppendFormat 后原切片看起来没变化？

最常见原因是没有接住返回值。切片长度由调用方持有的切片头决定，即使底层数组被复用，调用方也要使用 dst = t.AppendFormat(dst, layout) 更新长度和指针信息。

AppendFormat 一定比 Format 快吗？

不能脱离场景下结论。已有字节缓冲区并继续拼接时，它可以避开中间字符串这条路径；但最终效果仍取决于容量、后续转换、写入接口和完整调用链，应通过贴近业务的基准确认。