Go io.ReaderAt 返回短读时怎样处理有效数据

io.ReaderAt.ReadAt 返回的 n 个字节即使伴随错误，也可能是有效数据。正确处理方式是先使用 p[:n]，再根据错误判断它能不能组成完整的业务对象：当 n 时不能当成成功；固定长度数据在中途遇到文件尾通常应视为 io.ErrUnexpectedEOF，而完整读到末尾时才可以接受正常的 io.EOF 语义。

最容易写错的地方，是把 ReaderAt 当成普通 Reader。Read 可以返回当前已有的一部分数据，ReadAt 则会等待到目标长度或遇到错误；因此短读本身就是一个需要处理的边界信号。

先认清 ReaderAt 的短读契约

ReaderAt 的方法签名是 ReadAt(p []byte, off int64) (n int, err error)。它从固定偏移 off 开始，尝试填满 p。官方约定是：如果 n ，返回的 err 必须非空，说明为什么没有更多字节。

这和 io.Reader.Read 的语义不同。普通流读取允许“当前能拿到多少就返回多少”，而 ReadAt 会在数据暂时不足时继续等待，直到读满目标缓冲区或遇到错误。调用方因此要同时看两个返回值：

保留返回的有效前缀，再判断能否使用

只要 n > 0，缓冲区前面的 p[:n] 就是本次调用写入的有效部分。它是否能直接交给业务层，取决于数据协议：变长记录可能允许把这段作为尾部缓存，固定长度记录却必须等到 n == len(p) 才能解析。

func readAtPrefix(r io.ReaderAt, off int64, size int) ([]byte, error) {
    if size  0 {
        // 先复制有效前缀，调用方不必依赖未写满的尾部内容。
        prefix := append([]byte(nil), buf[:n]...)
        if err != nil {
            // 短读仍然保留数据，但把原始错误一起返回给上层判断。
            return prefix, fmt.Errorf("读取偏移 %d 的前缀失败: %w", off, err)
        }
        return prefix, nil
    }
    if err != nil {
        // 没有有效字节时，错误就是这次调用的主要结果。
        return nil, fmt.Errorf("读取偏移 %d 失败: %w", off, err)
    }
    // ReaderAt 在 n==0 时不应依赖 nil 错误代表成功。
    return nil, io.ErrNoProgress
}

这个小函数故意同时返回数据和错误。这样调用方可以决定：是把前缀留给下一次拼接，还是因为协议要求定长而立即拒绝。不要因为 n > 0 就把整个请求标记成成功，也不要读取 p[n:] 期待它包含有意义的数据。

区分 EOF 与 ErrUnexpectedEOF

io.EOF 表示没有更多输入，适合表达一个结构已经完整结束后的正常尾部。io.ErrUnexpectedEOF 则表示在固定大小的块或结构中途遇到了输入结束。两者都可能出现在定长读取的边界上，但业务含义完全不同。

func readFixedRecord(r io.ReaderAt, off int64, recordSize int) ([]byte, error) {
    if recordSize  0 {
        // 先保留前缀，便于日志或上层决定是否缓存残片。
        prefix := append([]byte(nil), buf[:n]...)
        if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) {
            return prefix, io.ErrUnexpectedEOF
        }
        if err != nil {
            return prefix, fmt.Errorf("定长记录只读到 %d/%d 字节: %w", n, len(buf), err)
        }
        return prefix, io.ErrUnexpectedEOF
    }

    if errors.Is(err, io.EOF) {
        // 起始位置已经没有字节，表示没有下一条记录，而不是坏记录。
        return nil, io.EOF
    }
    if err != nil {
        return nil, fmt.Errorf("读取定长记录失败: %w", err)
    }
    return nil, io.ErrUnexpectedEOF
}

这里有一个很实用的区分：在记录起点读到 n == 0, err == io.EOF，可以解释为“没有下一条记录”；读到了一部分后再遇到 EOF，则说明当前记录被截断，应返回 io.ErrUnexpectedEOF。如果协议允许最后一条记录变长，可以改成返回前缀，但不能把它当作一个已经完整的定长记录。

固定长度读取函数应该把错误边界集中起来

实际项目里，多个调用点都直接写 ReadAt 很容易出现不同的错误判断：一个调用点忘了检查 n，另一个调用点把所有 EOF 都当成正常结束。把定长语义封装在一个函数里，调用方只需要处理“完整记录、没有下一条、记录损坏、底层失败”几种结果。

func loadHeader(r io.ReaderAt, off int64) ([]byte, error) {
    const headerSize = 16

    header, err := readFixedRecord(r, off, headerSize)
    if err != nil {
        // 只有完整头部才进入解析器，短读残片不能伪装成合法头部。
        return nil, err
    }
    // 解析器接收的切片长度已由 readFixedRecord 保证。
    return header, nil
}

如果底层是文件或其他支持并发偏移读取的对象，多个 ReadAt 调用可以使用不同的偏移并行进行；它不会像共享游标式的 Read 那样改变或依赖一个共同的当前位置。并发安全仍要以具体实现的文档为准，不能把所有包装器都默认成可并发。

五个边界检查点

• 先看 n，再看 err。只要 n > 0，先处理或保存 p[:n]，不要直接丢弃。
• 短读不是成功。固定长度对象只有 n == len(p) 才能进入解析流程。
• 区分两种 EOF。起点的 io.EOF 可以表示没有下一条；中途结束应转成 io.ErrUnexpectedEOF。
• 不要使用脏尾部。缓冲区未写入的 p[n:] 不属于本次读取结果。
• 保留偏移语义。off 是本次读取的绝对起点，不能用共享游标的直觉替代它。

可以用下面的速查表决定处理方式：

相关问题

ReadAt 返回 n 大于 0、err 不为空时，数据能用吗？

可以先使用 p[:n]，但能否作为完整业务对象要看协议。对固定长度结构来说，它只是有效前缀，不是完整记录。

为什么 ReadAt 短读时不能等下一次补齐？

可以由调用方重新分配缓冲区并再次读取剩余偏移，但这已经是新的读取策略。一次 ReadAt 调用返回短读时，调用方必须先处理本次非空错误。

读到完整长度时为什么 err 还可能是 EOF？

当这次读取正好覆盖输入末尾，返回 n == len(p) 与 io.EOF 并不矛盾；完整性由字节数确认，EOF 表示后面没有更多输入。