Go fix unsafefuncs 怎样在迁移函数指针转换（输入边界）

如果代码里还出现 unsafe.Pointer(uintptr(ptr) + uintptr(n)) 这样的指针算术，Go 1.27 的 go fix 可以通过 unsafefuncs 将可识别的表达式改写为 unsafe.Add(ptr, n)。标题里的“函数指针转换”需要先校正：这里不是把 Go 函数值变成函数指针，而是把旧式指针算术转换成更清楚的函数调用。

最稳妥的入口是先在干净分支运行 go fix -diff -unsafefuncs ./...，只查看这一个 modernizer 提议的差异；确认偏移量、对象边界和兼容性后，再应用同一项改写。

unsafefuncs 负责表达式现代化，不负责证明 unsafe 代码整体正确。它把已识别的指针算术换成 unsafe.Add，仍然需要人工确认 ptr 与偏移量指向同一分配对象的合法范围，并继续检查指针生命周期。

unsafefuncs 真正迁移的是什么

Go 1.27 的发布说明把 unsafefuncs 列为 go fix 新增 modernizer。官方 modernize 文档给出的典型输入是把一个 unsafe.Pointer 转成 uintptr 后加上偏移，再转回指针；输出是调用 Go 1.17 引入的 unsafe.Add。因此，不能把它理解成“所有包含 unsafe 的代码都会自动变安全”。

package packet

import "unsafe"

// byteAt 展示待迁移的旧式指针算术：offset 是相对同一对象的字节偏移。
func byteAt(base unsafe.Pointer, offset uintptr) *byte {
	// 这类表达式是 unsafefuncs 关注的输入形态。
	return (*byte)(unsafe.Pointer(uintptr(base) + offset))
}

// byteAtModern 使用函数调用表达同一个偏移关系，调用方仍需保证范围合法。
func byteAtModern(base unsafe.Pointer, offset uintptr) *byte {
	// unsafe.Add 不替调用方检查 offset 是否落在有效对象内。
	return (*byte)(unsafe.Add(base, offset))
}

上面的两段只说明静态对应关系，不代表某次命令已经执行。左侧是“指针—整数—指针”的表达式链，右侧把偏移动作集中到 unsafe.Add。语义边界仍由分配对象、偏移量和使用时机决定。

先用 -diff 锁定改动范围

go fix 是源码改写工具，默认运行一组可用的 modernizer。本文只指定 -unsafefuncs，让代码审查可以把注意力集中在 unsafe 指针算术这一类变化上。

# 先只预览 unsafefuncs，不直接修改工作区。
go fix -diff -unsafefuncs ./...

# 确认差异、模块版本和构建范围后，再应用同一个 modernizer。
go fix -unsafefuncs ./...

# 查看当前工具链登记的 fixer 名称与帮助信息。
go tool fix help unsafefuncs

如果 -diff 没有输出，通常表示当前构建配置下没有匹配表达式，并不等于所有 unsafe 代码都已经审查完成。带构建标签、不同 GOOS 或 GOARCH 的文件，可能需要在对应配置中单独阅读。若预览中混入其它 modernizer 的改动，先收窄命令或恢复到干净分支，不要把多个重构混成一次难以回看的差异。

读懂“指针算术到函数调用”的边界

unsafe.Add(ptr, n) 的第一个参数是 unsafe.Pointer，第二个参数是字节偏移。它适合表达“从这个指针沿同一对象移动 n 个字节”，但不会替你验证结构体字段、切片底层数组或 mmap 区域的布局。

package record

import "unsafe"

// Header 保存固定布局数据；偏移量必须与实际布局约定保持一致。
type Header struct {
	Kind  uint16
	Flags uint16
}

// flagsPtr 返回同一 Header 对象中的 Flags 地址，避免手写整数加法。
func flagsPtr(h *Header) *uint16 {
	// unsafe.Offsetof 只计算编译期字段偏移，仍要求 h 指向有效 Header。
	base := unsafe.Pointer(h)
	return (*uint16)(unsafe.Add(base, unsafe.Offsetof(h.Flags)))
}

这个例子中，unsafe.Offsetof 给出字段相对结构体起点的偏移，unsafe.Add 表达从 h 移动到该字段。真正的风险不在函数名更换，而在 h 是否仍指向有效对象、偏移是否属于该对象，以及结果是否在使用前保持可达。

迁移后要人工复核哪些问题

第一，看偏移量的单位。unsafe.Add 按字节移动，不是按元素个数移动；如果旧代码的 n 代表元素下标，迁移前就必须确认它已经乘过元素大小，不能因为新函数看起来更安全就省略这个判断。

第二，看对象边界。结果指针应当落在同一分配对象内，或落在允许的边界位置；把一个整数地址当成任意可访问对象、跨越不相关分配或依赖未声明的布局，都不是 modernizer 能修复的事情。

第三，看生命周期。若指针来自短生命周期对象、系统调用、切片或 cgo 交界，改写表达式不会自动延长对象存活时间。确实需要时，按官方 runtime.KeepAlive 的语义把保持可达放在最后一次使用之后，并重新审查 cgo 与非 cgo 的规则。

第四，看兼容版本。unsafe.Add 从 Go 1.17 起可用，但项目仍可能需要支持更老的工具链或维护生成代码；这种情况下应把模块版本、构建矩阵和发布分支一起纳入决策，而不是只看本机能否格式化。

应用后的收尾清单

完成复核后，再运行项目自己的构建和测试流程，查看 Git diff 并提交。go fix 只负责提出或应用源码重写，不替代对 unsafe 代码的内存模型审查。

官方资料：https://go.dev/doc/go1.27、https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/modernize#hdr-Analyzer_unsafefuncs、https://pkg.go.dev/unsafe#Add、https://pkg.go.dev/runtime#KeepAlive

常见问题

unsafefuncs 会把所有 uintptr 转换都改成 unsafe.Add 吗？

不会。它针对可识别的 unsafe 指针算术表达式；任意整数转指针、动态地址计算和不明确的对象关系仍需要人工判断。

为什么要先运行 -diff？

因为 go fix 会改写源码。先看差异能确认命令范围、偏移单位、构建配置和兼容性，再决定是否把结果应用到工作区。

unsafe.Add 是否自动保证指针安全？

不是。它只把偏移动作表达成函数调用；对象边界、生命周期、布局和 cgo 约束仍由代码作者负责。