Go strings.ToValidUTF8 清洗日志内容的边界

在日志管线里，strings.ToValidUTF8 适合修复“需要展示的自由文本”，不适合改写请求 ID、签名、哈希、协议字段或审计原文。它只保证结果是有效 UTF-8：不会脱敏，不会移除换行和控制字符，也不会把 GBK 等其他字符集转成 UTF-8。

官方文档：https://pkg.go.dev/strings#ToValidUTF8；UTF-8 校验：https://pkg.go.dev/unicode/utf8；结构化日志：https://pkg.go.dev/log/slog。

目标和边界：先按字段用途决定策略

Go 的 string 能保存任意字节，进入日志器之前必须先回答一个问题：这个字段是供人阅读，还是参与定位、比较、验签或审计？只有第一类字段适合生成清洗后的展示副本。

全流程总览：清洗不是日志入口的第一步

推荐顺序是：限制输入大小 → 脱敏 → UTF-8 规范化 → 处理换行和控制字符 → 结构化编码 → 写入日志后端。这个顺序把资源消耗、隐私、编码有效性和日志注入拆成独立问题，任何一步都不能替代下一步。

先限制大小可以避免超长字段拖垮分配和传输。截断如果刚好切在多字节字符中间，会产生无效尾部，此时再执行 ToValidUTF8 正好修复展示副本。脱敏要放在日志落盘前；实际项目可根据字段模型使用白名单、专用脱敏器或日志处理器，不能指望 UTF-8 替换隐藏令牌和手机号。

阶段一：实现一个有状态的最小清洗函数

utf8.ValidString 用于判断字符串是否完全由有效 UTF-8 编码组成。strings.ToValidUTF8 会把每一段连续的无效 UTF-8 字节替换为指定字符串；替换串可以为空。日志通常使用可见的 U+FFFD，这样异常不会被静默吞掉。

package logtext

import (
    "strings"
    "unicode/utf8"
)

type Result struct {
    Text    string
    Changed bool
}

func Normalize(s string) Result {
    // 正常输入保持原样，并让调用方避免记录误报。
    if utf8.ValidString(s) {
        return Result{Text: s}
    }

    // 每段连续无效字节替换一次，输出成为有效 UTF-8。
    return Result{
        Text:    strings.ToValidUTF8(s, "\uFFFD"),
        Changed: true,
    }
}

Changed 比只返回字符串更重要：监控可以统计异常来源，排查上游编码问题。不要把原始坏字节拼进普通错误日志，否则清洗函数反而把问题重新带回采集链路。

阶段二：接入 slog，但只记录经过分类的字段

log/slog 用消息、级别和键值属性表达结构化日志。将“是否替换”单独作为布尔属性，后端就能按来源聚合，而不必搜索替换字符。

package logtext

import "log/slog"

func WriteMessage(logger *slog.Logger, source, raw string) {
    result := Normalize(raw)

    // source 必须来自受控枚举，不能直接使用用户输入作为字段名。
    logger.Info("外部文本已进入日志管线",
        slog.String("source", source),
        slog.Bool("utf8_replaced", result.Changed),
        slog.String("message", result.Text),
    )
}

这段代码演示 UTF-8 边界，不等于完整安全实现。raw 在进入函数前仍需限长与脱敏，result.Text 还要按日志格式策略处理换行、回车、制表符和其他控制字符。对于必须单行采集的系统，可以把换行编码成可见转义；对于 JSON 行日志，则应由可靠的结构化处理器完成编码。

阶段三：明确 ToValidUTF8 不处理什么

• 不是脱敏器：有效 UTF-8 的密码、令牌、手机号会原样保留。
• 不是防注入器：换行、回车和大多数控制字符本身可以是合法 UTF-8。
• 不是字符集探测器：GBK、Big5 或设备私有编码需要基于明确来源做确定性转码。
• 不是证据保全工具：替换后无法还原原始字节，审计与重放数据必须另存。
• 不是标识符修复器：多个不同坏字节片段可能得到相同替换结果，不能用于唯一键。

推荐流程：用检查点约束每个阶段

1. 入口分类：确认字段是自由文本、关键标识还是原始载荷；未分类字段默认不进普通日志。
2. 资源边界：按字节限制最大长度，并记录是否截断。
3. 隐私边界：删除或遮盖秘密字段，优先记录状态和摘要，而不是完整内容。
4. 编码边界：自由文本执行 Normalize，同时记录 utf8_replaced。
5. 行边界：按后端要求处理换行和控制字符，再交给结构化日志器。
6. 可观测性：按 source 统计替换率；异常突然升高时回查上游协议或字符集约定。

常见误区

直接把替换串设为空是否更干净？

空串会删除每段无效字节，日志看起来整洁，却隐藏了数据被修改的事实。除非字段价值很低并且已经记录修改标记，否则更推荐使用可见替换字符。

清洗后可以覆盖原字段吗？

只对临时展示副本这样做。需要验签、重放、审计或精确故障定位的场景必须保留原始字节，并通过访问控制保护它。

ValidString 和 ToValidUTF8 是否重复扫描？

无效输入会经历判断和替换两次扫描，但正常输入只做一次校验。若调用方不需要 Changed，也可以直接调用 ToValidUTF8；若需要可观测性，显式判断更清楚。

速查表

把 strings.ToValidUTF8 放在正确的位置，它能让日志展示字段保持有效 UTF-8；把它当成安全过滤器、转码器或证据修复器，则会制造更隐蔽的数据问题。真正可靠的做法是先分类字段，再把限长、脱敏、编码规范化、行边界和结构化输出分别落实。