Go os.File.WriteAt 怎样判断固定偏移写入是否完整

用 os.File.WriteAt 写文件块时，判断是否完整不能只看 err == nil，也不能只看返回的字节数。最稳妥的边界是：把 n 和 len(p) 放在一起比较；当 n != len(p) 时优先保留底层错误，没有错误也要按短写处理。

官方地址：https://pkg.go.dev/os#File.WriteAt

下面的文章只讨论固定偏移写入的完整性判断，不展开追加模式、并发写入安全和文件同步落盘。对普通文件而言，WriteAt(p, off) 把数据写到指定的字节偏移，返回实际写入的 n 和错误 err。

先把“写成功”定义成 n 等于 len(p)

假设要写入的切片是 p。完整写入的首要条件是 n == len(p)。Go 的 os.File.WriteAt 文档还规定，当 n != len(p) 时应返回非空错误；因此工程代码既要检查长度，也要检查错误，才能对自定义实现、包装器或底层异常保持清晰的边界。

另一个容易混淆的条件是文件打开方式。若文件使用了 os.O_APPEND，WriteAt 会返回错误；固定偏移写入需要在打开文件时就选择不带追加语义的方式。

固定偏移、输入切片和返回值各自负责什么

可以把一次调用看成三个静态对象的组合：p 描述期望写入的字节，off 指定目标区间起点，返回的 n 与 err 描述本次请求实际完成到哪里。WriteAt 使用的是显式偏移，不依赖调用方先执行 Seek 来定位当前读写位置。

这张图的关键不是箭头表示执行顺序，而是帮助定位判断边界：输入长度由 len(p) 给出，实际结果由 n 给出，是否存在底层停止原因由 err 给出。三者缺一不可。

用一个小函数保留短写和原始错误

把判断收在一个函数里，调用者就不会在业务代码中重复写“只看 err”的不完整逻辑。下面的示例不依赖运行时截图，重点是把判断顺序写清楚：

package main

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

// writeAtComplete 只负责判断一次固定偏移写入是否完整。
func writeAtComplete(file *os.File, off int64, payload []byte) error {
	// WriteAt 使用显式偏移，不需要先改变文件的当前顺序位置。
	n, err := file.WriteAt(payload, off)

	// 先判断 n，避免底层错误被“err == nil”之外的逻辑遗漏。
	if n != len(payload) {
		if err != nil {
			// 保留原始错误，方便上层用 errors.Is 或 errors.As 继续判断。
			return fmt.Errorf("固定偏移写入不完整：已写 %d/%d 字节：%w", n, len(payload), err)
		}
		// 自定义 WriterAt 出现无错误短写时，转换成标准短写错误。
		return io.ErrShortWrite
	}

	// n 已经等于请求长度，但仍不吞掉异常返回值。
	return err
}

这里的 n != len(payload) 是完整性判断，err != nil 是原因判断。把两者分开写，既能保留底层错误，也能防止非标准实现返回“短写但无错误”时被误判为成功。

三种现场要分开记录

在日志或上层错误中，至少要留下目标偏移、请求长度、实际长度和错误值。这样后续才能区分“根本没有完成写入”和“已经写入一部分后停止”。

• 完整写入：n == len(p) 且通常 err == nil，当前块可以标记为完成。
• 部分写入：n ，即使已经有一部分字节落到目标区间，也不能把当前块标成完成。
• 调用前或写入过程中失败：n == 0 只是常见表现，不应据此猜测唯一原因，必须保留 err 并由错误类型决定上层处理。

不要把“部分写入后重试”写成无条件规则。是否能重试取决于上层协议是否允许覆盖同一文件区间、错误是否可恢复，以及是否需要避免重复写入。当前函数只负责把一次调用的真实结果传出去。

把一次成功放回文件块流程里

如果业务是分块写入，建议每个块都带着自己的偏移和长度进入判断函数。上一块返回成功，只说明上一块满足 n == len(p)，并不等于整个文件已经写完；文件总长度、块顺序和最终收尾应由更高一层管理。

// writeBlocks 按调用方给出的块偏移逐块写入，并在首个异常处停止。
func writeBlocks(file *os.File, blocks []struct {
	off  int64
	data []byte
}) error {
	for index, block := range blocks {
		// 每个块独立判断，避免把前一个块的成功带到下一个块。
		if err := writeAtComplete(file, block.off, block.data); err != nil {
			return fmt.Errorf("第 %d 个文件块失败：%w", index, err)
		}
	}
	return nil
}

这个封装的价值在于让“块完成”成为明确的局部事实：每次都使用自己的 off、data 和返回值。若业务需要断点续写，再由上层根据错误类型和已经写入的字节数设计恢复记录。

常见误区

只判断 err == nil

这会把错误组合和非标准短写实现隐藏起来。固定偏移写入是否完整，必须把 n 与 len(p) 比较。

把 n == 0 当成唯一失败形态

短写可以已经写入一部分字节，n 的数值还决定了恢复记录从哪个位置开始。不要只保存一句“写失败”。

把 WriteAt 当成追加写入

WriteAt 的语义是把数据放到显式偏移；带 O_APPEND 打开文件时会报错。追加和固定偏移是两种不同的文件写入约束。

结语

判断 os.File.WriteAt 是否完整，核心只有一个可复用的边界：n == len(p)。然后再根据 err 判断原因；短写且有错误时保留原始错误，短写但无错误时转成 io.ErrShortWrite。把这段逻辑封装起来，分块写入和断点恢复都会更容易维护。

相关问题

• WriteAt 会不会改变文件当前偏移？固定偏移调用使用传入的 off，不要把它和先 Seek 再 Write 的顺序写入模型混用。
• 为什么返回 n 之后还要保存 err？因为 n 只说明完成了多少字节，err 才描述停止原因，两者服务于不同判断。
• 短写一定要重试吗？不一定。是否重试要由文件块协议、错误可恢复性和重复覆盖风险共同决定。