Go unicode/utf8 截断而不切断 UTF-8

我在给日志摘要和列表标题做长度限制时，最容易踩的坑不是“少截几个字”，而是把 Go 字符串当成字符数组直接按字节切。ASCII 看不出问题，中文或表情一出现，结果就可能落在一个 UTF-8 字符的中间，后续显示成替换字符。

更稳妥的做法是先确认输入是合法 UTF-8，再按 range 看到的每个 rune 累加 utf8.RuneLen，只接受不超过字节上限的完整字符。Go 官方包地址：https://pkg.go.dev/unicode/utf8

如果限制的是存储或传输字节数，就按 UTF-8 字节宽度截断；如果限制的是字符数量，应另算 rune 数量。两者不要混用。

先把“字节上限”和“字符数量”分开

Go 的 string 保存的是字节序列，len(s) 返回字节数；一个中文字符通常占 3 个 UTF-8 字节，部分表情会占 4 个字节。因此 s[:10] 只表示取前 10 个字节，并不保证正好取到第 10 个字符。

本篇只解决“合法 UTF-8 字符串的最大字节数”这个边界。显示宽度、组合字符和按词截断属于另外的问题，不能因为 rune 完整就认为屏幕上一定占一格。

用 range 找到最后一个完整 rune

下面的函数把 maxBytes 明确解释为 UTF-8 编码后的字节上限。先用 utf8.ValidString 拒绝非法输入，然后遍历每个 rune；如果加入当前 rune 会超过上限，就停止，最后用累计的字节数切片。

package main

import "unicode/utf8"

// TruncateUTF8 按 UTF-8 字节上限截取字符串，并保留完整 rune。
// 返回值中的 bool 表示输入是否为合法 UTF-8；maxBytes 不代表字符数量。
func TruncateUTF8(s string, maxBytes int) (string, bool) {
	// 先拒绝非法编码，避免把错误字节悄悄替换成 RuneError。
	if !utf8.ValidString(s) {
		return "", false
	}
	// 非正上限没有可保留的字节，但输入本身仍然是合法的。
	if maxBytes  maxBytes {
			break
		}
		used += width
	}
	return s[:used], true
}

func main() {
	text, ok := TruncateUTF8("Go 中文🙂", 8)
	if !ok {
		return // 调用方可记录坏输入或返回参数错误。
	}
	_ = text // 示例只展示安全截断结果，不把输出伪装成运行截图。
}

这个实现的关键不是“把字符串转成 []rune”后再拼回去，而是保留原字符串并记录完整 rune 占用的字节数。这样不会额外复制整个字符数组，也能清楚表达限制针对的是编码后的字节。

零值、超长上限和非法输入怎么处理

maxBytes 返回空字符串；上限超过原字符串字节数时，循环会把整个字符串保留下来；非法 UTF-8 则返回 false，让调用方决定记录、拒绝还是先做清洗。这里没有把非法字节自动替换为 �，因为替换会改变原始数据语义。

如果业务允许“尽力显示”，可以在边界层先约定替换策略，再调用截断函数；如果业务是签名、协议字段或持久化数据，建议保留失败信号，不要静默修复。

接入日志和摘要字段时的取舍

日志摘要常见的是“最多 N 个字节”，因为下游字段或消息协议有固定容量；这时可以直接复用上面的函数。若产品文案要求“最多 N 个字”，则应使用 rune 计数，或按业务定义的词、组合字符边界处理，不要把 maxBytes 换个名字继续使用。

我通常会在调用点保留两个名字：maxBytes 表示编码容量，maxRunes 表示 Unicode code point 数量。命名把约束写出来，后续维护时比注释更不容易误用。

速查：

相关问题

为什么中文比英文更容易暴露这个问题？

因为 ASCII 字符通常只占一个字节，而中文常见编码宽度更大，任意字节截断更容易切到一个字符中间。

把字符串转成 []rune 是否就一定正确？

它能避免切断 rune，但会改变限制单位并产生额外的 rune 切片；如果业务限制的是 UTF-8 字节容量，仍然需要按每个 rune 的编码宽度计算。