Go //go:fix inline 怎么迁移改名后的 API 调用

Go 1.26 的新 go fix 支持 //go:fix inline 指令。库作者只要保留旧 API 的兼容包装函数，让函数体调用改名后的新 API，再把指令放在旧声明上方，下游执行 go fix 时就能把旧调用改写为新调用。它依赖源码级内联，不是简单字符串替换，因此还能处理导入变化和参数重排。

官方说明：https://go.dev/blog/inliner

升级范围：什么时候适合用 //go:fix inline

我第一次看到这个能力时，最容易误解成“给新函数加个重命名规则”。实际正好相反：指令加在旧声明上，旧声明的函数体就是迁移模板。典型场景包括：

• 函数从旧包移动到新包，签名保持兼容；
• 函数改名，同时参数顺序调整；
• 旧的常量或类型名迁移到新包；
• 旧辅助函数可直接表达为新的标准写法。

它不适合需要业务判断、数据迁移或行为语义变化很大的升级。此时兼容层无法完整表达迁移规则，应继续提供人工迁移文档。

变更表：库作者与调用方分别做什么

旧代码风险：直接搜索替换为什么不够

假设旧函数叫 oldcalc.Sub(y, x)，新函数改为更自然的 newcalc.Sub(x, y)。只把包名和函数名替换掉，会保留错误的参数顺序。源码级内联会把实参按旧函数参数绑定到函数体，再生成新调用，因此能得到正确顺序。

另一个常见风险是副作用。如果参数表达式会修改状态，粗糙的替换可能重复求值或改变求值顺序。官方内联器会保守处理这些语义问题；无法证明安全时，宁可不生成批量修复。

新写法：在旧声明上提供迁移模板

下面是一个完整的最小示例。新包提供目标 API：

package newcalc

// Sub 按自然顺序计算 x-y，作为迁移后的目标 API。
func Sub(x, y int) int {
	return x - y
}

旧包保留兼容函数，并用函数体描述迁移方式：

package oldcalc

import "example.com/project/newcalc"

// Sub 保留旧参数顺序，避免现有调用在升级时立即失效。
// Deprecated: 请改用 newcalc.Sub。
//
//go:fix inline
func Sub(y, x int) int {
	// 参数在这里交换，内联器会把调用点改成 newcalc.Sub(x, y)。
	return newcalc.Sub(x, y)
}

调用方原来写的是：

package report

import "example.com/project/oldcalc"

// delta 使用旧 API，10-1 的结果应为 9。
var delta = oldcalc.Sub(1, 10)

运行修复后，调用会变成：

package report

import "example.com/project/newcalc"

// delta 已迁移到新包，并保持 10-1 的原有语义。
var delta = newcalc.Sub(10, 1)

这里不仅改了函数名，还交换了参数并更新了导入；这正是普通文本替换很难可靠完成的部分。

先预览，再批量执行

在真实仓库里，我更倾向于先看 diff，确认新工具链识别到了指令，再落盘修改：

# 确认正在使用支持新 go fix 的 Go 1.26 或更新工具链
go version

# 只预览整个模块的修复，不修改文件
go fix -diff ./...

# 确认差异后再写入源码
go fix ./...

如果只想缩小范围，可以把 ./... 换成具体包路径。大型仓库最好按包或业务域分批提交，避免把 API 迁移与无关格式变化混在一个审查中。

回归检查：改完不等于结束

go fix 的目标是不改变程序行为，但迁移仍应像正常代码变更一样审查和测试。建议至少执行：

# 统一格式，确保生成代码符合项目风格
gofmt -w .

# 运行全部测试，覆盖参数顺序与错误路径
go test ./...

# 运行静态检查，发现迁移后未使用的导入或其他问题
go vet ./...

还要搜索旧 API 是否仍有引用。剩余调用不一定代表工具失效，可能是该调用内联后需要函数文字包装、涉及复杂控制流，或工具无法证明改写结果足够安全整洁。

边界条件：哪些声明可以迁移

除了函数，官方说明还支持用转发声明迁移类型别名和常量。例如：

package oldcalc

import "example.com/project/newcalc"

//go:fix inline
type Number = newcalc.Number // 类型引用迁移到新包

//go:fix inline
const Pi = newcalc.Pi // 常量引用迁移到新包

对于函数，包装体越简单越适合批量迁移。如果函数包含 defer、复杂控制流或容易改变求值行为的表达式，交互式内联可能给出较复杂结果，而 go fix 的批量策略会更保守。

迁移清单

1. 先发布新 API，并让旧 API 继续兼容现有调用。
2. 把旧 API 实现收敛为调用新 API 的简单包装。
3. 在旧声明文档末尾加入独立的 //go:fix inline 指令。
4. 使用 Go 1.26+ 的 go fix -diff 查看参数和导入变化。
5. 分批执行修复，运行格式化、测试与静态检查。
6. 人工处理工具拒绝的调用，再评估是否删除旧依赖。

这套方式的价值不是“把改名自动化”这么简单，而是把兼容包装声明本身变成可执行的迁移知识。库作者负责表达语义，工具负责在调用点安全展开，下游仍负责审查和回归。