Go net/http NewFileTransportFS 怎样让 HTTP 客户端读取 fs.FS

如果测试代码、命令行工具或本地资源读取已经统一使用 http.Client，再为文件系统单独写一套读取逻辑会让接口越来越散。Go 的 net/http.NewFileTransportFS 可以把一个 fs.FS 适配成客户端侧的 RoundTripper，让调用方用 file:// URL 读取目录或嵌入文件系统。

它的关键不是“把文件变成 HTTP 服务”，而是把文件系统接到 HTTP 客户端的传输层。官方地址：

官方地址：https://pkg.go.dev/net/http#NewFileTransportFS

记住一句话：NewFileTransportFS 返回的是客户端传输器；要访问文件，准备好 fs.FS、注册 file 协议，再像调用 HTTP 客户端一样处理 Response.Body。

接口目标：NewFileTransportFS 到底接在 HTTP 客户端哪一层

NewFileTransportFS(fsys) 接收 fs.FS，返回一个 http.RoundTripper。它不会创建监听端口，也不是 http.FileServerFS 那类服务端 Handler。最常见的接法是把它注册到 http.Transport 的 file 协议上，让同一个客户端继续处理普通 HTTP/HTTPS 请求。

package main

import (
	"io"
	"net/http"
	"os"
)

func newClient(root string) (*http.Client, error) {
	fsys := os.DirFS(root)
	transport := &http.Transport{}
	// 只把 file 协议交给文件系统传输器，其他协议仍由 Transport 负责。
	transport.RegisterProtocol("file", http.NewFileTransportFS(fsys))
	return &http.Client{Transport: transport}, nil
}

func readFile(root string) ([]byte, error) {
	client, err := newClient(root)
	if err != nil {
		// 初始化失败时不继续构造请求，避免掩盖 Transport 问题。
		return nil, err
	}
	resp, err := client.Get("file:///README.md")
	if err != nil {
		// 文件不存在、路径不合法等错误会在客户端请求阶段返回。
		return nil, err
	}
	defer resp.Body.Close()
	// 读取完响应体后由调用方决定如何解析文件内容。
	return io.ReadAll(resp.Body)
}

这个例子把 root 作为文件系统根目录，URL 中的路径对应 fs.FS 的相对路径。Transport 的职责是把协议映射到文件；客户端仍然负责处理响应状态、读取响应体和关闭资源。

参数设计：fs.FS、路径和 file URL 要保持同一套边界

io/fs 的路径是 UTF-8、无根、用斜杠分隔的路径名，例如 docs/readme.md；不要把操作系统的绝对路径直接当成 fs.FS 内部路径。使用 os.DirFS(root) 后，root 已经成为文件系统视图的根，客户端请求只需要表达这个视图内的文件。

官方文档还特别说明，NewFileTransportFS 返回的传输器会忽略 URL host 以及请求的大部分其他属性。因此不要把 host 当成访问控制手段；真正的访问边界应由传入的 fs.FS、目录权限和上层业务规则共同决定。

错误处理：路径、io.Seeker 和响应体要分别处理

这条链路至少有三类容易混淆的失败。第一类是 URL 映射后找不到文件，应该检查 FS 根目录和相对路径；第二类是文件对象不满足传输器需要的 io.Seeker 能力，不能只实现顺序读取；第三类是请求成功后没有关闭 Response.Body，这属于资源生命周期问题。

package main

import (
	"errors"
	"fmt"
	"io"
	"net/http"
	"os"
)

func loadConfig(client *http.Client, name string) ([]byte, error) {
	resp, err := client.Get("file:///" + name)
	if err != nil {
		// 请求阶段错误通常对应路径、打开文件或读取能力问题。
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		// 非成功状态不应直接交给配置解析器。
		return nil, fmt.Errorf("file response status: %s", resp.Status)
	}
	data, err := io.ReadAll(resp.Body)
	if err != nil {
		// 读取失败与路径存在是两件事，要保留原始错误。
		return nil, err
	}
	return data, nil
}

func isMissing(err error) bool {
	// 业务层可以把不存在文件单独映射成默认配置或清晰提示。
	return errors.Is(err, os.ErrNotExist)
}

示例中的 isMissing 只是错误分类入口，不意味着所有实现都会把底层错误直接包装成同一个值。实际项目应保留原始错误链，并在测试中覆盖空文件、目录路径、非法路径和缺少 io.Seeker 的自定义 FS。

兼容策略：什么时候注册 file 协议，什么时候单独使用传输器

如果客户端既要请求普通网络地址，又要读取本地或嵌入文件，优先使用 http.Transport.RegisterProtocol，这样 file 只是一个明确的替代协议。若工具只允许读取受控文件系统，也可以直接把 http.NewFileTransportFS(fsys) 作为客户端的 Transport，但这会让客户端不再拥有默认的 HTTP/HTTPS 网络能力。

还要区分两个方向：客户端侧使用 NewFileTransportFS；服务端把文件系统暴露给浏览器，则应看 http.FileServerFS 等 Handler。两者都接收文件系统概念，但调用方向、权限边界和部署风险完全不同。

调用清单：把文件来源、请求和资源生命周期对齐

1. 先确定 fs.FS 的根目录或嵌入视图，不把用户输入直接拼成宿主机绝对路径。
2. 确认访问 URL 使用 file 协议，并让路径符合 FS 的 slash-separated 规则。
3. 需要混合协议时注册替代协议；不需要网络访问时再考虑单独的文件传输器。
4. 确认自定义文件实现满足文档要求的 io.Seeker 能力。
5. 读取 Response.Body 后始终关闭它，并区分请求错误、状态错误和读取错误。

因此，标题中的问题可以落成一条稳定的 API 组合：fs.FS → NewFileTransportFS → RoundTripper → http.Transport → http.Client → file URL。只要不把它误解成服务端静态文件 Handler，并把路径和资源关闭放在各自边界上，就能让文件读取复用 HTTP 客户端的调用方式。

相关问题

NewFileTransportFS 能直接读取任意 io.Reader 吗？

不能。它接收的是 fs.FS，再由文件系统打开文件；如果数据本身只是一个 Reader，应直接使用对应的读取接口，而不是把 Reader 强行包装成文件系统。

为什么文件读到了还要关闭 Response.Body？

客户端响应仍遵循 HTTP 资源生命周期。关闭 Body 能让传输器完成资源回收；即使是本地文件协议，也不应因为没有网络连接就省略关闭动作。