go fix inline 分析器识别内联建议的条件

我第一次把 go fix -inline ./... 放进迁移分支时，最容易误解的是“inline”这个词：它不是让编译器在机器码层面自动内联，而是根据源码里的 //go:fix inline 标记，把旧入口的调用改写成新表达式。真正决定它是否提出建议的，是声明形态、替换是否安全，以及调用是否属于测试保护范围。

官方资料：https://go.dev/gopls/analyzers

这篇文章只讨论 inline 分析器的识别条件和工程取舍。我的建议是先用 -diff 看替换范围，确认迁移语义后再落盘；不要把它和编译器优化开关混为一谈。

一、先看 inline 建议从哪里来

inline 分析器依赖一个很具体的信号：声明前出现单独的 //go:fix inline 注释。它支持三类迁移入口：函数、命名常量和类型别名。运行 go fix -inline ./... 时，工具会遍历匹配到的包，寻找这些标记对应的引用。

这个机制适合“旧 API 仍然能工作，但希望调用方逐步迁移”的场景。例如旧函数可以保留一段时间，内部只转发到新函数；工具负责把调用点改成新函数，开发者再通过代码审查确认变更。

package legacy

import "example.com/mathx"

// Deprecated: 请改用 mathx.Pow(x, 2)。
// go fix inline 让迁移工具识别这个兼容入口。
//go:fix inline
func Square(x int) int { return mathx.Pow(x, 2) }

上面的注释示例表达的是“调用替换”，不是性能承诺。函数体如果包含副作用、参数多次求值会改变结果，或者替换后表达式的求值顺序不再等价，就不应该只因为能写出标记而强行迁移。

二、函数条件：替换调用必须能保留原意

函数是最常见的入口。分析器会围绕被标记的函数寻找调用，并尝试把调用替换为函数体表达式。实用上可以把它理解成一层兼容壳：旧函数的参数要能映射到新调用，返回值和错误处理也要继续对应。

package oldapi

import "example.com/newapi"

// Deprecated: 新代码直接使用 newapi.Parse。
// go fix inline 让旧调用具备可迁移的源码指向。
//go:fix inline
func Parse(text string) (newapi.Value, error) {
    // 保持参数只传递一次，避免迁移后改变副作用顺序。
    return newapi.Parse(text)
}

调用方原本写的是 oldapi.Parse(input)，理想的替换结果是 newapi.Parse(input)。如果包装函数需要修改全局状态、记录一次额外日志、重复计算参数，或依赖调用位置才能成立，就把迁移拆成手工改造，不要把 inline 当成万能重构器。

我在实际迁移里会把函数按三个问题筛一遍：新旧参数是否一一对应，返回值是否保持同样的错误边界，函数体是否只是低风险转发。三个问题都能回答“是”，才适合用工具批量推进。

三、常量和类型别名：语法形态比名字更重要

常量的条件更窄：被标记的常量必须引用另一个命名常量。字面量、iota 或一段重新计算的表达式，不属于这种低风险别名迁移。

package oldapi

import "example.com/newapi"

// go fix inline 可以把旧常量迁移到新包的命名常量。
//go:fix inline
const DefaultMode = newapi.DefaultMode

// 这个写法是重新计算字面量，不应当当作常量别名入口。
const RetryCount = 3

类型的判断也类似：只有类型别名才是直接替换关系。type Name = newapi.Name 表示两个名字指向同一个类型；type Name newapi.Name 则创建了一个新定义，方法集、赋值和转换边界都可能不同，不宜自动改成新包类型。

package oldapi

import "example.com/newapi"

// 类型别名保持类型身份，适合做低风险迁移入口。
//go:fix inline
type Name = newapi.Name

所以遇到“标记写了却没有建议”时，先看右侧是不是命名常量、等号是不是类型别名，而不是马上怀疑 go fix 没有扫描到包。

四、哪些调用会被保留下来

分析器特意保留一组测试相关调用。专用测试 TestX、基准 BenchmarkX 和示例 ExampleX 中对符号 X 的使用，不会因为 X 被标记就改掉；如果符号 X 在 foo.go 中声明，那么 foo_test.go 中对它的使用也会保留。

这条边界很有价值：迁移生产调用时，测试仍然可以继续覆盖旧入口本身。若测试也被替换，测试可能只是在验证新函数，旧入口的兼容承诺反而失去了保护。

# 先只查看 inline 分析器将要修改的文件，不直接落盘。
go fix -diff -inline ./...

# 审查 diff 后，再对当前模块的全部包应用替换。
go fix -inline ./...

命令中的 ./... 是包模式，不是文件名通配符。大型仓库可以先缩小到一个模块或子目录，按变更批次提交，这样更容易把“工具替换”与手工修改分开。

五、我会怎样在迁移中选择工具

如果目标是一次性升级标准库写法，直接运行默认的 go fix ./... 更省事；如果只想验证由兼容入口产生的替换，go fix -inline ./... 更可控；如果迁移逻辑不是简单的源码等价替换，手工修改或专用重构工具通常更合适。

我的落地顺序通常是：先在干净分支执行 -diff，按包阅读变更；再跑现有测试和静态检查；最后才提交实际替换。这里的“跑测试”是迁移后的工程动作，不是本文图片或示意图的运行证据。

相关问题

为什么写了标记却没有替换所有调用？

优先检查调用是否位于专用测试、基准、示例或与声明同名的测试文件中；再检查函数是否真的能表达为安全替换，以及常量和类型是否满足各自的声明条件。

go fix inline 会改变编译器的机器码内联吗？

不会。它是源码级迁移分析器，目标是修改调用表达式；编译器是否在生成代码时做优化，是另一套机制。

应该直接运行 go fix ./... 吗？

如果想同时采用多个现代化修复器，可以使用默认命令；如果只审查兼容 API 的替换，先单独运行 go fix -diff -inline ./... 更容易控制变更。