CGo调用指南

约 1884 字大约 6 分钟

gocgoc

2025-04-25

概述

CGo是Go与C语言之间的桥接机制，允许Go代码直接调用C库函数，也允许C代码回调Go函数。虽然CGo功能强大，但它引入了额外的复杂性和性能开销。本文将详解CGo的使用方法、类型映射、内存管理、回调机制、性能考量以及何时应该避免使用CGo。

基本用法

package main

/*
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

// 也可以直接写C代码
int add(int a, int b) {
    return a + b;
}
*/
import "C" // 注意：import "C" 必须紧跟注释块，不能有空行

import (
    "fmt"
    "unsafe"
)

func main() {
    // 调用C函数
    result := C.add(3, 5)
    fmt.Println("3 + 5 =", result) // 8

    // 调用标准库函数
    cs := C.CString("Hello from C")
    defer C.free(unsafe.Pointer(cs))
    C.puts(cs)
}

类型映射

基本类型映射

// C类型              → Go类型
// char               → C.char     (int8)
// signed char        → C.schar    (int8)
// unsigned char      → C.uchar    (uint8)
// short              → C.short    (int16)
// unsigned short     → C.ushort   (uint16)
// int                → C.int      (int32)
// unsigned int       → C.uint     (uint32)
// long               → C.long     (int32 or int64)
// unsigned long      → C.ulong    (uint32 or uint64)
// long long          → C.longlong (int64)
// float              → C.float    (float32)
// double             → C.double   (float64)
// void*              → unsafe.Pointer
// size_t             → C.size_t

// 使用时需要显式类型转换
var goInt int = 42
var cInt C.int = C.int(goInt)
var backToGo int = int(cInt)

指针类型

// C指针 → Go中的C指针类型
// int*    → *C.int
// char*   → *C.char
// void*   → unsafe.Pointer

// 结构体指针
/*
typedef struct {
    int x;
    int y;
} Point;
*/
import "C"

func usePoint() {
    var p C.Point
    p.x = 10
    p.y = 20
    fmt.Printf("Point: (%d, %d)\n", p.x, p.y)
}

字符串转换

// Go string → C string (需要手动释放!)
goStr := "Hello, CGo"
cStr := C.CString(goStr) // 分配C内存，复制数据
defer C.free(unsafe.Pointer(cStr))

// C string → Go string
goStr2 := C.GoString(cStr) // 分配Go内存，复制数据

// C string with length → Go string
goStr3 := C.GoStringN(cStr, C.int(len(goStr)))

// Go []byte → C *char
goBytes := []byte("hello")
cPtr := (*C.char)(unsafe.Pointer(&goBytes[0]))
// 注意：goBytes必须保持引用，否则可能被GC回收

// C memory → Go []byte
goBytes2 := C.GoBytes(unsafe.Pointer(cPtr), C.int(5))

内存管理

CGo中最容易出错的地方是内存管理：

// 规则1：C.CString分配的内存必须手动free
func correctUsage() {
    cs := C.CString("hello")
    defer C.free(unsafe.Pointer(cs)) // 必须释放
    C.puts(cs)
}

// 规则2：不能将Go指针传递给C并长期持有
// Go的GC可能移动Go对象，导致C持有的指针失效

/*
// 这是危险的！
void store_ptr(void* p) {
    global_ptr = p;  // C持有Go指针 → 未定义行为
}
*/

// 规则3：Go指针指向的内存中不能包含Go指针
// （Go 1.17+ 有所放宽，参见 runtime/cgo）

// 正确做法：使用C内存传递数据
func safePass() {
    data := []byte("important data")
    cData := C.CBytes(data) // 复制到C堆
    defer C.free(cData)
    C.process_data((*C.char)(cData), C.int(len(data)))
}

cgo.Handle（Go 1.17+）

import "runtime/cgo"

// 安全地将Go值传递给C
func registerCallback() {
    handler := func(msg string) {
        fmt.Println("Received:", msg)
    }

    h := cgo.NewHandle(handler) // 创建handle
    defer h.Delete()             // 使用完毕后删除

    // 将handle作为uintptr传给C
    C.register_callback(C.uintptr_t(h))
}

// C端通过handle回调Go
//export goCallback
func goCallback(h C.uintptr_t, msg *C.char) {
    fn := cgo.Handle(h).Value().(func(string))
    fn(C.GoString(msg))
}

Go回调（export）

/*
#include <stdlib.h>

// 声明Go导出的函数
extern int goAdd(int a, int b);
extern void goLog(char* msg);

// C函数调用Go回调
int callGoAdd(int a, int b) {
    return goAdd(a, b);
}
*/
import "C"

//export goAdd
func goAdd(a, b C.int) C.int {
    return a + b
}

//export goLog
func goLog(msg *C.char) {
    fmt.Println("Go log:", C.GoString(msg))
}

func main() {
    result := C.callGoAdd(10, 20)
    fmt.Println("Result:", result) // 30
}

构建标志

// #cgo 指令控制C编译器和链接器的标志

/*
#cgo CFLAGS: -I/usr/local/include -DDEBUG
#cgo LDFLAGS: -L/usr/local/lib -lssl -lcrypto
#cgo pkg-config: libxml-2.0

// 平台特定标志
#cgo linux LDFLAGS: -lrt
#cgo darwin LDFLAGS: -framework Security
#cgo windows LDFLAGS: -lws2_32

// 使用pkg-config
#cgo pkg-config: sqlite3
*/
import "C"

性能开销

CGo调用有显著的性能开销：

// 纯Go函数调用：~1-2 ns
// CGo函数调用：~50-100 ns（约50-100倍开销）

// 开销来源：
// 1. goroutine栈 → 系统线程栈的切换
// 2. Go调度器需要标记当前M为syscall状态
// 3. C函数不支持Go的抢占式调度
// 4. 可能需要数据类型转换和内存拷贝

减少开销的技巧

// 1. 批量操作：一次CGo调用处理多条数据
// 而不是多次CGo调用每次处理一条

// 差：每个元素一次CGo调用
for _, v := range data {
    C.process_one(C.int(v))
}

// 好：一次CGo调用处理所有数据
cData := (*C.int)(unsafe.Pointer(&data[0]))
C.process_batch(cData, C.int(len(data)))

// 2. 使用unsafe直接操作C内存，避免多余拷贝
// 3. 考虑缓存C分配的内存，避免频繁malloc/free

CGo的替代方案

在决定使用CGo之前，考虑以下替代方案：

// 1. 纯Go实现
// 许多C库已经有纯Go替代品
// modernc.org/sqlite → 纯Go的SQLite
// github.com/pion/webrtc → 纯Go的WebRTC

// 2. 通过子进程/IPC调用
// 启动C程序作为子进程，通过stdin/stdout通信
cmd := exec.Command("./c-program", args...)
output, err := cmd.Output()

// 3. 通过网络协议调用
// 将C服务封装为gRPC/HTTP服务

// 4. 使用syscall直接调用系统API
// 不需要CGo就能调用操作系统功能
syscall.Open(path, syscall.O_RDONLY, 0)

// 5. 使用purego（纯Go的dlopen）
// github.com/ebitengine/purego
// 无需CGo即可调用动态库

CGo的限制

// 1. 交叉编译困难（需要目标平台的C工具链）
// 2. 构建速度变慢
// 3. 静态链接复杂度增加
// 4. 不支持Go的竞态检测器（race detector可能误报）
// 5. 增加二进制大小
// 6. 使Go的内存安全保证失效
// 7. 调试更困难（需要同时调试Go和C）

实际案例：封装SQLite

/*
#cgo LDFLAGS: -lsqlite3
#include <sqlite3.h>
#include <stdlib.h>
*/
import "C"

type DB struct {
    db *C.sqlite3
}

func Open(path string) (*DB, error) {
    cPath := C.CString(path)
    defer C.free(unsafe.Pointer(cPath))

    var db *C.sqlite3
    rc := C.sqlite3_open(cPath, &db)
    if rc != C.SQLITE_OK {
        errMsg := C.GoString(C.sqlite3_errmsg(db))
        C.sqlite3_close(db)
        return nil, fmt.Errorf("sqlite3_open: %s", errMsg)
    }
    return &DB{db: db}, nil
}

func (d *DB) Close() error {
    if rc := C.sqlite3_close(d.db); rc != C.SQLITE_OK {
        return fmt.Errorf("sqlite3_close: code %d", rc)
    }
    d.db = nil
    return nil
}

总结

特性	说明
调用开销	~50-100ns/次，比纯Go慢50-100倍
内存管理	C.CString需手动free，不能长期持有Go指针
回调	//export导出Go函数供C调用
构建标志	#cgo CFLAGS/LDFLAGS/pkg-config
替代方案	纯Go库、子进程、purego
适用场景	必须使用的C库、系统级API

CGo是一把双刃剑。它提供了与C生态系统互操作的能力，但也带来了性能开销、复杂性和安全风险。遵循"如果能用纯Go实现就不用CGo"的原则，只在真正需要的场景下使用CGo。

贡献者

withesse

更新日志

2026/3/14 13:09

查看所有更新日志

9f6c2-feat: organize wiki content and refresh site setup于 2026/3/14