[!info] Related notes

• 所属 MOC：高级运行时 · 学习路线
• 前置：指针、转换与可赋值、内存模型
• 相关：cgo、反射、slice/map 实现、逃逸分析
• 工程：静态分析、性能方法论

Go unsafe 包

这个概念为什么出现

Go 的类型系统与 GC 假设协作：普通 *T 不能任意变成 *U，也不能把整数当指针随便解引用。这换来内存安全与可演进的运行时。

但极少数场景需要“有文档约束的逃脱口”：

• 与 C 或操作系统 ABI 对齐的结构布局
• 高性能序列化/哈希中的受控别名
• 标准库内部实现（sync/atomic、reflect、字符串与字节切片转换等）
• 驱动、嵌入式、研究工具

unsafe 把危险集中到显式导入的包，便于审计。默认业务代码不应依赖它。

[!abstract] 一句话理解 unsafe 提供绕过 Go 类型保护的能力；unsafe.Pointer 仅在文档列出的合法模式内使用，否则可能破坏 GC、引入悬空指针并在未来编译器下崩溃。

最小可运行示例

先把示例放进调试互操作 / 理解成本场景，再看代码：

场景：核对 ABI 布局时用 Sizeof/Offsetof（默认业务禁用）

对接 C 结构、内核 ioctl、或二进制协议时，工程师需要确认「字段偏移 / 对齐 / 整结构体大小」是否与对端一致。
unsafe.Sizeof / Alignof / Offsetof 用于观察 Go 值的布局；参数类型无可变大小时结果是常量，含类型参数时不一定。它们不能单独证明布局符合某个 C ABI 或线协议。 默认业务代码不应依赖 unsafe；这里只演示「为什么要懂成本」与合法 Pointer 模式的形状。警告保留：误用可破坏 GC 语义。

package main

import (
	"fmt"
	"unsafe"
)

// point：模拟与外部 ABI 对齐的简单结构（真实场景可能是 C 结构镜像）。
// 警告：字段顺序/填充随 GOARCH 与对齐规则变化；跨平台勿硬编码数字。
type point struct {
	X int32
	Y int32
}

func main() {
	// --- 实验 A：量尺寸（理解互操作成本的第一步）---
	fmt.Println("size:", unsafe.Sizeof(point{}))
	fmt.Println("align:", unsafe.Alignof(point{}))
	fmt.Println("offset Y:", unsafe.Offsetof(point{}.Y))

	// --- 实验 B：合法模式示意 —— *T → Pointer → 算术 → *U ---
	// 业务意图：在已知布局下读取 Y 字段（类似手写偏移访问）。
	// 硬约束：Pointer↔uintptr 算术必须在同一表达式完成，避免 uintptr 临时值不保活对象。
	var p point
	p.X, p.Y = 3, 4
	yp := (*int32)(unsafe.Pointer(uintptr(unsafe.Pointer(&p)) + unsafe.Offsetof(p.Y)))
	fmt.Println(*yp) // 期望：4
}

保存为 main.go 后运行：

go run main.go

Go 1.26.8 的 linux/amd64 与 linux/386 下该结构输出如下；其他布局应以目标架构验证。int32 本身固定为 32 位，对齐与填充需要另外确认：

size: 8
align: 4
offset Y: 4
4

警告：

1. 本例的 uintptr 算术需在同一表达式内完成，结果仍须位于同一已分配对象内；写在同一表达式不是任意转换合法的充分条件。
2. 完整合法模式以 unsafe.Pointer 原文为准。
3. 生产路径优先 encoding/binary、binary.Append、生成代码或 cgo 绑定，而不是手写偏移。

仅在已证明需要零拷贝且能维护不变量时考虑以下 API：unsafe.Add / Slice 自 Go 1.17 提供，unsafe.String / StringData / SliceData 自 Go 1.20 提供；它们仍是 unsafe，不是安全转换的替代默认值。

// 仅示意：务必阅读当前 go 版本 unsafe 文档与 release notes
b := []byte("hi")
s := unsafe.String(unsafe.SliceData(b), len(b)) // 空切片也不索引 b[0]；s 使用期间不可改底层字节
_ = s

这里创建的是别名，不会复制字节；不能在字符串仍被使用时把 buffer 交回可重写的池。反方向从 StringData 得到的内存也不能修改。unsafe.String(nil, 0) 得到空字符串；unsafe.StringData("") 的返回值未指定，可能为 nil，不可解引用。

结合场景再看关注点

1. 场景是调试/互操作/成本理解，不是日常业务捷径。
2. Sizeof 量的是头/类型本身，不是 slice 底层数组总长。
3. 违规模式可能“本地能跑、升级后炸”——规则比样例输出更重要。

核心模型

包提供什么

见 pkg.go.dev/unsafe：

API	作用
Pointer	特殊指针类型，可在规则下与普通指针、uintptr 转换
Sizeof(x)	x 的大小（字节）
Alignof(x)	对齐要求
Offsetof(f)	结构体字段偏移
Add / Slice / String 等	较新版本提供的受控辅助（以当前文档为准）

六大（文档）Pointer 规则——必须读原文

官方在 unsafe.Pointer 列出合法模式。教学浓缩（以原文为准，版本会增补）：

1. *T1 → Pointer → *T2：重新解释值；T2 不大于 T1，二者须有等价内存布局，并满足访问所需对齐等条件。
2. Pointer → uintptr（不能任意转回）：得到地址整数，例如用于打印；它不保活对象，也不会随对象移动而更新。
3. Pointer → uintptr → 算术 → Pointer：转换在同一表达式内完成，结果仍在原已分配对象内；nil 与越过末尾的 one-past-end 指针不符合该模式。unsafe.Add 也保留这些约束。
4. syscall 等特定调用的 uintptr 参数：转换须直接出现在调用参数表达式内，编译器才能按文档识别并保持对象到调用完成；普通 Go 函数接收 uintptr 并不自动获得这个保证。
5. reflect.Value.Pointer / UnsafeAddr 的结果立即转为 Pointer：在同一表达式中转回，不能把返回的 uintptr 存下再转换。
6. 实际 slice/string 的 Header.Data 转换：历史模式只能让 *reflect.SliceHeader / *reflect.StringHeader 指向真实 slice/string 值；不能单独声明 Header 再伪造值。现代代码优先考虑上面的专用 unsafe API。

flowchart LR
    T["*T"] <--> P["unsafe.Pointer"]
    P <--> U["*U"]
    P --> X["uintptr<br/>非指针！"]
    X -->|"仅文档允许的受限模式"| P

与 GC 的核心冲突

GC 跟踪指针类型字段与栈上指针。uintptr 是整数：

• 对象可能被回收或移动（若实现移动；目前许多对象不移动，但规则仍按“uintptr 不保活”写）
• 你拿着过期整数当指针 = 内存破坏

因此：uintptr 数字不保活对象。 runtime.KeepAlive 可影响可达性，但不会把原本不合法的“存 uintptr 后再转回”变成合法模式；栈移动、指针更新与布局约束仍然存在。

Sizeof 的边界

• Sizeof 测值本身的大小：slice 是描述符，map/channel 是引用值，接口是接口值；都不包含被引用的底层数据。
• 含指针字段的结构体大小不含堆上指向的对象。

规范 vs 实现分界

包契约	不能据此推出
按文档模式转换 Pointer	任意地址重解释或任意跨对象指针算术合法
Sizeof/Alignof/Offsetof 测当前 Go 布局	与另一语言 ABI、网络编码或所有架构布局一致
unsafe API 有明确使用约束	使用 unsafe 的程序受 Go 1 兼容性承诺保护
vet / checkptr 可发现部分问题	工具通过即证明所有生命周期和布局都正确

语言规范把 unsafe 单独拿出；可移植与安全的 Go 程序可以完全不用它。

边界

1. 可移植性
   字长、对齐、端序、结构体填充随 GOOS/GOARCH 变。

2. 向前兼容
   编译器更强优化后，曾经“碰巧能跑”的非法模式可能炸。

3. 工具覆盖不全
   go vet、-race 与 -gcflags=all=-d=checkptr=2 可辅助检查，但不能证明所有 unsafe 用法正确。

4. 与 cgo
   传递指针给 C 有 cgo 指针规则（是否把 Go 指针传入 C、是否在 C 持有等）。见 cgo。

5. 安全审计
   任何 import "unsafe" 都应触发代码评审额外门槛。

常见误区

[!warning] 把 uintptr 存进结构体当“智能指针” GC 不保活；这是经典 use-after-free 写法。

[!warning] 用 unsafe 把 []byte 转 string 后仍修改底层字节 若 string 假设不可变，修改会导致诡异的 map 键/哈希/竞态问题。

[!warning] 认为 Sizeof(slice) 是数据长度 那是头大小；数据长度用 len。

[!warning] 复制网上“绕过逃逸/零拷贝”片段却不读规则 多数片段违反同一表达式规则或生命周期规则。

[!warning] 为微优化在业务域大量引入 unsafe 先证明热点；多数情况下算法、分配次数、I/O 更重要。

工程实践

1. 默认禁止
   可按团队需要限制业务 package 使用 unsafe，并要求有依据的例外审查；这是一种策略建议，不是 Go 语言要求或已存在的本仓库规则。

2. 优先安全替代

   • 编码：encoding/binary、显式字段
   • 泛型/反射
   • strings.Builder、bytes
   • 需要独立值时用普通 string(b) / []byte(s) 转换；是否消除分配由编译器在不改变安全语义的前提下决定

3. 必须用时

   • 注释写清：合法模式编号、不变量、生命周期
   • 表驱动测试覆盖对齐/大小
   • 多 GOARCH 测试（至少 amd64/arm64）
   • 尽量把 unsafe 关在最小文件/函数

4. 不要用 unsafe 读私有 runtime 堆结构做生产逻辑
   分配器、hmap、iface 布局都是实现。

5. 安全更新
   升级 Go 版本时全文搜索 unsafe. 回归。

可验证实验

2026-10-07 使用 Go 1.26.8：主示例在 linux/amd64 与 linux/386 下启用 checkptr 通过；另核验 Add、反射即时转换、空 String/Slice 和 Sizeof。泛型 Sizeof 不能作常量的反例编译失败，分离 uintptr 往返的反例触发 vet 诊断（未执行非法解引用）。工具通过不构成通用安全证明。

实验 A：Offsetof 与字段读写

定义 struct，用 Offsetof 写第二字段，与正常字段写入对比。

实验 B：错误存 uintptr（危险，仅本地玩具）

对比：

// 错误模式示意——不要用于生产
u := uintptr(unsafe.Pointer(new([1024]byte)))
// runtime.GC(); 再转回指针使用 —— 可能坏

与直接保留 *T、访问时按文档模式转换的写法对照；仅添加 KeepAlive 不会修复分离的 uintptr 往返转换。可用 vet 检查反例，无需实际解引用非法地址。

实验 C：Sizeof 头 vs 数据

对 []int{1,2,3} 打印 unsafe.Sizeof(s)、len、cap，建立直觉。

本节总结

• unsafe 是显式的类型系统逃脱口；能力与责任对等。
• 只使用 unsafe.Pointer 文档 列出的模式。
• uintptr 不保活对象；算术必须极度小心。
• 工程默认不用；必须用时最小化、测全、可审计。

自测题

1. 为什么 uintptr 不能当指针长期保存？
2. *T -> Pointer -> *U 合法时，程序员还要保证什么？
3. unsafe.Sizeof([]byte{}) 大致反映什么？
4. 业务代码想“零拷贝 string/[]byte”，优先查什么？
5. 升级 Go 大版本时对 unsafe 代码应做什么？

参考答案

1. 它是整数，GC 不把它视为引用，对象可能被回收，数字变成悬空地址。
2. 目标类型对那块内存的读法/对齐/大小合法，且对象生命周期仍覆盖访问。
3. slice 头的大小，不是底层数组字节数。
4. 先使用普通安全转换并测量；专用 unsafe API 仍要求遵守布局、不可变与生命周期约束，不能称为“半安全”。
5. 全文检索、对照最新 Pointer 规则、重跑测试与 race/多架构 CI。

延伸阅读

• unsafe package
• unsafe.Pointer rules
• Go Spec — Package unsafe
• Go Memory Model
• cgo documentation — 与 C 交换指针时的额外规则
• Go 1 release notes — 检索 unsafe.String / Slice 等变更
• reflect package — 多数场景的安全替代观察手段