Go io.NewOffsetWriter 如何定位写入：偏移量、短写与错误传播边界

给一个文件或内存块预留固定区域时，调用方常常只想从“区域起点”开始写，而不想每次手算底层偏移。io.NewOffsetWriter正是这个适配层：它把相对位置加到起始偏移上，再交给底层的io.WriterAt；但短写、错误和并发安全仍由调用方负责。

io.NewOffsetWriter只负责偏移映射。普通Write从起点递进，WriteAt按“起点加相对偏移”写入；如果底层返回短写，适配层会把它转换成io.ErrShortWrite，不会静默补齐。

先把“区域起点”和“相对位置”分开

假设一个文件前1024字节存放头部，后面的区域存放索引。把底层文件交给io.NewOffsetWriter时传入1024，包装器的相对位置0就对应底层位置1024。这个关系是接口设计的核心，别把它理解成复制出一个新文件。

package main

import (
    "bytes"
    "fmt"
    "io"
)

func main() {
    base := bytes.NewReader(make([]byte, 64))
    _ = base
    var storage writerAtBuffer
    section := io.NewOffsetWriter(&storage, 16)
    n, err := section.Write([]byte("IDX"))
    fmt.Println(n, err, storage.data[16:19])
}

真实项目里底层通常是*os.File或实现了io.WriterAt的存储对象。这里的writerAtBuffer只为说明调用关系，生产代码不要把“实现了接口”误认为“自动支持并发”。

Write 和 WriteAt 的位置语义不同

Write使用包装器当前的逻辑位置，成功后当前位置向后移动；连续写入时，它适合填充一段顺序区域。WriteAt则接收相对偏移，实际写入位置是“区域起点 + 相对偏移”，并且不会因为这次调用改变包装器当前位置。

section, _ := io.NewOffsetWriter(file, 1024)

_, _ = section.Write([]byte("head"))
_, _ = section.WriteAt([]byte("tail"), 128)

// Write 写入底层 1024；WriteAt 写入底层 1152。

如果同一个包装器既被顺序写入又被随机写入，建议在代码边界上明确谁负责当前位置。否则一个调用方的Write会让另一个调用方对当前位置产生错误预期。

短写不是成功写入的另一种说法

底层WriterAt可能只报告写入了一部分字节。io.NewOffsetWriter不会猜测剩余数据，也不会循环重试；当返回数量小于输入长度且底层没有更具体的错误时，调用结果会带上io.ErrShortWrite。调用方应把它当作失败处理。

n, err := section.Write(payload)
if err != nil {
    return fmt.Errorf("write index section: %w", err)
}
if n != len(payload) {
    return io.ErrShortWrite
}

注意检查顺序：优先保留底层错误，再处理没有错误但数量不足的情况。不要只判断n == len(payload)就继续提交元数据，否则索引内容可能已经不完整。

Seek 只移动逻辑游标

包装器实现了io.Seeker时，Seek操作的是相对区域的逻辑游标。用io.SeekStart定位到0，仍然代表底层起点；定位到128，代表底层起点加128。它不会替你截断文件、填充空洞或校验区域长度。

pos, err := section.Seek(0, io.SeekStart)
if err != nil {
    return err
}
if pos != 0 {
    return fmt.Errorf("unexpected section position: %d", pos)
}

多个 goroutine 共享一个包装器时，当前位置会变成共享可变状态。随机位置写入优先使用WriteAt并让每个任务持有清晰的区间；需要共享游标时，再由上层加锁并定义锁的范围。

把接口选择落到文件分区

顺序填充一个独立区域

区域内容由一个调用方从头写到尾时，用Write配合一次io.NewOffsetWriter即可。写完后记录实际长度，避免把预留容量误当成有效数据。

并行写固定槽位

每个任务拥有固定槽位时，直接对底层io.WriterAt使用绝对偏移，或为每个任务创建自己的io.NewOffsetWriter。不要共享一个会被Seek改变位置的包装器。

验证错误和边界

测试至少覆盖：起点为0、起点大于0、WriteAt不改变当前位置、短写返回io.ErrShortWrite、负偏移返回错误。对文件实现还要验证区域末端没有越界写入。

相关问题

io.NewOffsetWriter会自动创建文件区间吗？

不会。它只是偏移适配器；文件是否存在、是否需要扩展以及区域长度如何管理，都由底层对象和业务代码决定。

WriteAt后能否用Seek读取刚才的位置？

可以，但要先确认读取对象和游标归属。WriteAt不移动包装器当前位置，后续Seek仍从原来的逻辑位置计算。

短写时应该自动重试吗？

只有当底层接口和业务允许重试时才考虑循环写入，并且要处理每次偏移、错误和取消；不能把所有io.ErrShortWrite无条件重试。

记住这条边界

把io.NewOffsetWriter当作“相对坐标到绝对坐标”的薄适配层最不容易误用：区域起点由构造函数确定，顺序游标由Write和Seek维护，随机写入由WriteAt指定。短写、越界和并发协调，则必须在更靠近业务的那一层验收。