Go unsafe限制指针转换的生命周期的设计要点

Go 的 unsafe.Pointer 转换真正难的地方不是“能不能把地址转过去”，而是转换后的值还能不能让对象保持可达。设计原则可以先记住一句：uintptr 是地址整数，不是引用；需要把地址交给底层调用时，尽量在调用表达式里一次完成转换，调用返回后再用 runtime.KeepAlive 明确最后一次使用点。

官方地址：https://pkg.go.dev/unsafe

凡是把 Go 对象地址保存成 uintptr 再等待以后转回指针的写法，都应先改成“直接传参”或“仍保留 Pointer 引用”的方案。

• 地址整数：uintptr 不会让垃圾回收器追踪对象，也不会替对象续命。
• 调用边界：转换出现在底层调用参数中，才能让编译器识别这是一次性传递。
• 最后使用：调用返回后使用 runtime.KeepAlive，把可达性边界写清楚。

先区分 unsafe.Pointer 与 uintptr 的生命周期语义

unsafe.Pointer 仍然具有指针语义，可以在受限规则内转换为其他指针类型；uintptr 则只是整数。它适合打印地址，或作为一次系统调用的临时参数，但单独保存一个地址整数，并不能阻止对象被回收。

因此，下面两段代码的风险不同：第一段把地址整数从对象生命周期中“摘出来”，第二段让转换紧贴调用边界。

var saved uintptr

func remember(buf []byte) {
    if len(buf) == 0 {
        return
    }
    // 这里只保存整数地址，不会替 buf 的底层数组续命。
    saved = uintptr(unsafe.Pointer(&buf[0]))
}

func passOnce(buf []byte) {
    if len(buf) == 0 {
        return
    }
    // 地址转换紧贴调用参数，避免把 uintptr 脱离调用边界。
    nativeRead(uintptr(unsafe.Pointer(&buf[0])), uintptr(len(buf)))
    // 调用返回后明确 buf 的最后一次使用点。
    runtime.KeepAlive(buf)
}

这里的 nativeRead 代表需要地址参数的底层函数。重点不是函数名，而是不要先写 u := uintptr(...)，再把 u 交给后续调用。

uintptr 只适合作为调用边界的临时参数

Go 官方文档允许的特殊模式很窄：当指针转换直接出现在系统调用或汇编实现函数的参数列表中，编译器可以把它视为一次调用期间的临时地址。把转换结果先放进变量，会让这个识别条件消失。

这也解释了为什么“看起来地址没变”不是充分理由。垃圾回收器不会把 uintptr 当成引用更新或追踪；即使整数仍保存着旧地址，对象也可能已经不可达。生产代码里不要把它放入结构体字段、全局缓存、通道或异步任务，等待下一次再转回 unsafe.Pointer。

如果只是对同一对象做小范围偏移，优先考虑 unsafe.Add，不要手动把指针转成整数再加减：

func byteAt(buf []byte, index int) byte {
    if index = len(buf) {
        panic("index out of range") // 先保证偏移仍在同一底层数组内。
    }
    // unsafe.Add 返回 Pointer，避免地址整数长期脱离对象。
    p := unsafe.Add(unsafe.Pointer(&buf[0]), uintptr(index))
    return *(*byte)(p) // 这里只读取已检查范围内的一个字节。
}

unsafe.Add 也不会替你检查业务边界，更不能跨越一个分配对象。偏移量、元素大小和切片长度仍要由调用方负责。

用 runtime.KeepAlive 标出最后一次使用点

当对象带有 finalizer，或其地址被交给可能在函数返回前使用的底层代码时，局部变量在“源码上最后一次出现”之后可能已不再被认为可达。runtime.KeepAlive(x) 的作用是把可达性明确延长到这行，而不是把一个已经失效的 uintptr 变回安全指针。

func writeNative(buf []byte) error {
    if len(buf) == 0 {
        return nil
    }

    // 直接把地址交给底层调用，不把 uintptr 存到局部变量之外。
    err := nativeWrite(uintptr(unsafe.Pointer(&buf[0])), uintptr(len(buf)))
    // nativeWrite 返回后，buf 才到达这里标记的最后使用点。
    runtime.KeepAlive(buf)
    return err
}

如果底层调用有多个返回路径，应把 KeepAlive 放在统一的调用之后，或用一个收尾块保证每条路径都经过它。它只解决过早 finalizer 的问题，不能解决数据竞争、越界和错误的指针转换。

发布前按生命周期清单检查 unsafe 代码

1. 查保存：搜索 uintptr(unsafe.Pointer(...))，确认结果没有写入全局变量、字段、缓存或异步队列。
2. 查边界：需要底层地址时，确认转换直接出现在调用表达式中，且调用不会把该整数再保存到更晚的阶段。
3. 查可达性：调用可能触发系统操作或对象有 finalizer 时，在调用后补 runtime.KeepAlive，并把对象本身作为参数传入。
4. 查范围：使用 unsafe.Add 前先检查索引、元素大小和同一分配对象边界。
5. 查工具：配合 go vet 和必要的 checkptr 运行方式发现部分违规，但工具安静不代表所有 unsafe 逻辑都正确。

这套清单的核心是让“地址存在多久”与“对象必须活多久”对齐。只要两条时间边界不一致，就不要用“当前机器上能跑”作为通过依据。

常见问题

把 unsafe.Pointer 转成 uintptr 后马上转回来可以吗？

只有符合官方列出的受限模式才可以，普通的“先存变量、稍后再转回”并不普遍有效。能在同一个调用表达式内完成，就不要拆开保存。

runtime.KeepAlive 能修复越界指针吗？

不能。KeepAlive 只负责把对象保持可达直到指定位置；越界、错误对齐、跨对象偏移和不符合 Pointer 规则的转换仍然是独立问题。