Go strconv.NumError 怎样区分语法错误和范围溢出

我在接收配置项或接口参数时，最不愿意看到的就是把所有 strconv 转换失败都返回成“数字格式不对”。更稳妥的做法是保留错误链：用 errors.Is 判断底层是 strconv.ErrSyntax 还是 strconv.ErrRange，再在确实需要定位时用 errors.As 读取 *strconv.NumError 的 Func、Num 和 Err。

官方地址：https://pkg.go.dev/strconv#NumError

ErrSyntax 表示输入文本不符合目标数字语法，ErrRange 表示文本本身可解析但结果超出目标类型范围。不要只看返回值是不是零，也不要用错误字符串做分类。

NumError 的三个字段分别记录什么

strconv.ParseInt、ParseUint、ParseFloat 等函数失败时，会返回一个实现了 error 的 *strconv.NumError。它不是另一套错误枚举，而是把“哪个转换函数、哪段输入、什么原因”放在同一个错误对象里。

用 errors.Is 分开语法错误和范围溢出

判断原因时优先写 errors.Is(err, strconv.ErrSyntax) 和 errors.Is(err, strconv.ErrRange)。NumError 实现了 Unwrap，所以调用方即使在外层用 fmt.Errorf("...: %w", err) 增加上下文，仍然可以沿错误链匹配这两个标准原因。

package main

import (
    "errors"
    "fmt"
    "strconv"
)

func classifyInteger(raw string) string {
    // bitSize=8 表示结果必须能放进 int8 的范围，便于演示范围边界。
    _, err := strconv.ParseInt(raw, 10, 8)
    if err == nil {
        return "解析成功"
    }

    // errors.Is 按错误原因分类，不依赖错误文本的语言或格式。
    switch {
    case errors.Is(err, strconv.ErrSyntax):
        return "输入不是合法的十进制整数"
    case errors.Is(err, strconv.ErrRange):
        return "整数超出 int8 的范围"
    default:
        // 保留未知错误，避免把新原因误报成语法错误。
        return fmt.Sprintf("其它转换错误：%v", err)
    }
}

这里的两个失败输入含义不同：12x 是格式问题，200 在 int8 目标范围下则是范围问题。前者通常提示调用方修正文本，后者则可能意味着字段类型、单位或接口约定选得太窄。

需要定位时用 errors.As 读取原始输入

如果只需要决定返回哪一类提示，errors.Is 已经够用；如果还要知道失败的是哪个函数、哪一段原始文本，就把错误提取成 *strconv.NumError。相比直接写 err.(*strconv.NumError)，errors.As 对包装后的错误更稳妥。

package main

import (
    "errors"
    "fmt"
    "strconv"
)

func parsePort(raw string) error {
    // 端口示例只接受无符号 16 位整数，原文交给 strconv 保留在错误对象中。
    _, err := strconv.ParseUint(raw, 10, 16)
    if err != nil {
        // %w 保留底层 NumError，调用方仍可用 Is 和 As 继续判断。
        return fmt.Errorf("端口字段转换失败: %w", err)
    }
    return nil
}

func describePort(raw string) string {
    err := parsePort(raw)
    if err == nil {
        return "端口可用"
    }

    var numErr *strconv.NumError
    // As 提取错误对象，避免依赖外层错误是否被包装。
    if errors.As(err, &numErr) {
        if errors.Is(numErr, strconv.ErrSyntax) {
            return fmt.Sprintf("端口 %q 不是合法数字", numErr.Num)
        }
        if errors.Is(numErr, strconv.ErrRange) {
            return fmt.Sprintf("端口 %q 超出 16 位范围", numErr.Num)
        }
        return fmt.Sprintf("%s 处理 %q 失败", numErr.Func, numErr.Num)
    }
    return "端口转换失败"
}

这个封装有两个关键点：一是返回错误时使用 %w，二是不要在解析失败后把零值当成有效端口继续保存。若字段来自批量配置，还可以把 numErr.Num 与配置键名一起交给上层，形成更容易修复的提示。

把错误分类接到业务入口

标准库只负责数字语法和目标范围；“是否允许负数”“端口是否必须在 1 到 65535”“空字符串能否使用默认值”都属于业务规则。建议先完成 strconv 分类，再在更外层添加业务上下限，不要把两种责任揉进一条错误字符串。

func readRetryCount(raw string) (int, error) {
    // 业务入口把标准库的转换错误包装成调用方能理解的上下文。
    value, err := strconv.ParseInt(raw, 10, 32)
    if err != nil {
        if errors.Is(err, strconv.ErrSyntax) {
            return 0, fmt.Errorf("重试次数必须是整数: %w", err)
        }
        if errors.Is(err, strconv.ErrRange) {
            return 0, fmt.Errorf("重试次数超出 32 位范围: %w", err)
        }
        return 0, fmt.Errorf("重试次数转换失败: %w", err)
    }

    // 这是业务范围，不是 ParseInt 的 bitSize 范围；两者要分开表达。
    if value  10 {
        return 0, fmt.Errorf("重试次数必须在 0 到 10 之间")
    }
    return int(value), nil
}

如果接口需要返回结构化错误，可以把“语法错误”“类型范围错误”“业务范围错误”映射成三个内部类别，同时保留原始错误作为日志上下文。这样客户端看到的是稳定提示，排查人员仍能从错误链和 NumError 找到具体输入。

几个容易混淆的边界

• 返回值不能代替 error：语法错误常常伴随零值，零本身也可能是合法输入，必须先检查错误。
• bitSize 不是业务上下限：ParseInt 的 bitSize 约束目标整数表示能力，不能替代“重试次数不超过10”这样的业务规则。
• 错误文本不是稳定接口：不要用 strings.Contains(err.Error(), "range") 代替 errors.Is。
• 原始输入要谨慎记录：Num 可能来自用户或配置文件，写日志前仍要遵守敏感信息和长度限制。

常见问题

NumError 能直接比较 Err 吗？

更推荐用 errors.Is(err, strconv.ErrSyntax) 或 errors.Is(err, strconv.ErrRange)。这样即使错误被包装，判断仍然基于错误链。

什么时候需要 errors.As？

需要读取 Func、Num 或具体的 Err 时使用。只做原因分类时，不必为了取出结构体而增加代码。

ParseFloat 也会返回 NumError 吗？

会。官方文档说明 ParseFloat 等数值转换函数返回的具体错误可以是 *strconv.NumError，但浮点值还要结合业务判断是否允许 NaN、无穷大或业务范围之外的结果。

小结

• 用 errors.Is 区分 ErrSyntax 和 ErrRange，不要解析错误字符串。
• 用 errors.As 读取 NumError 的 Func、Num 和 Err。
• 把标准库转换边界与业务上下限分层处理，并在包装错误时保留 %w。