Go uuid UUID 解析大小写和格式失败怎么办

Go 里用 github.com/google/uuid 解析 UUID 时，十六进制字母是大写还是小写通常不会导致失败。更常见的原因是输入前后带空白、连字符位置不对、混入了全角符号，或者把“能解析”误当成了“符合接口规定的唯一格式”。处理链路建议固定为：边界处清理输入，调用 uuid.Parse，按接口需要用 uuid.Validate 做严格格式检查，成功后统一用 String() 输出。

官方文档：https://pkg.go.dev/github.com/google/uuid

先把大小写和真正的格式错误分开

UUID 的十六进制字符可以写成 a 或 A。解析器关心的是十六进制值和结构，不会因为字母大写就判错。下面这段代码更适合放在 HTTP、JSON 或消息消费的边界层：先去掉传输层可能带来的首尾空白，再把错误返回给调用方，而不是直接 panic。

package main

import (
    "fmt"
    "strings"

    "github.com/google/uuid"
)

func parseID(raw string) (uuid.UUID, error) {
    // 只清理边界空白，不要用大小写转换去“修复”结构错误。
    value := strings.TrimSpace(raw)
    id, err := uuid.Parse(value)
    if err != nil {
        // 保留原始错误，便于把 400 与上游字段问题区分开。
        return uuid.Nil, fmt.Errorf("parse request uuid: %w", err)
    }
    return id, nil
}

例如 550E8400-E29B-41D4-A716-446655440000 可以解析；如果同样的值前后有换行或空格，边界层的 TrimSpace 也能避免把传输格式问题误判成 UUID 内容错误。它不会修复中间多一个字符、连字符错位或全角短横线。

Parse 能接受多种形式，不等于接口应该全部放行

uuid.Parse 的兼容面比很多接口约定更宽。官方文档列出的可解析形式包括标准的 36 字符连字符格式、urn:uuid: 前缀形式、大括号包裹形式，以及 32 个十六进制字符的无连字符形式。这样做适合兼容遗留数据，但如果你的 URL、缓存键或数据库字段要求单一文本格式，就不能只看 Parse 是否报错。

需要严格限制输入时，在解析前调用 uuid.Validate(value)，再决定是否继续解析。需要注意的是，官方源码明确提醒：Parse 会解析非标准编码，不应单独拿它做“是否严格符合某种文本格式”的判断。

用 String 固定输出，别让大小写继续向下游扩散

解析得到的是 uuid.UUID，不是原始字符串的副本。调用 String() 会得到标准的带连字符文本，适合写入响应、日志关联字段和规范化后的缓存键。不要把用户传入的原文直接回写给下游，否则同一个 UUID 可能出现大写、小写、URN 和大括号多个文本键。

func normalizeUUID(raw string, strict bool) (string, error) {
    // 统一处理传输层空白，避免只在部分入口做清理。
    value := strings.TrimSpace(raw)
    if strict {
        // 严格入口只允许约定的 UUID 文本格式。
        if err := uuid.Validate(value); err != nil {
            return "", fmt.Errorf("invalid uuid format: %w", err)
        }
    }
    id, err := uuid.Parse(value)
    if err != nil {
        return "", fmt.Errorf("parse uuid: %w", err)
    }
    // String 负责产生稳定的小写、带连字符输出。
    return id.String(), nil
}

如果只是兼容外部历史数据，可以把 strict 设为 false，但落库和对外返回仍建议保存 String() 的结果。若严格要求标准 36 字符形态，则保持 strict 为 true，并把不接受的 URN、大括号或无连字符形式在入口处拒绝。

线上排查清单：错误发生在输入还是调用方式

• 先记录长度和安全的可见表示，检查是否有换行、制表符、不可见空格或全角标点；不要在日志里记录敏感业务上下文。
• 确认 JSON 解码后拿到的是字符串本身，而不是带引号的字符串、空值或错误字段。
• 确认连字符是 ASCII -，位置是 8、13、18、23；复制自文档的长横线和全角符号不能代替它。
• 请求路径使用 Parse，不要使用会 panic 的 MustParse；后者更适合包级别的固定常量。

常见问题

UUID 大写会导致 uuid.Parse 失败吗？

不会。只要结构和十六进制字符有效，字母大小写不改变 UUID 的值；输出时用 String() 统一格式。

为什么 Parse 成功了，但接口仍然提示格式不对？

接口可能要求标准 36 字符形态，而 Parse 还兼容 URN、大括号和无连字符输入。严格入口应先用 uuid.Validate，再按约定处理。

可以直接用 MustParse 处理请求参数吗？

不建议。请求参数属于外部输入，解析失败应返回可控错误；MustParse 失败会 panic，只适合启动时确定不会变化的常量。