Go strconv.ParseInt 返回错误时怎么区分原因

strconv.ParseInt 返回错误时，不要只比较 err.Error() 的字符串。更稳妥的做法是先用 errors.As 取出 *strconv.NumError，再用 errors.Is 区分底层原因：ErrSyntax 表示字符串不是合法整数，ErrRange 表示超出目标位宽，ErrBase 和 ErrBitSize 则说明调用参数本身有问题。

先分清 ParseInt 的三个输入参数

ParseInt(s, base, bitSize) 会把字符串 s 按指定进制解析成有符号整数。base 可以是 0 或 2 到 36；传入 0 时，函数会根据前缀推断二进制、八进制、十六进制或十进制。bitSize 常用 0、8、16、32 和 64，它决定结果必须能放进多大的有符号整数。

我在排查这类问题时会先把调用配置写在一起。这样看到错误时，能快速判断是外部字符串变了，还是代码传错了进制和位宽：

package main

import (
    "fmt"
    "strconv"
)

func parseID(raw string) (int64, error) {
    // 接口中的 ID 约定为十进制，并限制在 int32 范围内。
    const base = 10
    const bitSize = 32

    value, err := strconv.ParseInt(raw, base, bitSize)
    if err != nil {
        return 0, fmt.Errorf("parse id: %w", err)
    }
    return value, nil
}

这里的 bitSize=32 不代表返回类型变成了 int32，函数仍返回 int64；它表示输入值必须符合 int32 的取值范围。这个区别正是后面判断 ErrRange 的基础。

用 NumError 取得失败上下文

ParseInt 的错误具体类型是 *strconv.NumError。它包含三个很有用的字段：Func 说明哪个转换函数失败，Num 保存传入的字符串，Err 保存底层原因。错误可能被 fmt.Errorf 用 %w 包装，所以不要贸然写类型断言，而应使用 errors.As。

package main

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

func explain(raw string) {
    // 这里故意限制为 int8，便于观察范围错误的上下文。
    _, err := strconv.ParseInt(raw, 10, 8)
    if err == nil {
        fmt.Println("解析成功")
        return
    }

    var numErr *strconv.NumError
    if errors.As(err, &numErr) {
        // NumError 保存原始输入和底层原因，适合记录结构化日志。
        fmt.Printf("func=%s input=%q cause=%v\n", numErr.Func, numErr.Num, numErr.Err)
        return
    }

    // 如果未来换成了非 strconv 错误，保留通用兜底分支。
    fmt.Printf("unknown parse error: %v\n", err)
}

errors.As 解决的是“错误属于哪种结构”；它本身并不直接告诉你是语法还是越界。原因分类要继续对错误链使用 errors.Is，这样即使外层增加了上下文，判断仍然稳定。

用 errors.Is 区分四类原因

最实用的分支顺序是先处理参数配置错误，再处理输入语法和数值范围。ErrSyntax 覆盖空字符串和非法数字字符；ErrRange 表示数值无法放进目标位宽，此时返回值是对应边界值，但它仍然不能当作成功结果；ErrBase 表示 base 不在允许范围内；ErrBitSize 表示位宽小于 0 或大于 64。

package main

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

func classify(raw string, base, bitSize int) string {
    value, err := strconv.ParseInt(raw, base, bitSize)
    if err == nil {
        // 只有 err 为 nil 时，解析结果才可以作为成功值使用。
        return fmt.Sprintf("ok: %d", value)
    }

    switch {
    case errors.Is(err, strconv.ErrBase):
        // base 是代码配置，不应把这类问题伪装成用户输入错误。
        return "开发配置错误：base 必须为 0 或 2 到 36"
    case errors.Is(err, strconv.ErrBitSize):
        // bitSize 也是调用方配置，应修正字段定义或常量。
        return "开发配置错误：bitSize 必须在 0 到 64 之间"
    case errors.Is(err, strconv.ErrSyntax):
        // 输入内容无法按当前进制解释，适合返回可读的输入提示。
        return "输入错误：请输入合法整数"
    case errors.Is(err, strconv.ErrRange):
        // 越界值即使返回了边界数字，也不能继续当成合法输入。
        return "输入错误：数字超出允许范围"
    default:
        // 保留未知错误分支，避免未来新增原因时静默放行。
        return fmt.Sprintf("解析失败：%v", err)
    }
}

这里没有用 err.Error() == "invalid syntax"。错误文本是给人看的；errors.Is 对应的是标准库定义的哨兵错误，能表达“这属于哪一类失败”。

把错误分类接到接口输入处理

在 HTTP、配置文件或消息消费场景里，建议把“用户可修复”和“开发可修复”分开。语法和范围错误可以转换成字段级提示；ErrBase、ErrBitSize 说明服务端代码或配置不一致，更适合记录错误日志并让调用链返回内部错误，而不是让用户反复修改同一个合法数字。

package main

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

func parsePage(raw string) (int64, error) {
    value, err := strconv.ParseInt(raw, 10, 32)
    if err == nil {
        return value, nil
    }

    if errors.Is(err, strconv.ErrSyntax) {
        // 输入可修复：向上层返回不暴露实现细节的字段提示。
        return 0, fmt.Errorf("page must be an integer: %w", err)
    }
    if errors.Is(err, strconv.ErrRange) {
        // 输入可修复：明确告诉调用方允许的范围，而不是继续使用 value。
        return 0, fmt.Errorf("page is outside the allowed range: %w", err)
    }

    // base 和 bitSize 在本函数内是固定常量，出现此分支代表代码需要修复。
    return 0, fmt.Errorf("page parser configuration is invalid: %w", err)
}

如果需要把外部错误映射成统一的接口错误码，可以在这一层完成，但要保留原始错误链。这样日志层仍能通过 errors.Is 判断具体原因，调用层也不会依赖标准库的完整错误文本。

排查清单：先看参数，再看输入

• 确认 base 是否为 0 或 2 到 36，并确认它与输入前缀、数字字符一致。
• 确认 bitSize 与业务字段范围匹配；不要因为返回了一个最大值就忽略 ErrRange。
• 用 errors.As 读取 NumError.Num，避免日志里只留下模糊的“parse failed”。
• 用 errors.Is 做分类，不把 Error() 文本比较当作协议。
• 对外提示隐藏内部参数配置，对内日志保留 Func、原始输入和底层原因。

常见问题

ParseInt 返回的值有数字，为什么还不能使用？

发生 ErrRange 时，函数会返回目标位宽对应的边界值，方便调用方了解饱和值，但这不是一次成功解析。必须先判断 err == nil。

能直接把 err 断言成 *strconv.NumError 吗？

如果错误没有被包装，通常可以；但业务代码常会用 %w 增加上下文。使用 errors.As 更能适应错误链。

base 传 0 时，字符串里的下划线都合法吗？

不一定。只有符合 Go 整数字面量规则的位置才允许下划线；位置不合法仍会归类为 ErrSyntax。

为什么不把所有错误都返回“请输入数字”？

因为非法 base 或 bitSize 不是用户输入造成的。把它们混成输入错误会掩盖程序配置问题，导致线上反复重试却无法解决。