Go 字符串按字节截断破坏中文的修复

Go 字符串按字节截断会破坏中文，根因是 string 保存的是字节序列，而不是固定宽度的字符数组。需要按 Unicode code point 截断时，先把字符串转换为 []rune 再切片；如果目标是终端或表格对齐，还要另外计算显示宽度。

官方资料：https://pkg.go.dev/unicode/utf8

一、先区分字节长度与字符边界

ASCII 字符通常一个字节就能表示，所以只用英文测试时，s[:n] 看起来没有问题。中文字符在 UTF-8 中通常占 3 个字节，截断位置如果落在这 3 个字节中间，结果就不是一个完整字符。

package main

import "fmt"

func main() {
	text := "Go中文"
	// len 统计字节；这里不能把结果直接当作字符数量。
	fmt.Println(len(text))
	// 只取前 4 个字节，可能把“中”的 UTF-8 编码截断。
	fmt.Printf("%q\n", text[:4])
}

排查这类问题时，先同时打印 len(s) 与 utf8.RuneCountInString(s)。两者不同并不代表数据损坏，只说明文本里存在多字节编码。

二、用 rune 截断并保留完整字符

如果业务规则是“最多保留 12 个 Unicode 字符”，可以把字符串转换成 rune 切片后再截取。这个边界对应 Unicode code point，适合昵称、摘要、日志字段等需要避免乱码的场景。

package textutil

// TruncateRunes 按 rune 数量截断，保证不会切入一个 UTF-8 字符。
func TruncateRunes(s string, limit int) string {
	if limit 

若只是需要统计字符数，不必先转换切片，可使用 utf8.RuneCountInString。若接口必须避免额外分配，也可以用 utf8.DecodeRuneInString 逐个累加字节宽度，在达到上限时返回原字符串的字节前缀。

三、处理非法 UTF-8 与输入边界

如果字符串来自 HTTP 请求、文件或消息队列，最好先明确输入是否必须是合法 UTF-8。标准库的 utf8.ValidString 可以做判断；直接转换为 []rune 时，非法编码会被替换为 utf8.RuneError，这可能掩盖上游数据问题。

package textutil

import "unicode/utf8"

// SafeTruncateRunes 只接受合法 UTF-8，调用方可据此返回 400 或记录数据源错误。
func SafeTruncateRunes(s string, limit int) (string, bool) {
	if !utf8.ValidString(s) {
		// 外部字节流有编码错误时，不把替换字符当作正常结果。
		return "", false
	}
	return TruncateRunes(s, limit), true
}

空字符串、上限为 0、上限大于文本长度都应写进测试。还要注意“字符”在业务上可能指 grapheme cluster，例如一个基础字母加组合音标在用户眼中是一个字形，但在 rune 层面可能是多个 code point。

四、不要把 rune 数量当成显示宽度

三种长度要分开命名：字节长度用于存储和切片边界，rune 数量用于 Unicode code point 级别的截断，显示宽度用于终端列、等宽表格和部分日志布局。中文全角字符通常占两列，emoji 的列宽还取决于终端实现，组合字符可能不额外占列。

因此，接口字段限制应先确认产品口径：限制“最多 20 个字符”就按 rune；限制“最多 40 列”则应使用能识别 East Asian Width 和组合字符的显示宽度库。不要为了让表格对齐，简单地把字节数除以 2。

五、上线前的截断检查清单

• 找到所有 s[:n]、string([]byte(s)[:n]) 等按字节截断点，确认它们是否处理 UTF-8 文本。
• 为中文、英文、emoji、组合字符和非法字节分别增加边界测试。
• 在代码中明确变量单位，例如 maxRunes、maxBytes、maxColumns，不要只写 limit。
• 日志摘要可以按 rune 截断；终端表格和命令行输出必须按显示列宽处理。

相关问题

为什么 range 适合遍历中文字符串？

range 会按 UTF-8 解码得到 rune 和字节起点，适合按字符边界处理；但它仍不等同于用户感知的字形数量。

什么时候应该按字节限制？

当协议、数据库字段或存储层明确限制字节数时才按字节限制，并在切割后用 utf8.ValidString 检查，避免生成半个字符。