Go io.NewOffsetWriter 怎样把写入限制在文件区间内

如果你要把一段数据写到文件的固定起点，io.NewOffsetWriter 可以把逻辑偏移映射到 io.WriterAt 的绝对偏移。要注意：它只负责“从哪里开始写”，没有区间长度参数，也不会自动阻止数据越过预留区域；长度门禁仍要由调用方完成。

官方文档：https://pkg.go.dev/io#NewOffsetWriter

最小用法是先用 os.File 提供 io.WriterAt，再用 io.NewOffsetWriter(file, base) 建立偏移适配层。连续 Write 会推进当前位置，WriteAt 使用相对偏移但不推进当前位置；真正的区间长度要在写入前自行检查。

触发场景：为什么要加一层 OffsetWriter

文件头、索引区和数据区经常共享同一个文件，但每个模块只应该看到自己的逻辑起点。直接调用 file.WriteAt(data, absolute) 会让每个调用方都维护绝对偏移，容易把“区间内偏移”和“文件偏移”混在一起。

NewOffsetWriter(w, off) 接收一个 io.WriterAt 和起始偏移 off。在 Go 官方实现中，起始位置和当前写入位置都从这个偏移开始，因此逻辑位置 0 对应底层文件的 base。

权限配置：先确认 WriterAt 和文件起点

偏移写入的第一道门禁是接口：目标对象必须实现 WriteAt。*os.File 可以直接作为底层写入对象；如果是自定义存储，则要保证它对偏移和并发语义有清楚约定。

package main

import (
    "fmt"
    "io"
    "os"
)

func main() {
    // 文件以读写方式打开；示例把数据区起点设为 4096 字节。
    f, err := os.OpenFile("data.bin", os.O_RDWR|os.O_CREATE, 0o644)
    if err != nil {
        panic(err)
    }
    defer f.Close() // 及时释放文件描述符。

    var target io.WriterAt = f
    writer := io.NewOffsetWriter(target, 4096)

    // 逻辑偏移 0 实际写到文件绝对偏移 4096。
    n, err := writer.Write([]byte("header-data"))
    if err != nil {
        panic(err)
    }
    fmt.Println("written:", n)
}

这里的 writer 只暴露逻辑位置，调用方不必在每次写入时重复加 4096。Write 成功写入后，下一次连续写入会接在前一次之后。

流水线阶段：Write、WriteAt 和 Seek 怎样配合

把三个方法分开看，偏移关系就不会混乱：

• Write(p) 写入当前逻辑位置，并在成功写入 n 个字节后推进当前位置。
• WriteAt(p, off) 把 off 当作相对于起点的逻辑偏移，实际位置是 base + off，不会改变连续 Write 的当前位置。
• Seek(offset, whence) 只接受 io.SeekStart 和 io.SeekCurrent；使用 io.SeekEnd 会返回无效 whence 错误，因为 OffsetWriter 不知道区间末端。

// writer 已经从 base 偏移创建。
// WriteAt 的 128 是逻辑偏移，底层位置是 base + 128。
n, err := writer.WriteAt([]byte("index"), 128)
if err != nil {
    return err
}

// 把下一次连续 Write 定位到逻辑偏移 64。
if _, err := writer.Seek(64, io.SeekStart); err != nil {
    return err
}
_, err = writer.Write([]byte("payload"))
return err

对负的逻辑偏移，WriteAt 和 Seek 都会报错。即使底层文件支持更大的偏移，也不要把负数当成“从文件尾部倒推”的写法；这个类型没有提供这种语义。

门禁规则：OffsetWriter 不会替你限制区间长度

这是最容易误解的地方。NewOffsetWriter 只有起点参数，没有长度参数，所以“固定区间”只是业务约定。若数据区从 4096 开始、长度为 1024，那么写入前应先判断待写字节数是否超过剩余空间。

func writeRegion(w io.Writer, data []byte, base, size int64) (int, error) {
    // 先校验区间参数，避免负偏移和整数边界带来误写。
    if base  size {
        return 0, fmt.Errorf("data does not fit in region")
    }

    // OffsetWriter 负责起点映射，长度门禁已经在上面完成。
    writer := io.NewOffsetWriter(w.(io.WriterAt), base)
    n, err := writer.Write(data)
    if err != nil {
        return n, err
    }
    if n != len(data) {
        return n, io.ErrShortWrite
    }
    return n, nil
}

生产代码中不建议依赖没有必要的类型断言，可以把函数参数直接声明成 io.WriterAt。这个示例保留了门禁重点：先比较数据长度，再写入，并检查 n 与 err。

失败处理：从 n 和 err 判断结果

写入接口的判断顺序是先处理 n，再处理 err。n == len(data) 且 err == nil 才表示这次调用完整成功；n 时应保留已写入数量，并把非空错误继续交给上层。底层对象返回短写却没有错误时，可以补成 io.ErrShortWrite。

速查结论：需要把一套逻辑坐标映射到文件起点时使用 NewOffsetWriter；需要真正封顶时额外保存区间长度并在每次写入前比较；需要随机写入时用 WriteAt，需要连续追加时用 Write。它不是带长度的切片写入器，也不会替你完成并发协调。

常见问题

io.NewOffsetWriter 能不能直接接 bytes.Buffer？

不能把普通 io.Writer 当成 io.WriterAt 使用。需要先选用实现 WriteAt 的对象，或自行提供明确的偏移写入实现。

WriteAt 会不会改变下一次 Write 的位置？

不会。WriteAt 使用相对起点计算底层偏移，连续写入位置由 Write 和 Seek 维护。