Go //go:fix inline 怎样为 API 迁移准备内联规则

如果一个旧 API 只是新 API 的薄包装，长期保留调用点会让迁移变成一项重复劳动。Go 1.26 重写了 go fix，并加入源代码级内联分析器；库作者可以在旧声明前写 //go:fix inline，让调用方把旧函数、常量或类型别名逐步改成新 API。

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

准备 API 迁移的关键不是给旧函数贴一个注释就结束，而是先让旧实现忠实转发到新 API，再用 go fix -inline -diff ./... 预览调用点变化。预览确认后才落盘，并把测试、参数副作用和无法自动整理的代码列入人工收尾清单。

先把旧 API 收敛成新 API 的薄包装

//go:fix inline 描述的是“如何把调用点改写成目标声明”。因此旧 API 最好已经用新 API 实现，迁移规则只负责把调用者带到新名字或新包，而不是在工具里隐含一套复杂业务逻辑。

package oldmath

import "example.com/newmath"

// Sub 保留旧参数顺序，内部转发到新包的逻辑顺序。
// Deprecated: 请改用 newmath.Sub。
//go:fix inline
func Sub(y, x int) int {
	return newmath.Sub(x, y)
}

这个例子把“兼容旧调用”和“迁移后的目标调用”分开：旧代码仍可编译，新代码可以逐步变成 newmath.Sub(10, 1)。如果参数顺序、默认值或包路径发生变化，都应在这个薄包装里明确写出来，便于审查生成的差异。

把指令放在能被分析器识别的位置

函数指令要紧挨着函数声明；常量和类型别名也可以使用同一指令。对于常量，官方分析器要求它引用另一个具名常量；类型别名则应直接指向目标类型。

package oldmath

import "example.com/newmath"

// Deprecated: 新包允许调用方显式选择方向。
//go:fix inline
func Inf() float64 {
	// 固定旧 API 的默认语义，迁移后保留同样的结果。
	return newmath.Inf(+1)
}

//go:fix inline
type Rational = newmath.Rational

//go:fix inline
const Pi = newmath.Pi

不要把指令写成普通说明文字，也不要把一个需要复杂判断的迁移硬塞进包装函数。这个机制适合重命名、换包、补充固定参数、修正明确的参数顺序，以及把旧类型或常量转到新声明。

先用 diff 观察迁移面，再决定是否落盘

准备好规则后，先对目标包做差异预览。-inline 只启用内联分析器，-diff 让结果停留在预览阶段；这样可以先检查 import 是否切换、参数是否按预期排列，以及是否出现绑定变量。

# 只预览所有包的内联迁移，不直接改写源文件。
go fix -inline -diff ./...

# 确认差异后，再把同一分析器的修复写回工作树。
go fix -inline ./...

批量迁移时不要只看“旧函数名是否消失”。还要看新包是否被正确导入、调用参数是否保留原语义、无关调用点是否没有被触碰。如果项目有专门的兼容测试，应把旧 API 自身的测试保留到迁移完成之后。

四个容易让迁移停在半路的边界

参数副作用。分析器会注意调用参数的求值顺序；当无法证明替换安全时，可能保留参数绑定声明。不要为了让结果更短而手工删掉这些绑定，先确认副作用顺序没有改变。

defer 与函数生命周期。带 defer 的函数不能简单地把函数体摊进调用者，否则延迟调用的生命周期会改变。go fix 的批量内联分析器会拒绝这类不适合自动落盘的 literalization，遇到它应改用人工重构。

测试和示例。专门测试旧符号的 TestX、基准和示例不会被当成普通调用点内联，避免迁移工具把测试对象本身删掉。迁移完成后，再决定是否删除旧 API 的兼容测试。

样式与残留差异。安全不等于一定漂亮。工具可能保留局部变量、绑定声明或新的 import 组织；批量提交前可以人工整理，但不要把“整理代码”与“验证迁移语义”混为一件事。

一份适合提交前使用的迁移顺序

1. 确认旧声明确实只是新 API 的兼容包装，并写清弃用说明。
2. 在函数、常量或类型别名前添加 //go:fix inline，先覆盖一个小包。
3. 用 go fix -inline -diff ./... 阅读 import、参数和绑定变量变化。
4. 分批落盘，保留旧 API 测试，处理无法自动内联的 defer 或复杂逻辑。
5. 按项目既有流程运行构建和测试，再评估是否可以删除旧包或旧声明。

常见问题

这个指令能替代所有 API 重构吗？

不能。它适合可以表达为安全转发的函数、具名常量和类型别名迁移；涉及业务分支、资源生命周期或复杂语义变化时，仍需要专门的迁移代码和人工审查。

为什么预览里出现了 var 参数绑定？

这是分析器为了保持参数求值顺序或避免重复计算而保留的中间绑定。它可能不够简洁，但优先保证迁移不会改变行为。

能不能直接对整个仓库执行？

可以从 ./... 开始，但更稳妥的做法是先在一个包上用 -diff 观察，再扩大范围；仓库中仍在维护旧 API 行为的测试和示例要特别留意。

总结一下：先用新 API 实现旧 API，再用 //go:fix inline 把迁移关系声明出来，最后通过差异预览和分批落盘控制影响面。函数、常量和类型别名适合这条路径；副作用、defer 和复杂业务逻辑则应保留人工判断。