API 设计与不透明类型：把 struct 藏进 .c,只把句柄放进 .h

引言：头文件能藏东西,不只是放声明

上一章我们钉了头文件的三条契约——include guard、ODR、static inline,核心一句话:头文件是跨翻译单元的契约。可契约里该写什么、又该「故意不写」什么,这件事本身就值得单独拆一章。你想过没有:FILE* 你天天用、fopen/fread/fclose 你天天调,可你从来没有写过 fp->buffer 或者 fp->pos——你压根不知道 FILE 这个 struct 里有什么字段。这不是 C 标准库「忘了告诉你」,而是它故意藏起来了:把 struct 的真实定义锁进 libc 的 .c 里,头文件只丢给你一个「指向不完整 struct 的指针」、外加一组操作它的函数。你拿到的是一个句柄——一个摸不到内部、只能交给 API 去摆弄的小东西。

这一招叫 opaque pointer(不透明指针),也叫不透明类型 / opaque type / handle pattern,是 C 里做封装最干净的手段。它的味道很像 C++ 的 pImpl、像 Java 的「你拿到的是接口」、像 Linux 内台下你拿到一个 int fd 就能 read/write 却摸不到 file 描述符内部结构——但 C 这一招是纯靠「前向声明 + 指针」在语言层面原生支持的,没有任何语言层面的新机制。我们这一章就真跑一个最小的 ringbuffer(环形缓冲区),把这套从头到尾走通:头里前向声明、.c 里藏字段、消费者试图偷摸字段被编译器当场拒绝、改走 API 一切平安。然后我顺手把项目里两个现成头拉出来对照——CCMutex.h 用 void* core_lock 把 pthread_mutex_t 藏进 .c(正面教材),CCDynamicArray.h 直接在头里把整个 struct 摊开(反面教材,我们点名、但不改它,它有它当时的取舍)。最后说清这套打法的收益和代价:封装、ABI 稳定是白捡的,但「只能堆分配、栈上放不下」这笔账你得认。

不透明类型是什么:一个你只能握、不能拆的句柄

先说清原理,这个真不复杂。C 允许你写这么一行——

struct Ring;

这叫前向声明(forward declaration),它告诉编译器:「存在一个叫 struct Ring 的类型,但它的字段我现在不告诉你」。一旦编译器接受了这句,你就可以声明指向它的指针(struct Ring* / Ring_t*)、把指针传来传去、存进变量、交给函数——因为所有指针在同一个编译器上大小都一样(比如 x86-64 上都是 8 字节),编译器不需要知道 struct Ring 长什么样,就能处理一个「指向它的指针」。但你不能对这个指针解引用去看字段(r->buf),也不能 sizeof(struct Ring)、不能在栈上或静态区分配一个 struct Ring 变量——因为这些操作都要求编译器「知道它多大、字段怎么排布」,而它只知道「有这么个名字」,字段是空的,这叫不完整类型(incomplete type)。

把这个性质用在 API 设计上,套路就清楚了。头文件(.h)里只放前向声明加一组操作指针的函数:

typedef struct Ring Ring_t;           /* 前向声明:struct Ring 存在,但字段不告诉你 */
Ring_t* ring_create(size_t capacity); /* 构造,返回一个句柄 */
void ring_destroy(Ring_t* r);         /* 析构,把句柄还回去 */
int ring_push(Ring_t* r, int v);      /* 操作:只接受句柄、不暴露字段 */
/* ... */

真实的 struct 定义——int* buf; size_t cap, head, tail, count;——只写在 .c 里。于是消费者 #include 你的头之后,拿到的是一个 Ring_t*,他能 ring_create 拿到它、能 ring_push/ring_pop 用它、能 ring_destroy 还掉它,但他写不出 r->buf——编译器只见过前向声明,r->buf 这种「解引用摸字段」的代码根本编不过。封装,就这么在语言层面完成了,没有任何访问控制关键字。

真跑一个最小 ringbuffer

我们来落地它。一个 ringbuffer(环形缓冲区)是一个固定容量的先进先出队列,头尾两个游标在一段连续数组上循环走——push 写在 tail、pop 读在 head,满了不能 push、空了不能 pop,经典得很。先看头文件,这是我对外发布的全部契约:

/* ringbuffer.h */
#ifndef RINGBUFFER_H
#define RINGBUFFER_H

#include <stddef.h>

/* 前向声明:只告诉世界「有这么个 struct」,字段定义藏在 .c 里。
   消费者拿到的是「指向不完整类型的指针」——一个不透明的句柄。 */
typedef struct Ring Ring_t;

/* 这才是模块对外的全部 API:一组操作「Ring_t*」的函数。 */
Ring_t* ring_create(size_t capacity);
void ring_destroy(Ring_t* r);
int ring_push(Ring_t* r, int value);
int ring_pop(Ring_t* r, int* out);
size_t ring_size(const Ring_t* r);

#endif /* RINGBUFFER_H */

整张头里,没有任何字段。第 9 行 typedef struct Ring Ring_t; 是这一章的灵魂——它把一个「不完整的 struct Ring」起了个短名字 Ring_t,但 struct Ring 的字段在头里一个字都没提。下面五条函数原型是模块的全部对外能力:创建、销毁、推一个进、弹一个出、查当前长度。一个消费者读完这张头,就完全知道「我能对 Ring_t* 做什么」,而完全不知道「Ring_t 里面长什么样」——这正是封装该有的样子。

接下来是 .c,真正的字段藏在这里:

展开代码 (共 65 行)收起代码

/* ringbuffer.c */
#include "ringbuffer.h"

#include <stdlib.h>

/* 真实的 struct 定义,只在这个 .c 里可见。改字段、换布局,外面编译不破。 */
struct Ring {
    int* buf;
    size_t cap;
    size_t head; /* 下一个 pop 的位置 */
    size_t tail; /* 下一个 push 的位置 */
    size_t count;
};

Ring_t* ring_create(size_t capacity) {
    if (capacity == 0) {
        return NULL;
    }
    Ring_t* r = malloc(sizeof(Ring_t));
    if (!r) {
        return NULL;
    }
    r->buf = malloc(sizeof(int) * capacity);
    if (!r->buf) {
        free(r);
        return NULL;
    }
    r->cap = capacity;
    r->head = 0;
    r->tail = 0;
    r->count = 0;
    return r;
}

void ring_destroy(Ring_t* r) {
    if (!r) {
        return;
    }
    free(r->buf);
    free(r);
}

int ring_push(Ring_t* r, int value) {
    if (!r || r->count == r->cap) {
        return 0; /* 满 */
    }
    r->buf[r->tail] = value;
    r->tail = (r->tail + 1) % r->cap;
    r->count++;
    return 1;
}

int ring_pop(Ring_t* r, int* out) {
    if (!r || !out || r->count == 0) {
        return 0; /* 空 */
    }
    *out = r->buf[r->head];
    r->head = (r->head + 1) % r->cap;
    r->count--;
    return 1;
}

size_t ring_size(const Ring_t* r) {
    return r ? r->count : 0;
}

字段全在这个 .c 里——int* buf 是那段连续数组、cap 是容量、head/tail 是读写下标、count 是当前元素数,一个 FIFO 该有的它都有。重点看几处实现纪律:ring_create 里我分两次 malloc(先分配 Ring_t 本体、再分配 buf 那段数组),第二次失败时记得 free(r) 把第一次的也还掉——这种「失败回滚」是写堆分配结构体的基本功,漏了就是经典的内存泄漏;ring_destroy 则反过来、先 free(buf) 再 free(r),顺序不能反(反了你就读到一个已释放的 r->buf、是 use-after-free);ring_push/ring_pop 用 (idx + 1) % cap 让下标在数组里循环走,这就是「环形」的全部秘密。这些字段和细节,头文件里一个字都没提,外面的人看不到。

现在消费者来了,乖乖走 API 的那种:

展开代码 (共 26 行)收起代码

/* main_ok.c:正常走 API,一切平安 */
#include <stdio.h>

#include "ringbuffer.h"

int main(void) {
    Ring_t* r = ring_create(4);
    if (!r) {
        fprintf(stderr, "create failed\n");
        return 1;
    }

    ring_push(r, 10);
    ring_push(r, 20);
    ring_push(r, 30);

    printf("size = %zu\n", ring_size(r));

    int v = 0;
    while (ring_pop(r, &v)) {
        printf("pop %d\n", v);
    }

    ring_destroy(r);
    return 0;
}

main 里全程只握着 Ring_t* r 这个句柄,所有操作都交给 ring_* 函数,gcc 和 clang 双跑都干净编过、跑出来是这个:

text

$ gcc -std=c11 -Wall -Wextra -I. main_ok.c ringbuffer.c -o ok_gcc && ./ok_gcc
size = 3
pop 10
pop 20
pop 30
$ clang -std=c11 -Wall -Wextra -I. main_ok.c ringbuffer.c -o ok_clang && ./ok_clang
size = 3
pop 10
pop 20
pop 30

先进先出,10 20 30 按 push 的顺序原样吐出来,符合 FIFO 的预期。顺手开 ASan+UBSan 验一下没漏没 UB——-fsanitize=address,undefined 跑完干干净净、rc=0、没有任何 leak 报告,说明 ring_destroy 把两块 malloc 都还干净了。

消费者想偷摸字段?编译器当场拒绝

好,现在来了一个不守规矩的消费者。他觉着自己聪明,想绕过 ring_push 直接往第一个槽里塞个 999、还想偷看 head 游标走到哪了,于是写下了 r->buf[0] = 999; 和 r->head。我们看看会怎样:

/* main_illegal.c:试图直接摸 struct 的字段 —— 拿不到,因为 Ring 是不完整类型 */
#include <stdio.h>

#include "ringbuffer.h"

int main(void) {
    Ring_t* r = ring_create(4);
    r->buf[0] = 999; /* 想偷摸写第一个槽 */
    printf("head = %zu\n", r->head);
    ring_destroy(r);
    return 0;
}

text

$ gcc -std=c11 -Wall -Wextra -I. -c main_illegal.c -o illegal_gcc.o
main_illegal.c: In function 'main':
main_illegal.c:8:6: error: invalid use of incomplete typedef 'Ring_t' {aka 'struct Ring'}
    8 |     r->buf[0] = 999; /* 想偷摸写第一个槽 */
      |      ^~
main_illegal.c:9:29: error: invalid use of incomplete typedef 'Ring_t' {aka 'struct Ring'}
    9 |     printf("head = %zu\n", r->head);
      |                             ^~

text

$ clang -std=c11 -Wall -Wextra -I. -c main_illegal.c -o illegal_clang.o
main_illegal.c:8:6: error: incomplete definition of type 'Ring_t' (aka 'struct Ring')
    8 |     r->buf[0] = 999; /* 想偷摸写第一个槽 */
      |     ~^
./ringbuffer.h:9:16: note: forward declaration of 'struct Ring'
    9 | typedef struct Ring Ring_t;
      |                ^
main_illegal.c:9:29: error: incomplete definition of type 'Ring_t' (aka 'struct Ring')
    9 |     printf("head = %zu\n", r->head);
      |                            ~^
./ringbuffer.h:9:16: note: forward declaration of 'struct Ring'
    9 | typedef struct Ring Ring_t;
      |                ^
2 errors generated.

两个编译器说的话几乎一模一样:这个类型是不完整的,我没法对它解引用。gcc 的措辞是 invalid use of incomplete typedef 'Ring_t',clang 更啰嗦、直接甩 incomplete definition of type 'Ring_t' (aka 'struct Ring') 还贴心地指了「它是在 ringbuffer.h:9 那行前向声明的」。注意一个细节——这是编译期就挡下来的,不是运行期、更不是链接期。消费者这个 .c 在自己这个翻译单元里就被编不过,根本到不了链接那一步。原因不玄:编译器在 main_illegal.c 这个翻译单元里只见过 ringbuffer.h,里面除了 typedef struct Ring Ring_t; 这个前向声明之外、struct Ring 的字段一个字都没有;编译器要生成 r->buf 这种「访问 r 指向的对象的第 0 个字段」的代码,就必须知道 struct Ring 的布局(字段在哪、偏移多少),可它只知道「这类型存在」、布局是空的,于是当场罢工。修法只有一个:别摸字段,改走 API——回到 main_ok.c 那种 ring_push(r, ...) 的写法,编过。

ISO C 对这个机制说得很直白:指向不完整类型的指针(pointer to incomplete type)是合法的,你可以声明它、传递它、赋值它;但「解引用」、sizeof、定义该类型的对象,都要求类型完整——见 C11 §6.2.5¶1(「类型在翻译单元的某个点上具有已知的对象表示和操作集合」)和 §6.7.2.1¶8(struct 的字段在 } 之后才算完整)。前向声明 struct Ring; 制造的就是一个在该翻译单元里始终不完整的类型,除非你在同一个翻译单元里把完整定义也写出来——而消费者当然不会写,他只在 .h 里看到前向声明。

代价:只能堆分配,栈上放不下

收益看够了,得说代价——这套打法不是白来的。消费者既然拿不到 struct Ring 的完整定义,他就不能在栈上分配一个 Ring_t、也不能 sizeof(Ring_t),因为这两件事都要求「编译器知道这类型多大」。我们在 main_ok.c 里全程是 Ring_t* r = ring_create(...)——r 这个指针变量在栈上,但它指向的 Ring_t 本体是 ring_create 里 malloc 出来的、在堆上。如果有个愣头青想省这一次 malloc、把 Ring_t 直接放栈上,会发生什么?

/* main_stack.c:想在栈上分配 Ring —— 编译器不知道它多大 */
#include <stdio.h>

#include "ringbuffer.h"

int main(void) {
    Ring_t r; /* 不完整类型,不能实例化 */
    printf("sizeof(Ring_t) = %zu\n", sizeof(Ring_t));
    return 0;
}

text

$ gcc -std=c11 -Wall -Wextra -I. -c main_stack.c -o stack_gcc.o
main_stack.c: In function 'main':
main_stack.c:7:12: error: storage size of 'r' isn't known
    7 |     Ring_t r; /* 不完整类型,不能实例化 */
      |            ^
main_stack.c:8:45: error: invalid application of 'sizeof' to incomplete type 'Ring_t' {aka 'struct Ring'}
    8 |     printf("sizeof(Ring_t) = %zu\n", sizeof(Ring_t));
      |                                             ^~~~~~

text

$ clang -std=c11 -Wall -Wextra -I. -c main_stack.c -o stack_clang.o
main_stack.c:7:12: error: variable has incomplete type 'Ring_t' (aka 'struct Ring')
    7 |     Ring_t r; /* 不完整类型,不能实例化 */
      |            ^
./ringbuffer.h:9:16: note: forward declaration of 'struct Ring'
    9 | typedef struct Ring Ring_t;
      |                ^
main_stack.c:8:38: error: invalid application of 'sizeof' to an incomplete type 'Ring_t' (aka 'struct Ring')
    8 |     printf("sizeof(Ring_t) = %zu\n", sizeof(Ring_t));
                                      ^

两处全炸:Ring_t r; 这行 gcc 说 storage size of 'r' isn't known、clang 说 variable has incomplete type,编译器不知道这变量多大、没法在栈帧上给它切一块;sizeof(Ring_t) 那行更直白,invalid application of 'sizeof' to incomplete type——sizeof 是编译期求值、需要完整类型,不完整类型压根求不出。这就是不透明类型的根本代价:对象只能由模块内部(那个看得到完整定义的 .c)分配,外部只能拿到指针、用完还得交回去。落到代码上就是「必然堆分配 + 配对一个 destroy/free」——你在享受封装的同时,认下了这一次 malloc/free 的开销和「忘了 destroy 就泄漏」的纪律负担。我们前面 ring_create 那两次 malloc、ring_destroy 那两次 free、ASan 干干净净的退出,就是这套代价的具象。

收益二:ABI 稳定,改 struct 内部不破消费者

代价说完了,回报里最值钱的一笔还没讲——ABI 稳定。这个性质是上一章 ODR 那条线自然延伸出来的:消费者那个 main_ok.o,只用了「Ring_t* 这个指针类型」和「ring_create/ring_push/... 这些函数符号」,完全没有把 struct Ring 的字段布局编进自己的目标文件(因为他根本不知道布局)。于是,只要头文件里对外承诺的东西不变——Ring_t* 这个指针类型、那几条函数原型——我在 .c 里随便改 struct 的字段,消费者那个已经编好的 .o 不用重编、照样能链上新版的 ringbuffer。

这话空说没劲,我们真跑一遍。我把 ringbuffer.c 里 struct Ring 加一个统计字段 size_t push_total;(记录历史上一共 push 过多少次),对应的 ring_create 初始化它、ring_push 维护它——字段变了、布局变了,但头文件 ringbuffer.h 一个字没动。然后把消费者 main_ok.c 编成 main_ok.o(只用旧头)、把新 ringbuffer.c 编成 ringbuffer2.o、把这两个 .o 链起来跑:

text

$ gcc -std=c11 -Wall -Wextra -I. -c main_ok.c -o main_ok.o       # 消费者:用旧头编,不知道新字段
$ gcc -std=c11 -Wall -Wextra -I. -c ringbuffer2.c -o ringbuffer2.o # 实现侧:struct 多了一个字段
$ gcc main_ok.o ringbuffer2.o -o ok_abi
$ ./ok_abi
size = 3
pop 10
pop 20
pop 30

消费者那个 main_ok.o 是对着没有 push_total 字段的旧头编出来的,链上加了字段的 ringbuffer2.o,跑得跟之前一模一样、size = 3 / pop 10 20 30。如果换成上一章那种「struct 字段全摊在 .h」的写法,这一改就得所有 #include 它的 .c 全部重编——因为字段布局被编进了每个翻译单元,布局一变、sizeof 一变、r->head 这种访问的字段偏移全变了,旧的 .o 跟新布局对不上、行为就错乱了。这就是 opaque pointer 在「库 + 大量消费者」场景下最值钱的性质:你换了内部实现、加了字段、调了字段顺序,消费者不用重编、ABI 不破。这也是为什么 C 标准库的 FILE*、POSIX 的 DIR*、Linux 内核里大量 struct 都走这一招——它们要在一个 .so/系统里活几十年,内部不知道改了多少版,但二进制层面消费者的老程序还能跑。

项目里两个现成头:正面教材与反面教材

讲完原理,我们把镜头拉回项目本身,看两个真实在用的头——它们正好一个是正面教材、一个是反面教材,对照起来读最有味道。

先看正面教材 CCMutex.h(只摘关键几行,原样引用、未按本教程风格重排):

text

typedef struct __CCMutex
{
    void*           core_lock;	/* pthread_mutex_t* */
    CCMutexError    e;
}CCMutex;

这里它没有用我们这一章的纯前向声明(它把 __CCMutex 整个 struct 摊在了头里),但它对最敏感的那个字段 core_lock 用了一招异曲同工的手法——void*。注释写着 /* pthread_mutex_t* */,说明它在 Linux/POSIX 分支里实际存的是 pthread_mutex_t*,但它故意不在头里 #include <pthread.h>,而是用 void* 把这个平台相关的类型藏起来。收益是双重的:其一,头文件保持轻量,消费者 #include "CCMutex.h" 不会被强行拉进整个 <pthread.h>(那个头相当大、还会传染到所有间接包含它的翻译单元,拖慢编译);其二,Windows 分支(#ifdef CCSTD_USE_WINDOWS)里 core_lock 指向的是 RTL_CRITICAL_SECTION、Linux 分支里指向的是 pthread_mutex_t,两边共用同一张头、同一套 API,平台差异全被 void* 这个「不知道指向啥的指针」吃掉了。这是 void* 型泛化 + 不暴露细节的典型用法,和 opaque pointer 师出同门——「我给你一个指针、但我不告诉你它指向什么、你只能交给我自己的 API 处理」。

再看反面教材 CCDynamicArray.h(同样只摘关键几行,原样引用、未按本教程风格重排):

text

typedef struct __CCDynamicArray
{
    CCAny_t     core_data;
    CCSize_t    core_size;
    CCSize_t    elem_size;
}CCDynamicArray;

这张头把整个 struct 的三个字段全摊在了 .h 里——core_data、core_size、elem_size,消费者一眼就能看到、一写就能摸到(arr->core_data、arr->elem_size 这种代码在外面随便写)。这种写法的代价就是我们前面分析的那条:任何对字段的增删、对字段顺序的调整、对字段类型的换型,都会让所有 #include 它的 .c 必须全部重编;更糟的是,消费者一旦开始依赖 arr->core_data 这种直接字段访问,你以后想改 CCDynamicArray 的内部实现就寸步难行——一动就破一堆下游代码。我们这里只点名、不改它——这个项目是历史代码,它当时这么写有自己的取舍(可能想要栈上直接分配 CCDynamicArray arr;、不想多一次 malloc,这正是 opaque 类型放弃掉的那个能力),而且它现在已经在跑、改它要动下游。把它当一个活生生的「为什么 opaque 更稳」的反例记着,以后写新模块、设计新 API 时,默认就该走前向声明那套,把字段锁进 .c。

小结

把 struct 藏进 .c、只把一个前向声明的指针句柄放进 .h,是 C 在语言层面原生支持的封装手段。头里一行 typedef struct Ring Ring_t; 制造一个不完整类型,消费者拿到 Ring_t* 之后能传、能存、能交给 API,但写不出 r->field、不能 sizeof、不能栈上分配——我们亲手让 gcc 和 clang 当场甩出 invalid use of incomplete type / incomplete definition of type,把这条边界钉死在编译期。代价是只能堆分配(ring_create 里那两次 malloc、ring_destroy 里两次 free,外加「忘了 destroy 就泄漏」的纪律),换来的是封装 + ABI 稳定这两笔大账:消费者那个 .o 只用了指针类型和函数符号、没编进任何字段布局,所以我在 .c 里给 struct 加字段、换实现,消费者不用重编、照样链上新版。项目里 CCMutex.h 用 void* core_lock 把 pthread_mutex_t 藏起来、走的是同一招的近亲变体,CCDynamicArray.h 把字段全摊在 .h 是反面教材——新写模块、默认走 opaque。

带着这套认识,下一章我们继续往工程化深处走,看更多「头文件该写什么、不该写什么」的实战——opaque pointer 只是 API 设计这盘棋的第一步。

参考资源

ISO C11:§6.2.5¶1(类型的「完整性」定义)、§6.7.2.1¶8(struct 类型在 } 之后才完整)、§6.5.2.5(复合字面量与不完整类型的使用限制)。前向声明与不完整类型的官方定义全在这里。
Expert C Programming(Peter van der Linden):第 7 章讲「为什么 C 库爱用不透明指针」,顺带吐槽过「把 struct 摊在头里」的代价。
21st Century C(Ben Klemens):第 5 章「在 C 里做封装」,把 opaque pointer 当作 C 的「私有成员」来讲,例子是 FILE*。
POSIX.1:DIR*(opendir/readdir/closedir)和 FILE*(fopen/fread/fclose)都是标准库里走 opaque pointer 的活样本——你天天用、却不知道它们 struct 里有什么字段,这本身就是这一招成功的证明。
本项目对照:projects/clib-utilities/SystemRelated/Includes/CCMutex.h(void* core_lock 藏 pthread_mutex_t,正面)、projects/clib-utilities/BasicDataStructure/Includes/CCDynamicArray.h(字段摊在 .h,反面)。

API 设计与不透明类型：把 struct 藏进 .c,只把句柄放进 .h ​

引言：头文件能藏东西,不只是放声明 ​

不透明类型是什么:一个你只能握、不能拆的句柄 ​

真跑一个最小 ringbuffer ​

消费者想偷摸字段?编译器当场拒绝 ​

代价:只能堆分配,栈上放不下 ​

收益二:ABI 稳定,改 struct 内部不破消费者 ​

项目里两个现成头:正面教材与反面教材 ​

小结 ​

参考资源 ​

API 设计与不透明类型：把 struct 藏进 .c,只把句柄放进 .h

引言：头文件能藏东西,不只是放声明

不透明类型是什么:一个你只能握、不能拆的句柄

真跑一个最小 ringbuffer

消费者想偷摸字段?编译器当场拒绝

代价:只能堆分配,栈上放不下

收益二:ABI 稳定,改 struct 内部不破消费者

项目里两个现成头:正面教材与反面教材

小结

参考资源