Go fix unsafefuncs 将 unsafe 指针运算迁移到 unsafe.Add 的处理方法

升级到 Go 1.27 后，我更愿意先用 go fix -diff ./... 看迁移建议，再决定是否写回源码。和把原子操作改成类型封装的 atomictypes 不同，unsafefuncs 只盯着一类旧式指针运算：把 unsafe.Pointer 转成 uintptr 后加偏移，再转回指针。它的目标是让这段关系直接表达为 unsafe.Add，但不会替你证明偏移量正确，也不会替你修复对象生命周期问题。

unsafefuncs 处理的不是所有 unsafe 代码

官方 modernize 文档把这个分析器描述为“用函数调用替换 unsafe 指针运算”。典型输入是 unsafe.Pointer(uintptr(ptr) + uintptr(n))，其中 n 表示从 ptr 起算的字节偏移。它不是检查所有类型转换的安全扫描器，也不会因为代码导入了 unsafe 就强行改写。

旧式指针运算怎样改成 unsafe.Add

迁移前后真正重要的变化不是“少写一次转换”，而是把基址和偏移明确放进同一个操作。下面的示例只表达结构，不代表可以绕过 Go 的指针规则：

package memory

import "unsafe"

func byteAt(base unsafe.Pointer, offset uintptr) unsafe.Pointer {
	// 旧式写法先绕到 uintptr，再把字节偏移加回指针。
	return unsafe.Pointer(uintptr(base) + offset)
}

func byteAtModern(base unsafe.Pointer, offset uintptr) unsafe.Pointer {
	// unsafe.Add 直接表达“基址加字节偏移”，结果仍是 Pointer。
	return unsafe.Add(base, offset)
}

如果项目使用的是带常量偏移的结构体访问，改写后应继续核对偏移是否以字节计量；如果偏移实际来自元素数量，就不能把元素下标直接当作字节数。对于数组、切片或带对齐要求的内存布局，最好把单位转换写在调用方，让审查者能看出它为什么是这个数。

先预览差异，再应用整个模块的修复

go fix 可以对命名包应用修复，-diff 则只输出统一差异并在存在改动时返回非零状态。我的处理顺序是先保持工作区干净，保存预览，再把 diff 中确实属于 unsafefuncs 的改动单独看一遍。

# 先只预览所有包的修复，不直接改写源码。
go fix -diff ./...

# 查看当前工具链注册了哪些 fix 分析器。
go tool fix help

# 复核通过后，才把修复写回模块源码。
go fix ./...

预览阶段可以重点搜 unsafe.Add、uintptr 和文件名。若同一次升级还混入其他 modernizer，建议按提交拆分，避免把不相关的格式或语义变化和指针迁移绑在一起。go fix 的作用是提出并应用工具已知的改写，不是替代代码审查。

迁移后要复核偏移量与生命周期

有三类情况不能看到自动改写就直接合并：

1. 偏移量单位。unsafe.Add 的偏移是字节数；结构体字段偏移、元素索引和序列化协议位置不能混为一谈。
2. 对象生命周期。把指针暂时转成 uintptr 并不能延长对象存活时间。若原代码跨越可能触发回收或移动的边界，应该重新审查整体设计，而不是只接受语法替换。
3. 版本边界。unsafefuncs 属于 Go 1.27 的 go fix modernizer；团队若仍用更早工具链，应先确认命令是否认识该分析器，不能把当前机器的结果当作所有构建机都支持。

最后可以把检查结果写进提交说明：改了哪些表达式、偏移从哪里来、是否有数组或结构体边界、测试覆盖了哪些平台。这样后续升级时，读者看到 unsafe.Add 仍能追溯它的来源和假设。

常见问题

unsafefuncs 会自动修复所有 unsafe.Pointer 转换吗？

不会。它聚焦可识别的指针运算模式；普通类型转换、生命周期问题和业务内存布局仍需人工处理。

可以把 uintptr 偏移直接换成结构体字段偏移吗？

不能直接换。先确认偏移是字节单位，并确认布局、对齐和目标对象与原代码一致。

为什么先运行 go fix -diff？

因为它只展示统一差异，不立即覆盖源码，适合把 unsafefuncs 的改动与其他 modernizer 分开审阅。