整数转换错误

我在处理命令行参数和 HTTP 查询参数时，最容易低估的一类问题就是“整数转换错误”：调用 strconv.Atoi 失败后，日志里只有一条很长的错误字符串，业务代码却不知道应该提示用户重新输入，还是提醒数值已经超出范围。真正稳妥的处理方式不是把所有错误都当成“不是数字”，而是区分 strconv.ErrSyntax 和 strconv.ErrRange。

这篇只解决一个边界：Atoi 失败时，怎样判断输入为空或格式非法，怎样判断整数超出当前平台 int 的范围，并怎样保留原始输入帮助排障。

Atoi 失败不是一种错误

Atoi 的名字容易让人以为它只是一个简单的字符串转换函数，但它的错误信息已经把失败原因分层了。Go 官方文档说明，Atoi 等价于 ParseInt(s, 10, 0) 后转换成 int；这里的 bitSize=0 表示使用当前平台的 int 大小。

因此，""、"12x" 和一个过大的纯数字字符串，虽然最后都返回了非 nil 的 error，但它们不是同一件事：

这里有一个很实际的习惯：只要 err != nil，就不要因为返回值看起来像一个整数而继续使用它。文档虽然定义了某些失败时的返回值，但业务上更重要的是先处理错误，再决定是否接受输入。

用 errors.Is 区分空串、非法格式和溢出

转换错误可能经过包装，所以不要依赖完整错误字符串做判断。errors.Is 会沿着错误链寻找目标错误，适合判断“属于哪一类”。下面这个小函数只做分类，不把用户输入直接写进返回给用户的提示。

package main

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

func parseID(raw string) (int, error) {
    value, err := strconv.Atoi(raw)
    if err == nil {
        return value, nil
    }

    // 先判断底层原因，再决定给调用方什么提示。
    switch {
    case errors.Is(err, strconv.ErrSyntax):
        return 0, fmt.Errorf("id 格式不正确: %w", err)
    case errors.Is(err, strconv.ErrRange):
        return 0, fmt.Errorf("id 超出 int 范围: %w", err)
    default:
        // 保留未知错误，避免把未来的错误原因误判成格式问题。
        return 0, fmt.Errorf("id 转换失败: %w", err)
    }
}

这个判断的重点是顺序：先检查 err == nil，再检查错误类别。若输入是空串或混入字母，通常会进入 ErrSyntax 分支；若输入是合法数字但太大，则进入 ErrRange 分支。对外提示可以更友好，但内部错误链最好保留。

为什么还要用 errors.As 读取 NumError

只知道 ErrSyntax 或 ErrRange，有时还不够。Go 的 strconv 会返回 *strconv.NumError，其中包含失败函数 Func、原始输入 Num 和底层原因 Err。这对统一日志、接口错误码和排查脏数据很有用。

package main

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

func describeInteger(raw string) string {
    value, err := strconv.Atoi(raw)
    if err == nil {
        return fmt.Sprintf("转换成功: %d", value)
    }

    var numErr *strconv.NumError
    if errors.As(err, &numErr) {
        // Num 保留原始字符串，日志可据此定位是哪条输入失败。
        return fmt.Sprintf("函数=%s 输入=%q 原因=%v", numErr.Func, numErr.Num, numErr.Err)
    }

    // 对不符合预期的错误类型保留兜底信息。
    return fmt.Sprintf("未知转换错误: %v", err)
}

errors.As 解决的是“错误对象里有什么上下文”，errors.Is 解决的是“它属于哪一种已知原因”。两者可以一起使用：先用 Is 给业务分类，再用 As 获取输入值和函数名用于日志。

平台 int 位宽是溢出判断的一部分

Atoi 不是固定按 64 位整数解析。它的目标类型是 int，所以同一字符串在不同平台的可接受范围可能不同。需要明确 32 位或 64 位协议字段时，使用 ParseInt 并显式指定 bitSize 更清楚；需要和本机索引、切片长度等 int 对接时，Atoi 才是自然选择。

package main

import (
    "fmt"
    "strconv"
)

func parseProtocolCount(raw string) (int64, error) {
    // 协议字段固定为 64 位，不跟随运行平台的 int 改变。
    value, err := strconv.ParseInt(raw, 10, 64)
    if err != nil {
        return 0, fmt.Errorf("协议数量无效: %w", err)
    }
    return value, nil
}

这不是说 ParseInt 一定比 Atoi 好，而是要让目标范围和数据契约一致。把数据库里的大编号、协议字段或外部 JSON 数字盲目转成 int，再依赖平台默认范围，往往会把部署环境差异带进业务。

一份可直接放进输入层的判断清单

我会把转换动作放在输入边界，成功后才把整数交给后续逻辑。可以按下面的顺序检查：

1. 确认空白是否有业务意义；如果不允许，先决定是拒绝还是在输入层统一清理。
2. 调用 Atoi 后先判断 err，不要只检查返回的整数是否为零。
3. 用 errors.Is(err, strconv.ErrSyntax) 区分格式问题。
4. 用 errors.Is(err, strconv.ErrRange) 区分超出目标类型范围。
5. 需要审计时用 errors.As 取出 NumError.Num，但记录日志前要考虑敏感输入脱敏。
6. 如果字段属于固定协议宽度，改用显式 ParseInt，不要让平台 int 替你做契约决定。

常见问题

空字符串一定会返回 ErrSyntax 吗？

在 strconv 的整数解析语义中，空字符串没有有效数字，属于语法错误。业务层仍应决定它是“必填项缺失”还是“格式错误”，不要把库错误名称原样当成用户提示。

判断溢出时能不能只比较返回值？

不建议。返回值可能是失败时的边界值或零值，单独看它无法说明转换是否成功。以 err 为准，再用 ErrRange 判断范围问题。

为什么不用 strings.TrimSpace 后再 Atoi？

是否允许首尾空白是输入契约，不是 Atoi 自动替你决定的规则。若接口约定允许空白，可以在边界层显式清理，并在代码注释或文档中写清楚；若不允许，就保留原始输入并返回格式错误。

NumError.Num 可以直接写进日志吗？

它适合帮助定位失败输入，但如果字段可能包含账号、令牌或个人数据，应先脱敏或只记录长度、来源字段和错误类别。错误诊断信息也要遵守数据最小化原则。

整数转换失败时，最有价值的不是把报错字符串拼得更长，而是把错误分类、目标位宽和输入上下文分开处理：errors.Is 负责判断原因，errors.As 负责读取结构化上下文，调用方再根据这两层信息做出明确决定。