Go strings.Reader.Seek 为什么会返回 ErrInvalidWhence

先说结论：strings.Reader.Seek 返回 ErrInvalidWhence，通常是因为第二个参数没有使用 io.SeekStart、io.SeekCurrent 或 io.SeekEnd。这三个常量分别表示从字符串开头、当前位置和末尾计算偏移；它们不是可以随便替换的普通整数。

官方文档：https://pkg.go.dev/strings#Reader.Seek

还要把两类容易混淆的情况分开：合法 whence 但最终位置小于 0，属于负位置错误；而合法 whence 算出的新位置超过字符串末尾，Seek 本身可以接受，后续读取才会表现为没有更多数据。

先把 Reader 的位置理解成字节偏移

strings.Reader 通过读取一个字符串实现了 io.Reader、io.ReaderAt 和 io.Seeker 等接口。它内部的游标表示“下一个要读取的字节”，所以 Seek 返回的是字节偏移，不是 Unicode 字符个数。

这点对中文字符串尤其重要。例如一个汉字在 UTF-8 中通常占用多个字节，不能把“第 2 个字符”直接当成 offset 2。需要按字节定位时，应先明确输入是 UTF-8 字节序列，还是已经按字符切分后的数据。

三个合法 whence 分别表示什么

Go 把定位起点定义在 io 包中，建议始终使用常量而不是手写数字。选择不同起点后，offset 的含义会改变，但返回值始终是新的绝对字节位置。

例如，Seek(3, io.SeekStart) 表示绝对位置 3；Seek(-2, io.SeekCurrent) 表示从当前游标回退 2 个字节；Seek(-1, io.SeekEnd) 表示移动到最后一个字节的位置。

用一个小例子观察返回位置

下面的例子把定位动作放在一个函数里，每次都打印返回的位置和错误。代码注释说明了 offset 的单位以及为什么不能把 whence 当作业务编号传入。

package main

import (
    "fmt"
    "io"
    "strings"
)

func main() {
    reader := strings.NewReader("golang-reader")

    // 从字符串开头定位到第 6 个字节，返回值是新的绝对字节偏移。
    position, err := reader.Seek(6, io.SeekStart)
    fmt.Printf("start: position=%d err=%v\n", position, err)

    // 当前位置再向后移动 2 个字节，offset 仍然按字节计算。
    position, err = reader.Seek(2, io.SeekCurrent)
    fmt.Printf("current: position=%d err=%v\n", position, err)

    // 从末尾向前移动 3 个字节，适合定位尾部字段。
    position, err = reader.Seek(-3, io.SeekEnd)
    fmt.Printf("end: position=%d err=%v\n", position, err)
}

检查这个例子时，重点不是把返回值当成“移动了多少”，而是把它当成下一次读取会使用的绝对位置。每次调用后都应同时看 position 和 err，不要只判断位置是否非零。

为什么会得到 ErrInvalidWhence

实现只认识三个合法的定位起点。如果把自定义枚举、HTTP 参数或数组下标直接传给 Seek，即使数值看起来有意义，也不会被当成新的模式处理。例如下面的调用传入了 3，问题在于 whence 不在合法集合中，而不是 offset 的正负。

package main

import (
    "fmt"
    "strings"
)

func main() {
    reader := strings.NewReader("abcdef")

    // 3 不是 io.SeekStart、io.SeekCurrent 或 io.SeekEnd，不能当作自定义起点。
    position, err := reader.Seek(1, 3)
    fmt.Printf("position=%d err=%v\n", position, err)
}

修复方式不是换一个看起来接近的数字，而是把业务层的选择明确映射到 io 常量：

func seekFrom(reader *strings.Reader, offset int64, from string) (int64, error) {
    var whence int
    switch from {
    case "start":
        whence = io.SeekStart
    case "current":
        whence = io.SeekCurrent
    case "end":
        whence = io.SeekEnd
    default:
        // 未知的业务值在进入 Reader 前就拒绝，避免产生 ErrInvalidWhence。
        return 0, fmt.Errorf("unknown seek origin %q", from)
    }

    // 只有经过映射的 whence 才交给标准库执行定位。
    return reader.Seek(offset, whence)
}

ErrInvalidWhence 和负位置不是一回事

第二个边界是合法 whence 与 offset 组合后得到负位置。例如 Reader 当前在开头时执行 Seek(-1, io.SeekCurrent)，起点是合法的，但结果位置是 -1，因此错误原因与非法 whence 不同。

package main

import (
    "fmt"
    "io"
    "strings"
)

func main() {
    reader := strings.NewReader("abcdef")

    // 合法 whence 也不能把最终位置推到 0 以下。
    position, err := reader.Seek(-1, io.SeekStart)
    fmt.Printf("position=%d err=%v\n", position, err)
}

排查时可以按这个顺序判断：先看 whence 是否来自三个标准常量，再根据起点计算新位置是否小于 0，最后才判断位置是否超过字符串长度。这样能避免把所有错误都归结为“offset 写错”。

超过末尾时为什么不一定报错

Seek 负责移动位置，并不负责保证位置落在字符串已有内容之内。使用合法 whence 计算出一个大于字符串长度的位置时，定位可以成功；但后续 Read 没有可读字节，会返回 EOF。

package main

import (
    "fmt"
    "io"
    "strings"
)

func main() {
    reader := strings.NewReader("abc")

    // 位置 10 超过字符串长度，但仍然是一个非负的绝对偏移。
    position, seekErr := reader.Seek(10, io.SeekStart)
    var buf [1]byte
    readCount, readErr := reader.Read(buf[:])
    fmt.Printf("position=%d seekErr=%v readCount=%d readErr=%v\n", position, seekErr, readCount, readErr)
}

因此，若业务要求“必须定位到现有内容中”，需要在成功 Seek 后自行比较返回位置与 reader.Size()，或者读取后根据 io.EOF 做边界处理。不要把“Seek 没报错”理解为“那里一定有数据”。

把定位规则收敛成一个安全入口

在解析配置或协议字段时，建议让调用方只提交明确的起点和偏移，然后在一个入口中集中做校验。下面的写法同时覆盖非法起点、负偏移结果和超过末尾三种情况，调用方可以根据业务需要决定是否把超过末尾视为错误。

func seekChecked(reader *strings.Reader, offset int64, whence int) (int64, error) {
    // 先限制起点集合，让错误尽早暴露在业务边界。
    if whence != io.SeekStart && whence != io.SeekCurrent && whence != io.SeekEnd {
        return 0, fmt.Errorf("invalid whence: %d", whence)
    }

    position, err := reader.Seek(offset, whence)
    if err != nil {
        // 标准库负责返回具体定位错误，这里保留原错误供上层判断。
        return position, err
    }

    // 这里只把超过末尾作为业务提示，不改变 Reader 的 Seek 语义。
    if position > reader.Size() {
        return position, fmt.Errorf("position %d is beyond size %d", position, reader.Size())
    }
    return position, nil
}

要注意：这段封装把“超过末尾”升级成了业务错误，但标准库本身并没有把它当成 Seek 错误。若调用方需要支持稀疏式定位或先定位后追加逻辑，就可以移除这条业务限制。

常见误区速查

最后记住这三个判断

第一，whence 只负责选择起点，优先使用 io.SeekStart、io.SeekCurrent 和 io.SeekEnd。第二，offset 是相对所选起点的字节偏移，返回值才是新的绝对位置。第三，非法 whence、负位置和超过末尾是三个不同层次的问题，排查时不要混成一个错误。

如果你只需要在一段字符串中重复读取固定区间，也可以把“Seek 后的返回位置”记录下来，并在每次读取前检查目标区间是否落在 Size() 范围内。这样既保留了 Reader 的标准行为，也能让上层业务得到明确的边界提示。

相关问题

strings.Reader.Seek 的返回值是字符下标吗？不是，它是字节偏移；UTF-8 文本不能直接把字符序号当成 offset。

Seek 到字符串末尾之后一定返回错误吗？不一定。只要 whence 合法且结果位置非负，Seek 可以返回该位置；后续读取通常没有可读内容。

io.SeekCurrent 的 offset 可以是负数吗？可以，但计算出的最终位置不能小于 0，否则会返回负位置错误。