Go unsafe.Slice 从 C 缓冲区构造切片时如何限定长度

在 cgo 中拿到一段 C 缓冲区后，最容易写错的地方不是转换语法，而是长度的单位。unsafe.Slice 的第二个参数表示元素数量，不是总字节数；对 []byte 来说两者恰好相等，对 []uint32 或 C 结构体切片则必须先换算。切片本身也不会复制 C 内存，C 缓冲区必须一直有效到最后一次访问。

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

长度参数不是字节数

unsafe.Slice 的形式是 unsafe.Slice(ptr, len)。它从 ptr 指向的第一个元素开始，建立一个长度和容量都为 len 的切片。官方文档把它描述为从指针构造数组视图，因此它没有额外分配，也没有把 C 内存复制到 Go 堆。

假设 C 接口返回 4096 个字节。目标是 []byte 时传入 4096；目标是 []uint32 时只能传入 4096 / 4，并且剩余字节数必须为零。把 4096 直接当成 []uint32 的长度，会让 Go 认为后面还有 4096 个元素，读写范围随之扩大到实际分配之外。

先把 C 缓冲区变成受约束的 []byte 视图

对于字节缓冲区，长度换算最简单，但仍要处理两个边界：非零长度不能配 nil 指针，C 的 size_t 也不能未经检查就转换成 Go 的 int。下面的函数只建立视图，不负责申请内存；它把所有权问题留给调用方。

/*
#include 

// 这里只提供示例用的 C 内存所有者；真实项目应调用已有 C API。
static unsigned char* alloc_buffer(size_t n) {
    return (unsigned char*)calloc(1, n);
}
static void release_buffer(void *p) {
    free(p);
}
*/
import "C"

import (
    "errors"
    "unsafe"
)

func bytesView(p *C.uchar, bytes C.size_t) ([]byte, error) {
    // 非零长度没有可访问的起点，不能交给 unsafe.Slice。
    if p == nil {
        if bytes == 0 {
            return nil, nil
        }
        return nil, errors.New("C buffer is nil but length is non-zero")
    }

    // 先确认 C.size_t 能安全落入 Go 的 int，避免截断长度。
    maxInt := uint64(^uint(0) >> 1)
    if uint64(bytes) > maxInt {
        return nil, errors.New("C buffer is too large for Go int")
    }
    return unsafe.Slice((*byte)(unsafe.Pointer(p)), int(bytes)), nil
}

func consumeCBuffer(p *C.uchar, bytes C.size_t) error {
    // view 只借用 C 内存；消费结束后才释放原始缓冲区。
    view, err := bytesView(p, bytes)
    if err != nil {
        return err
    }
    defer C.release_buffer(unsafe.Pointer(p))

    // 示例只读取视图；真实逻辑可在此处解析 view。
    if len(view) > 0 && view[0] == 0 {
        return nil
    }
    return nil
}

这里的 bytes 是字节数，所以返回类型固定为 []byte。如果 C 接口给出的是元素个数，就不要再除以元素大小；如果给出的是字节数而目标元素大小大于 1，则应先检查整除关系，再传入元素数量。

C 内存的生命周期必须覆盖切片使用期

构造成功不代表数据已经归 Go 管理。view 仍指向 C 的分配区域：不能把它返回给调用方后立刻 C.free，也不能在另一个 goroutine 仍在读取时释放缓冲区。较稳妥的做法是把“建立视图、消费数据、释放 C 内存”放在同一个边界函数里。

如果 C API 规定调用者负责释放，就让负责释放的一侧保持明确；如果 API 返回的是静态区、对象内部字段或由库管理的内存，则按该库的生命周期文档处理，不能看到一个 C 指针就擅自释放。切片的 append 也要谨慎：当容量不够时它可能分配新的 Go 数组，但这并不会替你释放旧的 C 缓冲区。

哪些类型不适合直接映射

把 C 字节区映射成 []byte 通常最直观；映射为更宽的数值或结构体时，还要同时满足大小、对齐、布局和指针规则。尤其不要把含有 Go 指针的类型当作 C 内存元素长期保存，也不要因为两种结构体字段看起来相同就跳过 C 的 padding 和 ABI 差异。

cgo 文档还区分了“指向 Go 分配内存的 Go pointer”和“指向 C 分配内存的 C pointer”。不要用 unsafe 绕过这些规则，把 Go 指针塞进 C 内存，或让 C 保存本不该保存的 Go 指针；这类错误可能表现为偶发崩溃和内存破坏，而不是稳定的编译错误。

常见问题

nil 指针和零长度能不能一起传？

可以。官方约定是 unsafe.Slice(nil, 0) 返回 nil；但 nil 指针配非零长度会 panic。业务代码仍建议在入口显式判断，让错误更容易定位。

切片的 cap 能不能大于传入长度？

不能由 unsafe.Slice 直接得到。它返回的长度和容量都是传入的元素数；需要受限容量时，应在明确仍处于同一分配对象范围内的前提下再做切片表达式。

把 C 缓冲区转成 []byte 会发生复制吗？

不会。它只是建立 Go 切片描述符，读写仍作用于原 C 内存。若需要独立生命周期，应显式 append([]byte(nil), view...) 复制后再释放 C 缓冲区。

最实用的检查清单是什么？

依次确认元素单位、非空指针、int 范围、整除关系、对齐和布局、C 内存所有者、释放时机，以及切片是否逃逸到释放之后。任何一项说不清，就先复制数据，不要急着使用 unsafe.Slice。