Go fix inline 怎样迁移带副作用的旧函数调用

升级 Go 工具链后，旧包里那些“只是转发一下”的函数很适合交给 go fix 迁移，但带副作用的实参不能只看替换后的函数名。//go:fix inline 做的是源码级改写：它会把调用点改成被调函数体的等价形式，同时尽量保住参数求值顺序、只求值一次和局部变量作用域。

官方地址：https://go.dev/blog/inliner

迁移的关键不是把旧函数名机械替换成新函数名，而是先把旧 API 设计成足够薄、语义明确的转发层，再用 go fix -diff 看清每个调用点的变化。遇到 defer、参数重复使用或生成未使用变量的情况，应停下来人工处理。

Go fix inline 到底改了什么

Go 1.26 重写了 go fix，其中的 inline 分析器会寻找带 //go:fix inline 注释的函数、类型或常量引用，并把调用方改成新的源码形式。它和编译器为了性能做的临时内联不是一回事：编译器不会持久化源文件，而 go fix 会产生可以提交到代码库的迁移。

最小的旧 API 包装可以这样写：

package oldmath

import "newmath"

// Sub 保留旧参数顺序，调用方迁移后改用 newmath.Sub。
//go:fix inline
func Sub(x, y int) int {
	// 注释说明参数顺序的转换，避免迁移时把 x、y 位置看反。
	return newmath.Sub(y, x)
}

调用方原来写成 oldmath.Sub(1, 10)，迁移后目标是 newmath.Sub(10, 1)，而不是简单地把包名替换掉。准备迁移时，先用下面的命令看差异：

# 只预览变更，不直接改写工作区。
go fix -diff ./...

# 只关注 inline 分析器，便于把迁移拆成独立提交。
go fix -inline -diff ./...

如果项目还在使用更旧的工具链，先确认 CI 和本地开发环境都能运行对应的 go fix。不要把编辑器中的编译器内联优化误认为已经完成源码迁移。

先把旧函数设计成可迁移的薄转发层

go fix inline 适合“旧入口只是把参数转给新入口”的迁移。旧函数中不要混入日志、全局状态写入、重试或额外的清理逻辑，否则调用点展开后，读者很难判断哪些行为属于旧 API 的兼容承诺。

例如，把旧的文件读取函数迁移到新的标准库入口时，函数体只保留一次转发：

package legacyio

import "os"

// ReadFile 兼容旧包名，实际读取交给 os.ReadFile。
//go:fix inline
func ReadFile(name string) ([]byte, error) {
	// 只传递一次文件名，迁移后不会重复触发调用方表达式。
	return os.ReadFile(name)
}

调用方即使传入一个有副作用的表达式，也应该只让它发生一次：

func nextPath() string {
	// 这里用计数器或日志记录路径生成次数，便于观察是否被重复求值。
	return "data/input.txt"
}

func load() ([]byte, error) {
	// 迁移目标应等价于 os.ReadFile(nextPath())，而不是调用 nextPath 两次。
	return legacyio.ReadFile(nextPath())
}

设计原则可以压缩成一句话：旧函数体中的每个实参只承担一次明确的转发责任，副作用放在调用方可观察的边界之外。

带副作用的参数要检查求值顺序

真正容易出问题的是包装函数改变了参数位置，或者一个参数在新函数中出现多次。假设旧 API 把参数顺序反过来：

package oldmath

import "newmath"

// Sub 保持旧 API 的 x-y 语义，目标 API 使用 y-x 的参数排列。
//go:fix inline
func Sub(x, y int) int {
	// 迁移器需要同时关注参数位置和每个实参的求值次数。
	return newmath.Sub(y, x)
}

调用处如果是 oldmath.Sub(nextLeft(), nextRight())，检查重点不是结果表达式长什么样，而是 nextLeft 和 nextRight 是否仍然各执行一次、执行顺序是否符合原调用语义。对于包含发送、接收、递增、日志记录或修改共享状态的表达式，更应该阅读 -diff 后再继续。

当参数必须先保存，安全的人工写法是显式引入临时变量：

func migrate(left, right func() int) int {
	// 先保存左实参，保证它只执行一次且顺序清楚。
	x := left()
	// 再保存右实参，后续目标调用只读取普通变量。
	y := right()
	// 这里保留旧 API 的参数语义，不让目标 API 重复调用函数值。
	return newmath.Sub(y, x)
}

这不是要求所有调用点都手写临时变量，而是给审查迁移结果时的一条判断标准：看到复杂实参被复制、移动或展开，确认它没有因为源码变换而多执行一次。

重复参数、局部变量和 defer 是三个分界线

官方内联器会处理不少语义细节，但“能处理”不等于“每次都得到最简洁的代码”。迁移前后至少看三类情况。

同一个参数在函数体中出现多次

如果旧函数把参数用于多个位置，而调用方传入的是复杂表达式，直接复制表达式可能改变副作用次数。内联器会在需要时引入临时值，保持参数只求值一次；审查时重点看临时变量是否出现在正确的语句位置。

无效实参可能让局部变量变成未使用

例如旧函数接收一个不会使用的参数，调用方却刚好把某个局部变量的最后一次引用放在这里：

//go:fix inline
func announce(_ int) {
	// 这个参数只为兼容旧签名保留，函数体不会读取它。
	println("ready")
}

func run() {
	x := 42
	// 迁移后 x 可能没有任何剩余引用，需要重新检查编译结果。
	announce(x)
}

删除调用后，x 可能触发未使用变量错误。这个问题不是业务逻辑改变，而是源码清理后的编译约束变化；修复通常是删除无用变量，或者保留真正需要的赋值。

函数体有 defer 时不要强行批量内联

defer 的执行时机与函数边界有关。若把带 defer 的函数体直接摊平到调用方，清理动作可能从“被调函数返回时”推迟到“调用方返回时”。gopls 的交互式重构可以用函数字面量包住这段逻辑，但批量 go fix 会拒绝这类不适合自动化的 literalized call。遇到这种情况，保留旧函数、手工重写并补测试比盲目追求零旧调用更稳妥。

用一套小流程收尾迁移回归

正式改写前先让工作区保持干净，便于审查差异。Go 官方对大范围 go fix 的建议也是从干净的 Git 状态开始，因为一次运行可能修改很多文件。

# 先确认迁移前没有混入其它改动。
git status --short

# 预览所有现代化建议，先只审查 inline 相关 diff。
go fix -inline -diff ./...

# 确认方向正确后再写入源码。
go fix -inline ./...

# 重新格式化受影响文件，保持提交差异集中。
gofmt -w ./path/to/changed.go

# 编译并运行测试，暴露未使用变量、导入和行为回归。
go test ./...

大型仓库还要注意构建标签。go fix 每次只分析一个具体构建配置；如果项目按操作系统或 CPU 使用不同文件，应分别设置 GOOS、GOARCH 再运行，避免只迁移了当前机器可见的调用点：

# 下面两个命令分别覆盖两种构建配置，按项目实际矩阵调整。
GOOS=linux GOARCH=amd64 go fix -inline ./...
GOOS=darwin GOARCH=arm64 go fix -inline ./...

最后把迁移拆成易审查的提交：一提交只放旧 API 的标注和目标包准备，二提交放 go fix 结果，三提交处理 defer、未使用变量和构建标签遗漏。若分析器报告有冲突或跳过修复，先按提示再次运行并逐个阅读差异，不要把警告当成已经完成。

迁移清单：什么时候可以自动化

归根结底，go fix inline 更像一份由 API 作者提供的迁移契约：它能把明确、薄、行为稳定的兼容层批量推向新 API，但不能替代对副作用和生命周期的代码审查。只要把自动化范围限定在可证明等价的转发函数内，再用 diff、编译、测试和构建矩阵收尾，旧调用就能逐步退出而不把隐藏行为一起带走。

相关问题

go fix inline 和编译器内联是同一件事吗？

不是。前者修改源文件，用于迁移和现代化；后者是编译阶段的优化，通常不会留下源码改动。

可以直接把所有旧函数都加上 //go:fix inline 吗？

不建议。先确认函数是薄转发层，并检查参数求值、局部变量和 defer 边界，再决定是否适合批量迁移。

为什么要先运行 go fix -diff？

因为它能把包名、参数顺序、临时变量和导入变化集中展示出来，审查无误后再写入源码更容易定位问题。