Go io.NewOffsetWriter 怎样在 Writer 中定位写入偏移

我在做“只改文件中间一小段”的逻辑时，最先踩到的坑不是 WriteAt 不会用，而是把“业务区间的相对位置”和“文件的绝对偏移”混在了一起。结果是补丁内容写进了文件，却落在了错误的区间。

Go 的 io.NewOffsetWriter 适合解决这个问题：给它一个实现了 io.WriterAt 的基础对象和起始偏移，它就提供一个新的写入视图。这个视图里的位置从业务区间开始计算，真正落盘时再自动加上基础偏移。

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

把 io.NewOffsetWriter(w, base) 当成“从文件第 base 字节开始的局部 Writer”。Write 会推进这个局部位置，WriteAt 使用局部偏移但不推进当前位置，Seek 只支持它定义的相对位置语义。

先还原固定区间写错位置的故障现场

假设一个文件前 128 字节是固定头部，业务要从第 128 字节开始写入一段索引。直接把基础文件传给一个只知道 io.Writer 的函数，函数只能从当前写入位置开始工作；如果换成 os.File.WriteAt，又要把绝对偏移一路传进业务层。

这两种写法都能工作，但边界容易泄漏：业务代码本来只关心“区间内的第 0、1、2 个字节”，却不得不记住文件的第 128、129、130 个字节。OffsetWriter 的价值就在于把这层换算集中到一个对象里。

NewOffsetWriter 到底改变了什么

官方接口签名是 io.NewOffsetWriter(w io.WriterAt, off int64) *io.OffsetWriter。创建时，off 同时成为基础偏移和当前偏移。源码里的核心关系可以概括为：顺序 Write 写到底层的当前偏移；相对 WriteAt 写到底层的基础偏移加上调用参数。

因此可以把它记成三个量：

用 Write 完成带起点的连续写入

下面的例子把文件的第 128 字节当成一个独立区域。连续调用 Write 时，业务层不再手算 128、136、144 这样的绝对位置；每次成功写入多少字节，局部当前位置就向后移动多少。

package main

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

func writeIndex(path string, blocks [][]byte) error {
	// 这里只打开已有文件；固定区间写入不负责创建或截断文件。
	f, err := os.OpenFile(path, os.O_WRONLY, 0)
	if err != nil {
		return fmt.Errorf("打开索引文件失败: %w", err)
	}
	defer func() {
		// 关闭错误不能覆盖前面的写入错误，所以这里只做收尾处理。
		_ = f.Close()
	}()

	// 业务区间从文件绝对偏移 128 开始，后续 Write 使用局部位置。
	region := io.NewOffsetWriter(f, 128)
	for i, block := range blocks {
		if _, err := region.Write(block); err != nil {
			// 错误中带上块编号，便于定位是哪一次连续写入失败。
			return fmt.Errorf("写入第 %d 个索引块失败: %w", i, err)
		}
	}
	return nil
}

这段代码的关键是 f 必须实现 io.WriterAt，而不是只满足普通 io.Writer。如果基础对象不支持按绝对偏移写入，NewOffsetWriter 就没有可用的落点。

WriteAt 与 Seek 的位置语义不能混用

OffsetWriter 同时提供三个看似相近的方法，但它们对当前位置的影响不同：

• Write(p) 写入当前局部位置，并按成功写入的字节数推进当前位置。
• WriteAt(p, off) 写入局部偏移 off，底层位置是 base+off，不会修改顺序写入的当前位置。
• Seek(offset, io.SeekStart) 或 Seek(offset, io.SeekCurrent) 调整局部当前位置；位置不能退到基础偏移之前。

func patchRegion(f *os.File) error {
	// 128 是业务区间起点，OffsetWriter 内部会把它保存为基础偏移。
	region := io.NewOffsetWriter(f, 128)

	// WriteAt 的 16 是区间内偏移，实际写入位置是 128 + 16。
	if _, err := region.WriteAt([]byte("index"), 16); err != nil {
		return fmt.Errorf("写入局部偏移失败: %w", err)
	}

	// WriteAt 不推进顺序当前位置；这里先把当前位置移到局部第 32 字节。
	if _, err := region.Seek(32, io.SeekStart); err != nil {
		return fmt.Errorf("调整局部位置失败: %w", err)
	}

	// Write 从局部第 32 字节开始写，成功后当前位置继续向后移动。
	if _, err := region.Write([]byte("tail")); err != nil {
		return fmt.Errorf("顺序写入尾部失败: %w", err)
	}
	return nil
}

还有一个容易忽略的边界：当前 Go 的 OffsetWriter.Seek 实现处理 SeekStart 和 SeekCurrent，并不把 SeekEnd 当作有效分支。需要从末尾定位时，应该先明确区间长度并自行换算，不能假设所有 io.Seeker 都完整支持三种 whence。

负偏移、短写与并发场景怎么收口

调用 WriteAt 时传入负的局部偏移会直接返回错误，不会把写入位置“绕回”基础偏移之前。Seek 计算出的新位置如果低于基础偏移，也会返回错误。业务层应该保留这些错误，不要用忽略错误的方式继续写下一个区块。

写入接口遵循 Go 的 Writer 约定：如果返回的字节数小于输入长度，通常必须同时有非空错误。固定区间更新最好检查 n 与 len(p) 是否一致；如果底层 WriterAt 返回短写，文章中的“成功更新”就不能成立。

最后要注意并发：WriterAt 文档允许在写入范围不重叠时并发调用，但 OffsetWriter 自己维护了一个会被 Write 和 Seek 修改的当前位置。多个 goroutine 共享同一个 OffsetWriter 做顺序写入时，不应把它当成自动加锁的对象；要么按区间使用独立实例，要么在更外层明确同步。

常见问题

NewOffsetWriter 能不能接收普通 io.Writer？

不能。它要求基础对象实现 io.WriterAt，因为每次写入都需要明确的底层绝对偏移。

WriteAt 调用后再 Write，会从刚才的 WriteAt 位置继续吗？

不会。WriteAt 使用局部偏移直接写入，但不推进 OffsetWriter 的顺序当前位置；后续 Write 仍从此前的当前位置开始。

为什么 SeekEnd 不能直接用？

当前 OffsetWriter 的 Seek 实现只处理基础偏移和当前位置两种计算方式，没有区间长度可供它解释 SeekEnd。需要末尾定位时请把区间长度作为业务元数据管理。

OffsetWriter 会自动扩展文件吗？

它只负责把写入转换为对 WriterAt 的调用，不承诺基础对象的扩展策略。是否形成空洞、是否允许超出当前长度，取决于底层 WriterAt 的实现，例如文件对象的行为。

小结

io.NewOffsetWriter 的核心不是“再包一层 Writer”，而是把一个固定的基础偏移变成局部写入坐标。记住三点就够用：Write 会推进当前位置，WriteAt 只写局部偏移而不推进当前位置，Seek 不能把位置移到基础偏移之前，并且当前实现不处理 SeekEnd。这样在文件头、索引区或分段补丁场景里，业务代码可以只处理自己的区间坐标。