Golang中的指针语义与值语义的选择标准 Go语言API设计规范

核心判断标准是是否需修改调用方原始值：需修改、大结构体（>8字节）、实现接口方法时用t；基础类型、小结构体、不可变类型或需隔离副作用时用t；json.unmarshal等需写入内存的必须传t。

什么时候该传 *T 而不是 T

核心判断标准就一条：是否需要在函数内修改调用方的原始值。go 的参数传递永远是值拷贝，T 拷的是整个结构体或数组内容，*T 拷的是指针地址——后者才能让被调函数“触达”原始内存。

常见错误现象：func modify(s MyStruct) { s.Field = 42 } 调用后原变量没变；或者对大结构体（比如含几百字节字段的 struct）频繁传值，CPU 缓存压力明显上升。

• 必须用 *T：要修改字段、重置内部状态、或实现接口方法（如 io.Reader.Read 必须改 []byte 内容）
• 推荐用 *T：结构体大小 > 8 字节（编译器提示 large stack frame），或类型本身设计为“可变实体”（如 sync.Mutex、bytes.Buffer）
• 坚持用 T：基础类型（int、String）、小结构体（比如两个 int 字段）、不可变类型（如 time.Time）、或明确希望隔离副作用（比如配置快照）

json.Unmarshal 为什么总要传 *T

因为 json.Unmarshal 需要把解析出的字段值写进目标变量的内存地址。传 T 会导致解码结果只写进临时拷贝，原变量仍是零值。

典型错误：var u User; json.Unmarshal(data, u) → u 全是零值；正确写法是 json.Unmarshal(data, &u)，即传 *User。

立即学习“go语言免费学习笔记（深入）”；

• 即使 User 是空结构体，也必须传指针——Unmarshal 底层会做 reflect.Value.Elem()，非指针会 panic：panic: reflect: call of reflect.Value.Elem on struct Value
• 如果目标是切片，也要传指针：json.Unmarshal(data, &users)，否则解码后 users 长度仍为 0
• 嵌套结构体字段如果是值类型（如 Profile Profile），且 Profile 本身含指针字段，不传 *User 会导致深层字段解码失败

API 设计中哪些地方不该暴露指针细节

对外暴露的函数签名、结构体字段、返回值，能用值语义就别强行塞指针——这会让调用方误以为“可以安全修改”，或被迫处理 nil 分支。

使用场景：写 SDK、公共库、http handler 输入/输出结构体时，优先考虑值语义。

• 避免导出字段是 *string 或 *int：调用方得先 new(int) 再赋值，还容易忘记判 nil；改用 string + 空字符串语义更清晰
• 构造函数返回值用 T 而非 *T：比如 func NewConfig() Config，除非初始化成本极高（需延迟加载）或必须支持后续修改
• HTTP handler 接收的 JSON body 结构体，字段全用值类型；中间件或存储层才根据需要转指针操作

比较两个结构体时，== 和 reflect.DeepEqual 的陷阱

== 只对所有字段都可比较的结构体有效（不能含 map、func、slice），且对指针字段比的是地址而非内容；reflect.DeepEqual 能深比较，但性能差、且对 nil 指针和空指针行为不一致。

常见错误现象：u1 == u2 panic：invalid operation: u1 == u2 (struct containing []string cannot be compared)；或 reflect.DeepEqual(&u1, &u2) 返回 false，只因其中一个指针字段是 nil，另一个是 &""。

• 结构体含 slice/map/func：必须用 reflect.DeepEqual，但注意它会把 nil slice 和 []int{} 视为不同
• 字段含指针：若业务上认为 *int 的 nil 和 *int{0} 等价，就得手动展开比较，不能依赖 DeepEqual
• 性能敏感路径（如循环内）：提前用 unsafe.Sizeof 或字段哈希缓存比较结果，避免反复反射

指针和值的选择不是语法习惯问题，而是内存所有权和可变性的显式声明。最易被忽略的是：当结构体嵌套了指针字段，且该指针可能为 nil 时，任何基于值语义的假设（比如“字段一定存在”）都会在运行时崩掉。