Go billy 不同文件系统之间为什么不能直接 Rename

在 go-billy 里把文件从内存文件系统搬到操作系统文件系统时，很多人会自然地写成一次 Rename，然后发现调用边界不对。原因并不是 billy 忘了实现“跨盘移动”，而是 Rename(oldpath, newpath) 本来就是某一个 billy.Filesystem 实例上的方法：两个参数只是这个实例内部的路径，不携带另一个文件系统对象。

官方文档：https://pkg.go.dev/github.com/go-git/go-billy/v6

如果源路径和目标路径属于同一个 billy.Filesystem，可以调用该实例的 Rename；如果目标属于另一个 Filesystem，就要把问题改写成“源 FS 读取、目标 FS 写入、资源关闭、成功后删除源文件”。这是一段显式迁移流程，不应包装成跨后端原子重命名。

为什么 Rename 只负责同一个文件系统实例

从接口形状就能看出作用域。Filesystem 继承的基础接口提供 Rename(oldpath, newpath string) error，方法的接收者已经确定了操作对象；两个字符串只负责描述对象在这个文件系统中的旧路径和新路径。它们不是 sourceFS 与 targetFS 的一对地址。

因此下面的代码表达的是同一个文件系统实例里的改名或移动。目标目录可以不同，但仍然由 fs 负责解释路径。

// 同一 Filesystem 内部的路径移动，两个路径都由 fs 解释。
func renameInside(fs billy.Filesystem) error {
	// 这里的 oldPath 和 newPath 属于同一个 fs 的命名空间。
	return fs.Rename("incoming/report.txt", "archive/report.txt")
}

即使两个实例都实现了同一套接口，它们背后的存储也可能完全不同：一个是 memfs，另一个是 osfs，还可能是远端或自定义实现。接口统一的是调用方式，不是把两个后端合并成一个命名空间，更没有替调用方协调两个后端提交的职责。

把跨 FS 路径误当成普通路径会发生什么

下面这种思路的问题在于，dstFS 没有参与调用。即使把目标路径写得像另一个根目录，srcFS.Rename 仍会把它当成源实例里的字符串路径；它不会自动切换到 dstFS，也无法知道目标对象应该由哪个后端创建。

// 错误的抽象：dstPath 只是字符串，没有携带 dstFS 的所有权。
func wrongIdea(srcFS, dstFS billy.Filesystem, srcPath, dstPath string) error {
	// dstFS 在这里没有被调用，所以不可能完成两个实例之间的迁移。
	return srcFS.Rename(srcPath, dstPath)
}

同一个 FS 内的 Rename 也不等于所有后端都具备相同的底层语义。官方接口文档保留了操作系统和存储实现的限制，例如目标已经存在、跨目录限制或只读后端都可能导致错误。接口抽象减少了调用方对具体存储的依赖，但不会凭空增加跨存储事务。

跨文件系统移动要改成复制与删除

跨实例移动要把目标对象明确交给 dstFS 创建，再把源文件的字节写入目标。只有复制成功、目标文件关闭成功、源文件关闭成功后，才考虑删除源文件。这样做的关键不是让过程看起来像 Rename，而是保留每一步的错误边界。

package transfer

import (
	"fmt"
	"io"

	"github.com/go-git/go-billy/v6"
)

// MoveAcrossFS 用复制后删除表达两个 Filesystem 实例之间的迁移。
func MoveAcrossFS(srcFS, dstFS billy.Filesystem, srcPath, dstPath string) error {
	// 源文件由 srcFS 打开，目标文件由 dstFS 创建，不能混用接收者。
	src, err := srcFS.Open(srcPath)
	if err != nil {
		return fmt.Errorf("open source: %w", err)
	}

	dst, err := dstFS.Create(dstPath)
	if err != nil {
		// 目标创建失败时先关闭已经打开的源文件，再保留原错误。
		_ = src.Close()
		return fmt.Errorf("create destination: %w", err)
	}

	// 复制失败时不能删除源文件，避免只留下半个目标文件。
	if _, err = io.Copy(dst, src); err != nil {
		_ = dst.Close()
		_ = src.Close()
		_ = dstFS.Remove(dstPath)
		return fmt.Errorf("copy bytes: %w", err)
	}

	// 先关闭目标和源，确认句柄错误没有被忽略，再删除源文件。
	if err = dst.Close(); err != nil {
		_ = src.Close()
		return fmt.Errorf("close destination: %w", err)
	}
	if err = src.Close(); err != nil {
		return fmt.Errorf("close source: %w", err)
	}
	if err = srcFS.Remove(srcPath); err != nil {
		return fmt.Errorf("remove source: %w", err)
	}
	return nil
}

这个实现故意没有把“复制完成”说成“迁移已经原子提交”。如果删除源文件失败，源和目标可能同时存在；如果目标关闭失败，也不能放心删除源文件。调用方应该把错误记录下来，并根据业务决定重试、清理目标还是让人工处理，而不是直接忽略最后一步。

目录、元数据和失败恢复要单独判断

上面的示例针对文件内容。目录迁移需要递归读取并为目标目录创建对应结构；权限、修改时间、符号链接和稀疏文件等元数据也不会因为 io.Copy 自动获得跨后端等价表示。如果业务依赖这些属性，应在复制策略中显式记录和处理。

错误恢复可以按结果分成三类：

这也是跨 FS 方案与同 FS Rename 最大的工程差异：前者要设计中断后的状态，后者只需要处理当前后端对重命名操作返回的错误。

用这张清单选择 Rename 还是迁移

1. 先确认源路径和目标路径是否都由同一个 billy.Filesystem 实例解释；是的话才考虑 Rename。
2. 如果代码里同时出现 srcFS 和 dstFS，不要把目标 FS 隐藏在路径字符串中，改用显式的打开、创建和复制。
3. 复制完成前不删除源文件；目标和源句柄关闭失败时，也不要假设数据已经安全落地。
4. 把删除源文件看作独立的失败点，保留错误和两边状态，必要时提供幂等清理或人工恢复入口。
5. 如果需要目录、权限、时间戳或符号链接等语义，先为这些元数据定义跨后端映射，再决定是否能称为“移动”。

几个容易混淆的问题

两个 Filesystem 的根目录相同，还能直接 Rename 吗？

不能仅凭根路径相同就作出这个判断。真正的边界是调用所用的 Filesystem 实例及其实现；如果要让一个实例负责两个路径，应在同一实例的命名空间里表达，而不是把两个实例的职责混在一次调用中。

复制成功后可以立刻删除源文件吗？

至少要先处理目标文件和源文件的关闭错误。示例把删除放到两个关闭成功之后，是为了避免把仍可能有写入错误的目标当成完整副本。

跨 FS 复制能保证原子性吗？

不能。复制和删除是多个操作，任何一步都可能失败；如果业务要求可恢复，应保存迁移状态、目标临时名和清理记录，而不是伪装成一次 Rename。

记住一句话即可：Rename 的两个路径属于方法接收者代表的同一个文件系统；跨 billy 实例时，明确使用两个接收者完成复制，再以独立的删除动作收尾，才能把错误和恢复边界交代清楚。