Golang在API设计中选择指针还是值类型_技术教程

优先接收T，除非结构体大或需修改原值；返回值同理，仅当需表达“无值”或避免大对象复制时用T；JSON字段用string仅当需区分“未提供”与“空字符串”。

接收参数时用 `*T` 还是 `T`？看是否需要修改原值

Go 函数参数是值传递，传 T 会复制整个结构体；传 *T 只复制指针（8 字节），且能修改调用方的原始数据。API 处理函数（如 HTTP handler）通常不希望副作用，所以多数情况应接收 T —— 尤其是小结构体（如 type User struct { ID int; Name string }）。只有明确需要就地更新字段（比如解析请求后填充默认值并复用该实例），才考虑接收 *T。

接收 *T 时，调用方必须确保传入非 nil 指针，否则运行时报 panic: runtime error: invalid memory address
如果结构体含 sync.Mutex 或其他不可拷贝字段，编译器会强制你用 *T（因为 T 无法赋值）
JSON 反序列化常写成 json.Unmarshal(data, &v)，这里 &v 是惯用法，不是 API 设计偏好 —— 它本质是为让 Unmarshal 能写入内存

返回值用 `*T` 还是 `T`？优先 `T`，除非对象大或需区分零值

返回 T 更安全：调用方无需检查 nil，也不用担心悬空指针。但两种场景适合返回 *T：

结构体较大（比如超过 64 字节），避免复制开销（可通过 go tool compile -S yourfile.go 查看是否逃逸）
需要表达“无值”语义，例如查找失败时返回 nil（*User 可为 nil，User 不行）
类型实现了接口，且需保持方法集一致（比如 io.Reader 的实现通常以指针形式返回）

注意：不要为“看起来更像 OOP”而盲目返回指针 —— Go 的 func (T) Method() 和 func (*T) Method() 方法集不同，混用易导致接口实现意外丢失。

在 JSON API 中，struct 字段该用 `*string` 还是 `string`？按语义决定

这是最常被误用的点。用 *string 的唯一合理理由是：要区分「字段未提供」和「字段显式设为空字符串」。例如 PATCH 请求中，只更新部分字段：

type UpdateUserRequest struct {
    Name *string `json:"name,omitempty"`
    Age  *int    `json:"age,omitempty"`
}

这样你能判断：req.Name == nil 表示客户端没传 name，跳过更新；*req.Name == "" 表示客户端传了空字符串，要清空名字。

若业务上「空字符串」和「未提供」等价，一律用 string —— 简单、高效、不易出错
*string 会增加 GC 压力（每次解析都 new 一个 string），且 JSON 序列化时对 nil 指针输出 null，前端可能未适配
切勿对所有字段无脑加 *：比如 ID uint64 绝对不该是 *uint64，因为 ID 不可能“未提供却合法”

嵌套结构体字段要不要用指针？看是否允许为 nil

嵌套时是否用指针，取决于该子结构在业务逻辑中能否合法为 nil。例如：

type Order struct {
    ID     uint64 `json:"id"`
    User   *User  `json:"user,omitempty"` // 订单可暂无绑定用户
    Items  []Item `json:"items"`
}

type User struct {
    ID   uint64 `json:"id"`
    Name string `json:"name"`
}

这里 User 用指针，是因为订单创建初期可能尚未关联用户；而 Items 是切片（引用类型），天然支持空值，没必要包一层 *[]Item。