unsafe 与 checkptr 一起使用时如何定位越界转换

当一段 Go 代码把 unsafe.Pointer 转成结构体指针，或者先做地址偏移再转换，普通测试可能只表现为“偶尔读到异常数据”。定位这类问题的最小配方是：先把输入缩成一个固定长度的切片，再用 go test -gcflags=all=-d=checkptr=2 只跑一个测试。这样通常能把线索收窄到具体的转换表达式，而不是等到后续解引用时才看到模糊的崩溃。

官方资料：https://go.dev/src/cmd/compile/internal/base/debug.go

本文只讨论“转换覆盖的对象比实际分配更大”和“偏移把指针带到无效对象”两类边界，不把 checkptr 当成完整的内存安全证明。

问题：为什么要先把越界转换缩成一个测试

假设一个协议头需要两个 uint64 字段，但输入缓冲区只有 8 个字节。把缓冲区首地址直接转换成 *Header，转换结果覆盖的范围就可能超过原始分配。若代码立即读取字段，错误可能在很远的调用链上才显现；最小测试则把“对象大小”和“转换点”放在同一处。

package checkptrdemo

import (
	"testing"
	"unsafe"
)

type Header struct {
	Magic  uint64
	Length uint64
}

func asHeader(buf []byte) *Header {
	// 这里故意不检查缓冲区长度，用来复现转换覆盖范围过大的问题。
	return (*Header)(unsafe.Pointer(&buf[0]))
}

func TestAsHeader(t *testing.T) {
	// 8 字节不足以容纳两个 uint64 字段组成的 Header。
	buf := make([]byte, 8)
	_ = asHeader(buf)
}

这个例子没有把错误伪装成业务逻辑：buf 的长度、Header 的大小和转换位置都很明确。排查时先复制这种最小形态，再逐步把真实输入和调用方加回来，才能知道到底是长度不足、偏移错误，还是生命周期已经结束。

最小配方：用 checkptr=2 锁定转换表达式

先只跑这个测试：

# -run 只执行目标测试，-count=1 避免复用测试缓存。
go test -gcflags=all=-d=checkptr=2 -run '^TestAsHeader$' -count=1

checkptr 的级别含义是：0 关闭插桩，1 检查涉及 unsafe.Pointer 的转换，2 在此基础上让转换到 unsafe.Pointer 的场景强制堆分配。级别 2 更适合短时间定位问题，但它会改变部分分配行为，所以回归测试不应只依赖这一种构建参数。

如果报错文本包含 converted pointer straddles multiple allocations 或类似的 checkptr 提示，优先回到报错栈中第一处业务代码，查看那一行是否把较小的对象解释成了较大的类型。不要先改成“多申请一些字节”而不写出长度契约，否则下一次输入变化仍会复现。

关键变体：对象大小和地址偏移要分别检查

直接转换和地址偏移是两个不同的边界。直接转换要确认源对象至少容纳目标类型；使用 unsafe.Add 则要同时确认偏移没有超过源对象可访问范围，并确认最终转换类型的大小仍然放得下。

func headerAt(buf []byte, offset int) (*Header, bool) {
	// 先检查偏移和目标对象的总大小，避免把边界检查交给偶然的内存布局。
	if offset  len(buf)-int(unsafe.Sizeof(Header{})) {
		return nil, false
	}

	// 偏移基于同一个源对象，转换后仍然只解释已确认的范围。
	p := unsafe.Add(unsafe.Pointer(&buf[0]), offset)
	return (*Header)(p), true
}

上面的判断用 offset > len(buf)-size 规避了先做 offset+size 可能带来的整数溢出。若允许按容量而不是长度读取，契约也必须明确：调用方不能把尚未写入的容量当成有效协议数据。

另一类常见线索是对齐错误。目标类型包含指针或需要更高对齐时，随意从字节偏移处转换可能触发 misaligned pointer conversion。此时不要用额外填充字节掩盖问题，应该让协议解析按字段读取，或把对齐要求写进布局契约。

完整片段：把修复和回归断言放在一起

真正修复时，转换函数应返回“指针加成功标记”或明确错误，不要返回一个可能越界的指针再让调用方猜测。测试同时覆盖足够长、刚好不足和负偏移三种情况。

func headerAt(buf []byte, offset int) (*Header, error) {
	const size = int(unsafe.Sizeof(Header{}))
	// 先排除负偏移和不足以容纳 Header 的输入。
	if offset  len(buf)-size {
		return nil, fmt.Errorf("header range out of bounds: offset=%d len=%d", offset, len(buf))
	}

	// 只有通过范围检查后，才把地址解释成 Header。
	return (*Header)(unsafe.Add(unsafe.Pointer(&buf[0]), offset)), nil
}

func TestHeaderAtBounds(t *testing.T) {
	// 这个输入足以容纳一个 Header，offset=0 应该成功。
	buf := make([]byte, int(unsafe.Sizeof(Header{})))
	if _, err := headerAt(buf, 0); err != nil {
		t.Fatal(err)
	}

	// 长度不足和负偏移都必须在转换前失败。
	if _, err := headerAt(buf[:len(buf)-1], 0); err == nil {
		t.Fatal("expected short buffer error")
	}
	if _, err := headerAt(buf, -1); err == nil {
		t.Fatal("expected negative offset error")
	}
}

如果真实代码还把指针保存到结构体、跨 goroutine 传递，或把指针转成 uintptr 后再恢复，还要单独检查对象存活和指针生命周期。checkptr 能帮助发现部分非法转换，但不能替代这些契约。

兼容坑：哪些现象不能直接归咎于 checkptr

• 只在某个构建参数下出现：checkptr=2 会影响分配行为，先用它定位，再用普通测试和针对边界的断言确认修复。
• 没有报错不代表安全：检查覆盖的是特定指针转换和算术边界，数据竞争、悬空引用语义、C 侧内存和业务协议错误仍要单独处理。
• 跨平台结果不同：官方发布说明曾特别提示 Windows 上的 checkptr 使用边界；应在目标平台的 CI 中保留一次针对性测试。

相关问题

checkptr=1 和 checkptr=2 该选哪个？先用 1 观察普通转换检查；怀疑分配或生命周期改变掩盖问题时短时使用 2，并把最终回归放回普通测试环境。

为什么我用了 checkptr 仍然没有抓到越界？确认目标代码确实按 -gcflags=all=... 编译，并检查是否属于 checkptr 覆盖范围；对 uintptr 生命周期、C 内存和数据竞争要采用各自的测试手段。

排查这类问题的顺序可以固定为：缩小输入，锁定转换，开启 checkptr，读取第一处业务栈，再把长度、偏移、对齐和生命周期写成显式契约。这样修复的是边界，而不是某一次运行恰好没有崩溃。