Go x/text/secure/precis 用户名规范化为什么会改变输入字符

Go 的 golang.org/x/text/secure/precis 不是简单地把用户名做一次 trim。它按照 PRECIS profile 对国际化字符串执行准备、强制和比较规则，因此输入字符可能被映射、折叠或被判定为不允许。最容易遇到的情况是：原始用户名看起来只是大小写或宽窄形式不同，经过 UsernameCaseMapped 后却得到另一种规范化结果。

官方地址：https://pkg.go.dev/golang.org/x/text/secure/precis

这些字符变化通常不是 Go 原地改写了你的字符串，而是 profile 返回了“应用规则后的新字符串”。用户名系统应该明确区分原始输入、规范化后的存储值和用于唯一比较的键；只要返回错误，就不要把未通过 profile 的输入写入唯一索引。

• 输入变化的原因：PRECIS profile 允许执行映射、规范化和大小写相关规则。
• 两个常用选择：UsernameCaseMapped 面向统一比较形式，UsernameCasePreserved 保留大小写表现。
• 错误边界：Profile.String、Bytes 等 API 在输入无法通过 profile 时返回错误。
• 架构边界：展示名可以保留原始输入，但唯一性判断应使用经过 profile 的结果或 CompareKey。

先看清 precis 处理的三层职责

precis 文档把它定义为国际化字符串的 preparation、enforcement 和 comparison 实现。可以把它理解为三层约束：先把输入变成规则能够处理的形式，再检查 profile 允许的字符和边界，最后用同一套规则进行比较。只要其中某个步骤改变了字符，最终返回的字符串就不会与原始输入逐字相同。

因此，看到“输入字符变了”时，第一反应不应该是检查 Go 字符串是否被修改。Go 字符串值本身不会被 Profile.String 原地改写；这个方法返回的是应用 profile 后的新结果。profile 可能包含大小写映射、宽窄折叠或 Unicode 规范化选项，具体规则由 profile 决定，而不是由调用者临时猜测。

为什么 UsernameCaseMapped 会改变输入字符

UsernameCaseMapped 的名字已经说明了它的主要取舍：用户名在比较时需要统一形式，因此 profile 可以应用大小写映射等规则。对于英文用户名，大小写差异可能被折叠到同一个比较形式；对于其他 Unicode 字符，是否允许、如何映射，则要以 profile 的实际规则和 Unicode 表为准，不能只凭肉眼判断。

这也是“用户名显示什么”和“用户名是否相等”必须拆开的原因。业务如果希望用户看到自己输入的大小写，可以把原始输入作为展示字段；业务如果需要防止同一用户名以不同大小写重复注册，就应保存 profile 处理后的值或专用比较键。两者混成一个字段，后续很容易出现页面显示与唯一索引含义不一致。

package main

import (
	"fmt"

	"golang.org/x/text/secure/precis"
)

func main() {
	raw := "Alice-Admin"

	// UsernameCaseMapped 返回应用 profile 后的新字符串，不会原地改写 raw。
	normalized, err := precis.UsernameCaseMapped.String(raw)
	if err != nil {
		// 规范化失败时不要把原始输入当成可用用户名继续落库。
		fmt.Printf("用户名不可用: %v\n", err)
		return
	}

	fmt.Printf("原始=%q 规范化=%q\n", raw, normalized)
}

这段代码的重点不是预先写死某个 Unicode 字符一定会变成什么，而是把返回值和错误当成 profile 的正式结果。文章标题中的“改变”指的是返回值经过规则处理后与输入不同；它不代表所有字符都会变化，也不代表变化就是异常。

区分 UsernameCaseMapped 和 UsernameCasePreserved

precis 同时提供 UsernameCaseMapped 和 UsernameCasePreserved。前者适合需要把大小写差异纳入统一比较形式的账号标识；后者适合希望保留用户名大小写表现、但仍然接受 PRECIS profile 约束的场景。这里的“保留”不是跳过所有规范化，而是不要把它误解为“任何输入都原样通过”。

一个实用的判断方法是先问清楚用户名在系统中承担什么职责：

如果系统只保存一个字段，通常会在“用户想保留原样”和“系统要稳定去重”之间发生冲突。规模化账号系统更稳妥的做法是让字段职责明确：展示字段负责可读性，规范化字段负责一致性，原始字段是否保留则由审计和隐私要求决定。

在 Go 中保留规范化错误

Profile.String 适合处理字符串，Profile.Bytes 适合处理 UTF-8 字节；两者都会返回应用 profile 后的结果和错误。错误不能被简单吞掉，因为“返回空字符串”或“沿用原始输入”会把非法用户名带进后续存储。需要批量处理或流式处理时，还可以使用 Append 和 NewTransformer，但错误边界仍然要保留。

package account

import (
	"fmt"

	"golang.org/x/text/secure/precis"
)

// PrepareLoginName 只返回可用于登录比较的规范化名称。
func PrepareLoginName(raw string) (string, error) {
	// 统一入口让注册、登录和改名使用同一套 profile 规则。
	name, err := precis.UsernameCaseMapped.String(raw)
	if err != nil {
		// 这里保留错误，调用方可以转换为表单提示或审计事件。
		return "", fmt.Errorf("prepare username: %w", err)
	}
	return name, nil
}

注册和登录应调用同一个准备函数，而不是注册时规范化、登录时只做小写。后者会漏掉 profile 的其他限制，也会让同一个账号在不同入口得到不同结果。真正的系统还应在数据库层为规范化字段建立唯一约束，用并发写入时的约束错误作为最终冲突判断。

把展示值、存储值和比较键分开

precis 提供 Compare 和 CompareKey，它们表达的用途不同。Compare 会对两个字符串执行 profile 并比较处理后的字节身份；CompareKey 返回可用于比较、哈希或排序的字符串。选择哪一个，取决于你是在临时判断相等，还是需要构造稳定的索引键。

package account

import "golang.org/x/text/secure/precis"

// SameLoginName 判断两个输入是否落到同一个登录比较身份。
func SameLoginName(left, right string) bool {
	// Compare 内部会按同一 profile 处理双方，避免两边规则不一致。
	return precis.UsernameCaseMapped.Compare(left, right)
}

// LoginKey 返回适合哈希或唯一索引的比较键。
func LoginKey(raw string) (string, error) {
	// CompareKey 的用途是比较、哈希或排序，不应当替代展示字段。
	return precis.UsernameCaseMapped.CompareKey(raw)
}

一个常见的架构布局是：display_name 保存用户看到的文字，login_key 保存通过 profile 生成的比较键，必要时再用 raw_name 做有限期的审计记录。这样即使规范化改变字符，页面仍可按产品需求展示；唯一性判断也不会退回到未经处理的原始输入。

上线后的排查顺序

如果线上反馈“用户名被改了”，可以按四个问题定位：第一，调用的是哪个 profile；第二，变化发生在注册、登录还是展示层；第三，错误是否被吞掉后又写回了原始字符串；第四，数据库唯一索引使用的是展示字段还是比较键。把这四个问题分开，通常比继续追加字符串替换更容易找到根因。

还要注意，precis 官方文档明确提示该 package 仍在建设中，API 可能在没有兼容性承诺的情况下变化。因此升级依赖时，应该把规范化结果视为协议行为的一部分：先评估已存在账号的键是否需要迁移，再决定是否直接升级，而不是只看编译是否通过。

常见问题

UsernameCaseMapped 会把所有用户名都转成小写吗？

不能把它简化成普通的 ASCII 小写函数。它是 PRECIS profile，可能包含大小写映射、规范化和允许字符判断；具体 Unicode 输入的结果应以 profile 实际返回值为准。

为什么规范化后字符数量也可能变化？

Unicode 规范化和映射不只涉及单个 ASCII 字符，某些字符可能对应不同的编码表示或组合形式。业务应比较 profile 的结果，不要用字节长度变化来判断错误。

UsernameCasePreserved 是否等于完全不处理输入？

不是。它强调保留大小写表现，但仍属于 precis 的用户名 profile，仍然要经过相应的准备和强制规则；输入不满足规则时依然可能返回错误。

展示值可以直接当数据库唯一键吗？

不建议。展示值的职责是可读性，唯一键应由统一 profile 生成，并在数据库层设置唯一约束；否则同一登录身份可能因为大小写或其他 Unicode 表现不同而重复写入。

规范化失败时能否退回原始用户名？

登录或注册比较场景不应自动回退。更安全的做法是保留错误、提示用户修改输入，并让调用方决定是否记录原始输入；原始值不能绕过 profile 直接进入唯一索引。