用 //go:fix inline 发布可自动迁移的替代 API

如果一个 Go 包已经发布了旧函数，但新包拥有更清晰的参数顺序或更合适的实现，可以在旧入口上声明 //go:fix inline，把“兼容调用”和“源码迁移”分开处理：旧代码仍能编译，调用方运行 go fix -inline ./... 后再逐步改成新 API。

官方资料：https://go.dev/blog/inliner

把旧入口设计成可迁移的转发层

这个机制适合“旧 API 还能工作，但希望用户离开它”的迁移。下面用两个虚构包名演示：legacyclock 保留兼容入口，真正的实现放在 clockkit。转发函数应尽量短，参数顺序也要明确写成新 API 需要的样子。

package legacyclock

import "example.com/clockkit"

// Deprecated: 请改用 clockkit.After。
// 这条指令让 go fix 能把调用方迁移到新包。
//go:fix inline
func After(deadline time.Time, now time.Time) bool {
	// 保留旧入口的参数语义，再转给新包。
	return clockkit.After(now, deadline)
}

真实代码还需要补上 time 导入。关键不在于“给旧函数加一条注释”，而在于函数体必须能无歧义地表达替代调用。迁移后，调用方可以直接依赖 clockkit.After，旧包才有机会在后续主版本中退出。

函数、常量和类型别名分别怎么标记

inline 分析器处理的不只有函数。函数迁移要关注调用表达式，常量迁移要求右侧引用命名常量，类型迁移则使用类型别名。三种写法都要把指令放在声明前，并让替代对象来自新包。

package legacyclock

import "example.com/clockkit"

//go:fix inline
const DefaultZone = clockkit.DefaultZone

//go:fix inline
type Location = clockkit.Location

//go:fix inline
func ParseStamp(text string) (clockkit.Stamp, error) {
	// 把旧包的解析入口收敛到新包，错误值仍由新包返回。
	return clockkit.ParseStamp(text)
}

常量不要把指令放到一个无关的声明前，也不要把普通字面量误当成迁移目标。类型别名适合“名称换了、类型身份不应改变”的场景；如果新旧类型并不等价，就应设计显式转换函数，而不是强行内联。

用 go fix 预览并应用跨包迁移

发布新包后，先让一个干净的 Git 工作区承载差异。只查看 inline 规则时使用下面的命令：

# 只预览 inline 分析器准备修改的文件
go fix -diff -inline ./...

# 确认差异后，再把迁移写回源码
go fix -inline ./...+
# 迁移后整理导入并执行测试
gofmt -w .
go test ./...

如果旧函数位于被多个模块依赖的公共包中，调用方的导入路径和参数顺序都应进入差异审查。命令的目标是源代码迁移，不是编译器运行时优化；不要因为生成的二进制大小或速度没有变化，就判断规则没有生效。

自动迁移后要检查哪些边界

安全的自动迁移不等于无条件替换。分析器会尽量保持参数求值顺序；当直接替换可能改变副作用顺序时，可能插入参数绑定声明。这样的结果更保守，但比悄悄改变行为更可靠。

// 指令标记的包装函数
//go:fix inline
func JoinPair(left, right string) string {
	// 这里的返回值没有副作用，适合做简单迁移示例。
	return left + ":" + right
}

// 调用方的参数先按绑定规则求值，再进入替代表达式。
result := JoinPair(loadLeft(), loadRight())

含有 defer 的函数尤其要谨慎：直接把函数体搬到调用点会改变延迟执行的生命周期，因此批量分析通常会放弃这种不够整洁的替换。专门测试某个符号的 TestX、基准和示例也不会为了迁移而删除对该符号的覆盖，这正是测试边界。

版本门槛与发布清单

这类规则依赖支持它的 Go 工具链。库作者应在发布说明中写清最低工具链和迁移步骤；调用方则应先在目标分支预览差异，保留旧 API 的兼容期，再决定是否删除旧依赖。一个实用的发布清单如下：

• 旧函数体是否只表达新 API 的等价转发，是否写明弃用方向。
• 是否为函数、常量、类型别名分别选择了正确的指令位置。
• 是否用 go fix -diff -inline ./... 审查跨包改动，并运行 go test ./...。
• 是否单独复核副作用、defer、未使用变量和测试文件，而不是只看编译是否通过。

相关问题

go fix -inline 会自动删除旧包吗？

不会。它主要改调用方源码；旧包是否能删除，要等所有消费者完成迁移，并经过依赖和版本兼容审查。

普通函数都能加 //go:fix inline 吗？

不建议。只有替代关系稳定、函数体足够清晰且边界可审查时才适合标记；含复杂副作用或生命周期语义的函数应保守处理。

为什么预览结果里出现绑定变量？

通常是为了保持调用参数的求值顺序、避免名称遮蔽或避免把运行时检查提前成编译期错误。它是安全性优先的保守结果，提交前再做一次人工整理。