Go strconv.ParseInt 升级后行为变化怎么定位

Go 升级后如果发现 strconv.ParseInt 的结果“变了”，先不要把锅直接甩给新版本。这个函数的结果由输入字符串、base、bitSize 和错误处理共同决定；其中任何一个条件没有保持一致，都会让相同的业务字段呈现出不同的结果。最稳妥的定位方式，是把升级前后的调用还原成一份可比较的解析契约。

官方资料：https://pkg.go.dev/strconv#ParseInt

本文只讨论有符号整数解析。目标不是证明某个版本“绝对没有变化”，而是给出一条能把版本差异、输入差异和调用方误判分开的排查路径。

先对齐四个条件，再谈升级差异

我在排查这类问题时，第一步会把调用现场压缩成四列：原始字符串、base、bitSize、错误值。只看最终的 int64 不够，因为 ParseInt 返回的整数和 error 是一个整体。

例如下面两次调用看起来只是换了参数，实际已经改变了解析规则：

先排查 base=0：升级后最容易被忽略的前缀语义

base 传 0 时，ParseInt 会根据字符串前缀推断进制：0b 表示二进制，0o 或前导 0 表示八进制，0x 表示十六进制，没有这些前缀时按十进制处理。这个模式适合解析 Go 整数字面量风格的输入，却不一定适合业务配置。

如果升级前后配置文件的生成器、清洗逻辑或测试夹具发生过变化，原本的 010、0x10 可能不再代表你以为的十进制数字。定位时把原始字符串完整记录下来，不要只记录转换后的值。

package main

import (
    "fmt"
    "strconv"
)

func main() {
    inputs := []string{"010", "0x10", "10"}
    for _, raw := range inputs {
        // base=0 用于兼容带前缀的整数字面量，不能当作固定十进制解析。
        inferred, err := strconv.ParseInt(raw, 0, 64)
        if err != nil {
            fmt.Printf("raw=%q base=0 err=%v\n", raw, err)
            continue
        }
        // 业务字段若约定为十进制，应显式传 10，避免前缀改变含义。
        decimal, decimalErr := strconv.ParseInt(raw, 10, 64)
        fmt.Printf("raw=%q inferred=%d decimal=%d decimalErr=%v\n", raw, inferred, decimal, decimalErr)
    }
}

这里的对照重点不是哪一个结果“更正确”，而是业务协议到底允许前缀推断。如果字段文档写的是十进制端口、数量或 ID，通常应显式传 10；如果输入就是 Go 风格字面量，再保留 0 并在文档里写清楚。

固定 bitSize：不要让 int 的范围成为隐形变量

bitSize 决定字符串对应的值必须落在哪个有符号整数范围内。官方文档将 0、8、16、32、64 分别对应 int、int8、int16、int32、int64 的目标范围。虽然返回值的静态类型是 int64，但校验范围并不因此总是 64 位。

因此，升级后出现“某台机器能解析、另一台机器报范围错误”时，要检查调用是否使用了 bitSize=0，以及后续是否把结果转成了 int。对于跨机器配置、网络协议和数据库字段，直接固定为协议约定的位宽更容易复现。

package main

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

func parseCount(raw string) (int64, error) {
    // 数量字段的协议范围固定为 32 位，避免跟随本机 int 宽度变化。
    value, err := strconv.ParseInt(raw, 10, 32)
    if err != nil {
        // 保留原始错误，让上层可以区分语法错误与范围错误。
        return 0, fmt.Errorf("parse count %q: %w", raw, err)
    }
    // 显式检查包装后的错误，避免把越界值当成有效数量。
    if errors.Is(err, strconv.ErrRange) {
        return 0, fmt.Errorf("count out of range: %w", err)
    }
    return value, nil
}

示例中的 errors.Is 分支展示的是错误分类思路；实际工程中也可以在一次错误处理路径里先判断 ErrSyntax，再判断 ErrRange。关键是不要只看返回的数字，因为范围错误时函数仍可能返回目标位宽边界上的值。

保留 NumError：把“行为变化”拆成三类

ParseInt 返回的具体错误类型是 *strconv.NumError，其中包含函数名、原始输入和底层原因。升级排查时保留这个错误对象，比把它格式化成一段字符串后丢掉更有用。

• ErrSyntax：输入为空、包含不属于当前进制的字符，或整体不符合解析语法。
• ErrRange：语法成立，但值超出了指定 bitSize 的有符号范围。
• 参数错误：base 或 bitSize 本身不在允许范围内，应该回到调用配置排查。

package main

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

func describe(raw string, base, bitSize int) {
    value, err := strconv.ParseInt(raw, base, bitSize)
    if err == nil {
        fmt.Printf("raw=%q base=%d bitSize=%d value=%d\n", raw, base, bitSize, value)
        return
    }

    var numErr *strconv.NumError
    // NumError 保存原始输入；用 errors.As 兼容被包装过的错误。
    if errors.As(err, &numErr) {
        switch {
        case errors.Is(numErr, strconv.ErrSyntax):
            fmt.Printf("syntax: raw=%q func=%s\n", numErr.Num, numErr.Func)
        case errors.Is(numErr, strconv.ErrRange):
            fmt.Printf("range: raw=%q func=%s\n", numErr.Num, numErr.Func)
        default:
            fmt.Printf("conversion: raw=%q func=%s err=%v\n", numErr.Num, numErr.Func, numErr.Err)
        }
        return
    }

    // 非 NumError 通常提示参数组合或调用边界需要单独检查。
    fmt.Printf("parameter or unknown error: raw=%q err=%v\n", raw, err)
}

这样记录以后，升级前后的日志可以按 raw、base、bitSize 和错误类别逐项比较。若四项一致却仍然出现差异，才值得进一步检查 Go 版本、依赖替换、编译标签或上层转换逻辑。

用一份稳定入口收敛配置、测试和日志

真正容易复发的问题，往往不是某次升级，而是项目里有多个地方各自调用 ParseInt：配置读取传 0，命令行解析传 10，测试却没有覆盖带前缀或超范围的输入。可以把协议规则收拢到一个小函数，让调用方只处理业务语义。

package config

import (
    "fmt"
    "strconv"
)

// ParseDecimal32 统一解析协议中的十进制 32 位有符号整数。
func ParseDecimal32(field, raw string) (int32, error) {
    // 显式 base=10 和 bitSize=32，避免环境与调用点改变规则。
    value, err := strconv.ParseInt(raw, 10, 32)
    if err != nil {
        // 错误中保留字段名和原始值，便于升级前后比对输入契约。
        return 0, fmt.Errorf("field %s value %q: %w", field, raw, err)
    }
    return int32(value), nil
}

测试用例至少覆盖普通十进制、带前导零、十六进制前缀、非法字符、空字符串和超出 32 位范围的值。测试不需要绑定某台机器的 int 宽度，也不要只断言错误字符串；优先断言 errors.Is(err, strconv.ErrSyntax) 或 errors.Is(err, strconv.ErrRange)。

升级后定位清单：先证明条件相同

1. 记录升级前后的 Go 版本、实际调用代码和依赖锁定状态。
2. 记录未经清洗的原始字符串，特别关注前导零、0x、0o、0b 和下划线。
3. 把 base 与 bitSize 写进日志或诊断字段，不要只打印结果。
4. 检查调用方是否忽略了 error，以及是否继续使用了范围错误时返回的边界值。
5. 比较 NumError.Num、NumError.Func 与 NumError.Err，再判断是否需要深入版本实现。

如果是输入协议明确规定十进制，最终代码通常应当是 ParseInt(raw, 10, 32) 或 ParseInt(raw, 10, 64)，而不是让 base=0 替你猜。只有在确实要接受 Go 整数字面量时，才把前缀推断写进接口说明和测试。

常见追问

ParseInt 返回错误时，返回值还能使用吗？

不要把带错误的返回值当成成功结果。语法错误时返回值为零；范围错误时可能返回指定位宽的边界值，应该先处理错误再决定业务行为。

为什么同一个字符串传 base=0 和 base=10 结果不同？

因为 base=0 会根据前缀推断进制，而 base=10 强制按十进制解释。差异来自调用契约，不应简单归因于 Go 升级。

应该用 bitSize=0 还是 64？

如果字段协议要求跟随 int，可以使用 0；如果字段需要跨机器、跨进程稳定，通常应明确写出协议位宽，例如 32 或 64。