Go x/text/secure/precis UsernameCaseMapped 怎样规范账户名

如果账户名允许国际化字符，注册和登录最容易出现的隐性问题不是“字符串能不能存进数据库”，而是同一个人的输入是否会被应用当成同一个身份。golang.org/x/text/secure/precis 的 UsernameCaseMapped 适合承担这一层：先按 PRECIS 用户名规则准备并校验输入，再把成功结果作为账户身份键使用。

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

实际落地时记住一句话：显示名可以保留原样，但注册、登录和唯一性判断都应该围绕同一份规范值。规范化返回错误时不要把原始输入偷偷写入身份字段；它只是一个无效账户名，应交给上层返回可理解的提示。

UsernameCaseMapped 先解决什么问题

PRECIS 用于国际化字符串的准备、强制执行和比较。这个包的文档把 UsernameCaseMapped 标记为 RFC 8265 定义的用户名配置文件，并把它放在 Identifier 类这一类偏向安全标识符的规则体系中。它不是密码哈希，也不是登录鉴权组件，而是把“输入的账户名长什么样”变成应用可以稳定处理的字符串规则。

在 Go 代码里，配置文件已经由包提供，通常不需要自己拼接大小写转换、Unicode 归一化和字符过滤：

package main

import (
    "fmt"

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

func canonicalUsername(input string) (string, error) {
    // UsernameCaseMapped 负责按用户名 profile 准备并校验 UTF-8 输入。
    canonical, err := precis.UsernameCaseMapped.String(input)
    if err != nil {
        // 无效输入不能落入身份字段，交给调用方转换成表单或接口错误。
        return "", fmt.Errorf("invalid username: %w", err)
    }
    return canonical, nil
}

这里最重要的不是把函数包起来，而是保留错误。成功返回的字符串是后续唯一性判断和查找的候选值；失败则说明这次输入不能按该 profile 使用。

规范化并不等于保留显示文本

账户名通常有两个概念：给人看的显示文本，以及用于身份判断的规范文本。两者不必相同。页面可以展示用户原本输入的昵称，但数据库中的唯一索引、登录查询或业务关联应使用通过 profile 得到的规范值。这样做也能避免同一用户因为输入大小写或等价字符表现不同而形成两条身份记录。

可以把职责拆成两个字段：

不要把“数据库排序规则不区分大小写”当成 PRECIS 的替代品。数据库排序只解决某种比较或排序语义，不能替应用完成同一套输入准备、字符允许范围和错误处理。

空字符串和错误应当在入口处处理

如果业务不接受空账户名，可以在规范化 profile 上增加 DisallowEmpty 选项。包文档把它定义为：当结果会变成空字符串时，让 enforcement 步骤返回错误。它和 HTTP 表单的“必填”校验不是一回事：前者属于 profile 规则，后者属于交互层，两层可以同时存在。

package main

import (
    "fmt"

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

func canonicalNonEmptyUsername(input string) (string, error) {
    // 复制官方 profile 的语义，并额外要求规范化结果不能为空。
    profile := precis.NewIdentifier(precis.DisallowEmpty)
    canonical, err := profile.String(input)
    if err != nil {
        // 这里统一返回错误，调用方可以映射成“账户名不可用”。
        return "", fmt.Errorf("username rejected: %w", err)
    }
    return canonical, nil
}

上面的示例用于说明选项边界：如果目标是严格采用包预定义的 UsernameCaseMapped，优先直接调用它；如果产品需要额外的空值政策，应先确认该自定义 profile 是否仍然符合业务的用户名协议，再把它作为明确的工程决策记录下来。不要因为示例能运行，就把 NewIdentifier 当作与 UsernameCaseMapped 完全等价的替代实现。

注册和登录必须走同一条规范路径

注册时先得到规范值，再检查唯一性并写入；登录时对用户输入执行同样的规范化，再用规范值查找。最常见的错误是注册路径做了转换，登录路径却直接拿原始文本查询，结果是“刚注册的账户登录不上”。

type Account struct {
    DisplayName      string
    UsernameCanonical string
}

func prepareAccount(input, displayName string) (Account, error) {
    // 注册和登录都应调用同一个规范化函数，避免两条路径规则漂移。
    canonical, err := canonicalUsername(input)
    if err != nil {
        return Account{}, err
    }
    return Account{
        DisplayName:       displayName,
        UsernameCanonical: canonical,
    }, nil
}

数据库层面应给 username_canonical 建唯一约束，但仍要保留应用层错误判断：唯一索引处理并发注册竞态，profile 处理输入语义，两者解决的是不同问题。写入失败时也不要回退到原始账户名重试。

Compare 和 CompareKey 怎么选

Profile.Compare(a, b) 会对两边执行 profile，再按字节级相等判断；任意一边无法通过 enforcement 时，结果为 false。它适合一次性的等价判断，例如判断两个来自不同输入框的账户名是否代表同一规范值。

func sameUsername(left, right string) bool {
    // Compare 统一处理双方输入，失败时返回 false，不会把无效值当成相等。
    return precis.UsernameCaseMapped.Compare(left, right)
}

Profile.CompareKey(s) 返回可用于比较、哈希或排序的字符串。需要把规范账户名放进内存 map、缓存键或排序结构时，可以先计算比较键；但仍应处理错误，不能用空字符串或原始输入作为兜底键。

func usernameKey(input string) (string, error) {
    // CompareKey 的输出用于查找键，错误必须继续向上传递。
    key, err := precis.UsernameCaseMapped.CompareKey(input)
    if err != nil {
        return "", fmt.Errorf("cannot build username key: %w", err)
    }
    return key, nil
}

如果系统已经把规范字符串作为唯一字段保存，普通数据库查询通常直接用该字段即可；不要为了“保险”在查询条件里同时混入原始显示名和规范名，否则查询语义会变得含糊。

升级依赖时要留意什么

当前包文档明确提醒它仍在建设中，API 可能发生不向后兼容的变化。因此依赖升级不能只看编译是否通过，还应把账户名回归样例固定下来：ASCII 大小写、包含非 ASCII 字符的合法输入、被规则拒绝的输入、规范化后为空的输入，以及注册和登录使用同一输入的情况。

测试关注的是契约，而不是某个实现细节：

func TestUsernameCanonicalization(t *testing.T) {
    // 只断言业务需要的稳定契约：可接受输入能得到规范值，非法输入会报错。
    got, err := canonicalUsername("Alice")
    if err != nil {
        t.Fatal(err)
    }
    if got == "" {
        t.Fatal("canonical username must not be empty")
    }

    if _, err := canonicalUsername("\u0000"); err == nil {
        t.Fatal("invalid control character must be rejected")
    }
}

不要把某个具体 Unicode 表格版本或内部映射表复制进业务代码。升级时应重新阅读官方文档，确认依赖版本、profile 定义和测试期望，再安排数据库唯一约束与登录查询的回归。

结论：规范值是身份键，显示名只是展示层

UsernameCaseMapped 的正确用法可以压缩为四点：入口统一调用 profile；错误不落库；规范值单独作为身份字段；比较和查找使用 Compare 或 CompareKey 的明确语义。这样既能支持国际化账户名，也能把规范化规则和认证、展示、数据库并发控制分开。

常见问题

UsernameCaseMapped 是密码加密吗？

不是。它用于字符串准备、规范化和校验；密码仍需要独立的密码哈希和认证流程。

可以只调用 strings.ToLower 吗？

不建议把简单大小写转换当成 PRECIS profile。账户名的允许字符、规范化和错误边界不只由 ASCII 大小写决定。

为什么还要保存 display_name？

规范值适合身份查找，但展示文本可能需要保留用户输入的可读形式。分开字段可以避免把 UI 文本和身份键混成一个概念。

Compare 返回 false 是不是一定表示两个字符串不同？

不一定。任意输入无法通过 enforcement 时也会返回 false；如果需要区分“无效输入”和“规范后不相等”，请先分别调用 String 并处理错误。