Go //go:fix inline 怎么处理带副作用的实参

//go:fix inline 遇到带副作用的实参时，不会只做文本替换。Go 的源码级内联器会分析实参、形参使用位置以及函数体中其他表达式之间的依赖；如果不能证明直接替换仍保持原来的求值顺序和次数，就会采用更保守的参数绑定，或者拒绝不适合批量迁移的变换。

迁移的第一目标不是让调用变短，而是保持行为不变。带函数调用、递增、通道接收、map 写入或状态读取的实参，都应先按“可能有副作用”处理。

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

先明确要保护的东西

给旧 API 添加 //go:fix inline 时，真正需要保护的“资产”包括：

• 每个实参被求值的次数；
• 多个实参以及函数体内其他调用的相对求值顺序；
• 短路、分支和循环造成的条件执行或重复执行边界；
• 变量读写、通道操作、日志、计数器和外部 I/O 的可观察行为。

只要迁移让其中一项发生变化，即使新代码能够编译，也可能悄悄改变业务语义。因此，不能把“改名成功”或“测试能启动”当作唯一验收标准。

朴素替换为什么会改变副作用顺序

假设旧包提供一个兼容包装函数，它把参数调换后调用新 API：

package legacy

import "example.com/newcalc"

//go:fix inline
func Join(left, right int) int {
    // 新 API 的参数顺序与旧 API 不同。
    return newcalc.Combine(right, left)
}

调用方把两个有状态函数作为实参：

result := legacy.Join(loadPrimary(), loadFallback())
// loadPrimary 与 loadFallback 都可能更新计数器、缓存或日志。

如果只是把形参替换到函数体中，结果会像下面这样：

result := newcalc.Combine(loadFallback(), loadPrimary())
// 危险：两个调用在源码中的相对顺序已经反转。

旧调用先求值 loadPrimary()，再求值 loadFallback()；朴素结果把顺序反过来了。只要二者共享状态，结果就可能不同。源码级内联器因此会尝试证明重排安全；无法证明时，它会保留必要的绑定，例如先保存早先求值的实参，再构造新调用。

参数绑定如何守住语义边界

工具生成的具体变量名和代码形态可能随上下文变化，但保守结果通常会保留类似下面的语义结构：

var left = loadPrimary()
// 先保存原调用中更早求值的实参，避免后续重排改变副作用顺序。
result := newcalc.Combine(loadFallback(), left)

这里的临时变量不是多余代码，而是一条所有权和顺序边界：loadPrimary() 仍然只执行一次，并且仍然发生在 loadFallback() 之前。官方说明将这类分析称为 hazard analysis，它关注的不只是实参本身，还包括实参与函数体其他表达式的相对位置。

例如，包装函数在两个形参之间调用另一个函数：

//go:fix inline
func Score(first, second int) int {
    // audit 也可能读写与实参函数共享的状态。
    return first + audit() + second
}

即使 first 和 second 在函数体里保持声明顺序，把第二个实参直接替换进去，也可能让它从“进入函数前求值”变成“audit 之后求值”。内联器必须同时考虑这种跨越函数体表达式的风险。

求值次数变化比换序更隐蔽

如果一个形参在函数体中出现多次，直接替换可能让原本只执行一次的实参执行多次：

//go:fix inline
func Duplicate(value int) int {
    // value 被读取两次，但调用方的实参只应求值一次。
    return value + value
}

total := Duplicate(nextSequence())
// nextSequence 每次调用都会推进序号。

错误的文本替换会得到 nextSequence() + nextSequence()，这显然改变了调用次数。安全变换需要先把实参保存到变量，再复用这个变量。循环中的形参更需要警惕：把一次求值的实参搬进循环体，可能把副作用放大成多次。

同样，条件分支也可能把“必定执行”变成“按条件执行”。因此，评估 //go:fix inline 不能只数参数位置，还要检查参数处于普通表达式、分支还是循环中。

风险分级：哪些实参要重点审查

这里的分级用于代码审查排序，不等于工具只处理低风险情况。内联器可能通过显式绑定安全处理复杂实参；反过来，即使实参看起来只是字段读取，也可能被其他实参修改其接收对象，仍需看完整调用上下文。

先看差异，再决定是否批量应用

准备好指令后，先让工具输出差异：

# 先预览当前模块内 go fix 将产生的源码变化，不直接改文件。
go fix -diff ./...

# 确认差异后再应用；提交前仍需运行项目测试。
go fix ./...

审查差异时，重点搜索新引入的 var 参数绑定、函数调用顺序、重复表达式和被展开的控制结构。保守绑定可能不够简洁，但只要语义正确，就不要为了“看起来更短”立即删掉；先确认实参纯净且不存在未来行为变化，再做人工整理。

如果 go fix 拒绝某些调用点，也不要把它当成迁移失败。批量工具会主动回避需要函数文字量化等不适合自动改写的结果。保留旧包装调用，针对这些点人工迁移，通常比强制放宽安全约束更可靠。

用可观察事件测试迁移前后是否一致

对于有副作用的迁移，测试不应只断言最终数值，还应记录事件顺序：

func TestJoinKeepsEvaluationOrder(t *testing.T) {
    var events []string

    primary := func() int {
        // 记录可观察事件，帮助比较迁移前后的求值顺序。
        events = append(events, "primary")
        return 10
    }
    fallback := func() int {
        // 第二个实参应在第一个实参之后求值。
        events = append(events, "fallback")
        return 2
    }

    _ = legacy.Join(primary(), fallback())

    got := strings.Join(events, ",")
    if got != "primary,fallback" {
        t.Fatalf("evaluation order changed: %s", got)
    }
}

应用 go fix 前后运行同一组测试，事件序列和最终结果都应保持一致。若包装函数涉及外部 I/O，可以用可控的假实现记录调用，而不是依赖真实网络或数据库。

迁移验收清单

• 指令放在实际承载兼容语义的旧声明上，函数体足够小且意图清楚；
• 先运行 go fix -diff，没有直接在大范围代码上盲改；
• 逐项检查带调用、状态读取、通道操作或计数变化的实参；
• 确认参数绑定保留了原求值顺序和一次求值语义；
• 检查形参是否进入循环、条件、其他函数调用或重复使用位置；
• 迁移前后运行单元测试、静态检查和构建，并保留可回滚提交；
• 工具拒绝的调用点单独处理，不通过不安全选项强行批量改写。

结论

//go:fix inline 对副作用实参的核心策略是“能证明才直接替换，不能证明就保留绑定”。源码级内联器会保护实参求值顺序、次数以及它们与函数体其他表达式之间的关系。库作者应把包装函数写得清楚，使用 go fix -diff 审查保守变换，并用事件顺序测试验收；这样才能让 API 迁移既自动化，又不牺牲行为一致性。