Go SFTP PosixRename 与 Rename 的覆盖行为有什么区别

在 Go 的 SFTP 发布流程里，Rename 和 PosixRename 不能只看名字判断。最关键的差异是：PosixRename 使用 OpenSSH 的 posix-rename@openssh.com 扩展，官方文档明确说明目标已存在时会被替换；Rename 只发送标准重命名请求，文档没有承诺覆盖目标。

官方地址：https://pkg.go.dev/github.com/pkg/sftp

如果你的业务要求“用临时文件发布并替换同名正式文件”，优先探测服务器是否支持 posix-rename@openssh.com，支持时调用 PosixRename；不支持时不要把 Rename 当成等价替代，应明确失败或设计备份、删除和重试策略。

两个方法发出的请求并不相同

github.com/pkg/sftp 的实现把两条路径分开：Rename 组装标准的 SSH_FXP_RENAME 请求，PosixRename 组装带有 posix-rename@openssh.com 语义的扩展请求。前者更通用，后者的覆盖承诺更明确，但依赖服务端能力。

因此，不能只因为两个方法都接收 oldname 和 newname，就认为它们在目标已存在时的结果相同。

覆盖行为要看目标文件的当前状态

可以用两个输入状态和两个 API 组成四格判断矩阵。这里的“2×2”是排查维度，不是压测结果：目标不存在时，两者都可能完成重命名；目标已经存在时，PosixRename 才有明确的替换语义，而 Rename 的最终结果取决于服务端对标准请求的处理。

先探测扩展，再决定是否允许覆盖

服务端能力可以通过 HasExtension 查询。探测不到扩展时，最稳妥的做法是返回带上下文的错误，让调用方选择“停止发布”还是“改名保存”；不要静默降级到 Rename，否则失败可能变成旧文件一直保留，或者不同服务端表现不一致。

package publish

import (
    "fmt"

    "github.com/pkg/sftp"
)

// ReplaceRemoteFile 只在服务端声明扩展时执行覆盖式发布。
func ReplaceRemoteFile(client *sftp.Client, tempPath, finalPath string) error {
    // 扩展名是服务端能力探测结果，不是客户端本地配置。
    if _, ok := client.HasExtension("posix-rename@openssh.com"); !ok {
        return fmt.Errorf("sftp server does not support posix rename: %s", finalPath)
    }

    // PosixRename 的语义包含替换已存在的目标文件。
    if err := client.PosixRename(tempPath, finalPath); err != nil {
        return fmt.Errorf("publish %s -> %s: %w", tempPath, finalPath, err)
    }
    return nil
}

这段函数只表达选择边界，并没有把服务器返回成功当成“已经验证过的线上状态”。生产代码还应记录远程路径、发布批次和错误码，同时确保临时文件命名不会与并发发布互相覆盖。

什么时候可以继续用 Rename

如果目标文件一定不存在，或者业务接受服务端对标准重命名请求的原生规则，Rename 仍然足够。它也适合不需要替换语义的“移动到新名字”场景。反过来，配置文件热切换、版本指针更新、同名报表发布这类场景通常要求新文件替换旧文件，就应该把扩展支持作为前置能力条件。

如果服务端不支持扩展，可以改成“备份旧文件—删除旧文件—Rename 新文件”，但这已经不是同一个覆盖语义：中间可能出现目标不存在的窗口，也可能因权限、网络中断或并发写入留下半完成状态。除非业务明确接受这个窗口，否则应停止发布并更换服务端能力。

常见问题

PosixRename 一定适用于所有 SFTP 服务器吗？

不一定。它依赖服务端实现并声明对应扩展；先用 HasExtension 判断，不能仅依据客户端包中存在这个方法就假设远端支持。

把 Rename 改成 PosixRename 就能保证发布原子性吗？

不能把“替换目标”扩大解释成完整的业务事务保证。它解决的是重命名请求对已存在目标的覆盖语义，权限、存储后端、并发写入和网络故障仍需单独设计。