Go rune 与字节偏移混用导致截断的修复

我在处理中文摘要截断时遇到过一种很隐蔽的错位：代码看起来只是把前 12 个字符留下，结果中文被截成乱码，或者英文正常、换成 emoji 就突然少一截。根因通常不是 UTF-8 本身，而是把 rune 数量当成了字符串的字节偏移。

Go 的 string 索引和切片边界都是字节偏移；按可见长度截断应沿着 range 找 rune 的字节起点，按传输或存储预算截断则应把边界退回到合法 UTF-8 起点。

先把字节偏移和 rune 位置分开

Go 规范把字符串定义为不可变的字节序列，因此 len("界") 是 3，而不是 1。字符串下标取到的是 byte；如果把 utf8.RuneCountInString(s) 返回的数量直接用于 s[:n]，遇到多字节字符就会在错误位置停下。

我现在排查这类问题会同时写出三个量：字节长度、rune 数量和边界位置。下面的代码只做观察，不把输出伪装成运行截图。

package main

import (
    "fmt"
    "unicode/utf8"
)

func inspect(s string) {
    // len 统计字节，RuneCountInString 统计 UTF-8 解码后的 rune 数量。
    fmt.Println("bytes:", len(s), "runes:", utf8.RuneCountInString(s))
    for byteOffset, r := range s {
        // range 的 byteOffset 是 rune 的字节起点，不是第几个字符。
        fmt.Printf("offset=%d rune=%q width=%d\n", byteOffset, r, utf8.RuneLen(r))
    }
}

关键判断是：位置变量如果来自 range，可以继续用于字符串切片；位置变量如果来自“第几个 rune”的计数，就必须先转换成字节起点。两者不能互换。

按 rune 边界截取字符串的修复写法

标题、摘要、日志展示这类需求通常表达的是“最多保留几个 rune”。不要先把数字塞进 s[:n]，而是让 range 找到第 n 个 rune 的起点，再按字节切片。这样 ASCII 和中文走同一套逻辑，也不会为了一个简单展示需求复制整段 []rune。

// prefixByRunes 按 rune 数量保留前缀，返回值仍是合法 UTF-8 边界。
func prefixByRunes(s string, n int) string {
    if n = len(s) {
        return s
    }
    // limit 落在多字节 rune 中间时，向前退到 rune 起点。
    for limit > 0 && !utf8.RuneStart(s[limit]) {
        limit--
    }
    return s[:limit]
}

这里有两个容易混淆的边界。第一，prefixByRunes 的参数是可见长度，适合标题、摘要和分页展示；第二，prefixByBytes 的参数是协议或存储预算，适合固定字节字段。后者不能简单改名成“字符截断”，否则调用方会误以为单位是 rune。

如果输入可能包含无效 UTF-8，要先决定策略：可以拒绝输入，也可以让 Go 的解码规则把错误编码视为宽度为 1 的错误 rune。不要在函数内部悄悄替换数据，因为这会改变字节预算和审计内容。

保留字节偏移时如何避免截断

实际迁移时我会先查四类调用：直接下标、切片表达式、长度校验，以及把偏移写入缓存或数据库的代码。只修显示层往往不够，前面如果已经保存了一个 rune 计数，后面仍可能把它当字节偏移再次切片。

还要注意 range 解决的是 Unicode code point 边界，不等于用户看到的“一个字”。例如一个带组合音标的字形，或一个带肤色修饰符的 emoji，可能由多个 rune 组成。需要按用户感知字符处理时，应引入明确的 grapheme cluster 策略，而不是把 []rune 当作最终答案。

// byteOffsetAtRune 把第 n 个 rune 的位置转换成字符串字节偏移。
func byteOffsetAtRune(s string, n int) int {
    if n 

迁移检查清单与适用边界

提交修复前可以按这张清单回归：ASCII、中文、4 字节 emoji、空字符串和负数上限都测一遍；检查截断结果是否仍是合法 UTF-8；确认字段文档写的是 bytes 还是 runes；最后补一个组合字符样例，避免把“rune 安全”误写成“用户感知字符安全”。

我的取舍是：展示长度优先用按 rune 边界的前缀函数，协议字段优先用按字节预算回退边界的函数，业务如果要求“一个屏幕上看到几个字符”，则另外定义用户感知字符规则。把单位写进函数名和参数注释，通常比一次性把所有字符串转换成 []rune 更容易维护。

常见疑问

为什么 range 的索引还叫字节偏移？ 因为它标记的是当前 rune 在原字符串中的 UTF-8 起始字节，恰好可以安全地用作切片边界。

把字符串转成 []rune 能彻底解决吗？ 只能解决按 code point 计数的问题，还不能代表用户感知字符，也可能增加分配和复制成本。