Go 旧版 ioutil 代码怎样迁移到 os 和 io

我在接手一段较早的 Go 代码时，最容易误判的一类改动就是把 io/ioutil 全部替换成 os。真正稳妥的做法不是机械改包名，而是先按职责拆分：文件和目录操作归到 os，流处理辅助函数归到 io。Go 1.16 之后，io/ioutil 仍然可用，但新代码应该使用这些新位置。

官方参考：https://go.dev/doc/go1.16

迁移可以保持大部分行为不变，但 ReadDir 是需要单独复查的边界：新接口返回 []os.DirEntry，不再是旧的 []os.FileInfo。

先按函数职责拆分迁移范围

ioutil 的问题在于它把文件系统和流操作混在了一个包里。我的习惯是先列一张替换表，再动 import。这样可以避免把目录对象的类型变化藏在一次批量替换里。

文件和目录调用优先迁移到 os

文件读写通常是最直接的一组改动，函数签名和错误处理方式基本保持不变：

package main

import "os"

func loadConfig(path string) ([]byte, error) {
	// ReadFile 负责读取整个文件，错误直接交给上层决定是否重试或退出。
	return os.ReadFile(path)
}

func saveConfig(path string, data []byte) error {
	// 权限参数仍由调用方明确给出，迁移不应顺手改变文件权限。
	return os.WriteFile(path, data, 0o600)
}

临时目录和临时文件也放在 os。如果旧代码依赖前缀、关闭顺序或 defer os.RemoveAll，这些业务约束都不要因为换包而删除。

目录读取则要多看一步。os.ReadDir 返回 []os.DirEntry，调用方可以用 Name、IsDir 和 Type 获取信息；如果后续逻辑明确需要完整的 FileInfo，就对单个条目调用 Info，而不是假设新返回值可以直接赋给旧切片。

流处理函数迁移到 io

只要对象实现了 io.Reader 或 io.Writer，迁移通常更清晰：

package decoder

import "io"

func readBody(r io.Reader) ([]byte, error) {
	// ReadAll 读取 Reader 的剩余内容；真实项目应根据输入大小评估内存上限。
	return io.ReadAll(r)
}

func ignoreBody(r io.Reader) error {
	// Discard 消费输入但不保存数据，返回值仍用于判断流读取是否出错。
	_, err := io.Copy(io.Discard, r)
	return err
}

NopCloser 同样迁移到 io。它适合把只有 Read 方法的对象临时包装成带空 Close 的 Reader，但不要把它当成真实资源关闭器：包装层的 Close 不会替你关闭底层连接或文件。

迁移后的兼容边界与检查清单

改完后我会做四个检查。第一，全文搜索 io/ioutil，确认残留项是有意保留还是遗漏。第二，重点看 ReadDir 的赋值、排序和接口参数，尤其是旧函数返回的 []os.FileInfo 是否被下游继续使用。第三，确认项目的最低 Go 版本能提供目标 API；如果还要兼容很老的工具链，迁移应先放进单独分支评估。第四，执行 gofmt 和 go test ./...，把编译问题与行为回归分开处理。

# 先找旧导入，再格式化并运行全量测试；失败时保留第一条错误继续定位。
rg 'io/ioutil' --glob '*.go' .
gofmt -w .
go test ./...

如果只是为了消除弃用提示，却没有确认目录类型、临时文件清理和最低版本，迁移很可能只是表面完成。相反，按职责替换再做一次类型检查，通常能把改动控制在很小范围内。

常见问题

io/ioutil 现在还能不能继续用？

能用。Go 1.16 的说明明确表示它会继续工作，但新代码推荐使用 io 与 os 中的对应定义。维护旧分支时可以分批迁移，不必为了弃用提示一次性重写业务。

os.ReadDir 能直接替换 ioutil.ReadDir 吗？

函数用途接近，但返回类型不同。只读取名称或判断目录时通常可以直接改；需要 FileInfo 的调用方要补上 entry.Info() 或调整接口。

迁移后为什么还要跑全量测试？

因为 import 替换能通过编译，并不代表目录类型、权限参数、临时资源清理和大文件读取策略都保持了原来的业务假设。