1. C API 设计入门：什么是C API，为什么需要封装

说到C API，很多人第一反应就是“头文件里那些函数声明呗”。嗯，对也不全对。API的全称是Application Programming Interface，说白了就是别人写好的一段代码，你调它来完成某个功能。C语言里的API，通常就是一组函数、数据结构、宏定义的集合。我刚开始做嵌入式开发时，觉得API就是拿来就用的，直到自己开始写库，才发现设计一套好用的API远比想象中难。

为什么要封装？你想想看，直接暴露底层实现细节会带来什么后果？调用者必须知道内部结构，改一个字段就得改所有用到的地方，版本升级更是噩梦。封装，就是把复杂的实现藏起来，只给外界一个干净、稳定的接口。

什么是C API？

C API本质上是一个契约。它告诉你：给我什么参数，我做什么事，返回什么结果。它不关心你内部怎么实现。我个人的理解，好的C API应该像黑盒子：输入、处理、输出，外部无需了解内部。

举个例子，一个简单的队列API：

// queue.h — 对外接口
typedef struct queue queue_t;

queue_t* queue_create(size_t capacity);
void    queue_push(queue_t* q, int value);
int     queue_pop(queue_t* q);
int     queue_empty(queue_t* q);
void    queue_destroy(queue_t* q);

看到没？调用者只知道queue_t是个不透明类型，具体结构体长什么样，里面用了数组还是链表，完全不管。这就是封装的第一步——隐藏实现。

为什么需要封装？—— 我从踩坑中悟出的道理

我曾经参与过一个项目，早期为了图方便，直接把结构体定义扔在头文件里，所有模块都可以直接读写成员。结果后来需求变化，要在结构体里加一个字段，好嘛，所有引用了这个结构体成员的代码都要改，光是编译警告就处理了两天。从那以后，我再也不敢把内部结构暴露出去。

封装的收益可以总结成三点：

对比项	裸露API（不封装）	封装API
依赖隔离	调用者依赖具体实现，改了就得改	调用者只依赖接口，实现自由替换
版本兼容	升级库时可能破坏现有代码	接口不变，二进制兼容可保持
安全性	调用者可能绕过逻辑直接改数据	通过API控制所有访问，可以做校验
可读性	代码散布内部细节，难以理解	接口清晰，行为自文档

封装的基本原则

我自己总结了几条实用的原则，你们在写C API时可以当个参考：

• 最小接口原则：只暴露必须的函数，能藏的全藏。比如内部用的辅助函数，用static声明放在.c里。
• 不透明句柄：用指针指向内部结构，结构体定义对外不可见。就像上面那个queue_t*。
• 错误处理统一：设计统一的错误返回码，比如用int返回值表示成功/失败，或者用errno风格。
• 内存管理清晰：谁分配谁释放，文档里写清楚。我踩过的坑之一就是没约定好，导致内存泄漏排查了三天。

一个完整的封装例子

来看个完整的简单案例，一个整数栈API的封装前后对比。

不封装版本（直接暴露结构体）：

// stack_raw.h
typedef struct {
    int* data;
    int top;
    int capacity;
} raw_stack;

raw_stack* raw_stack_create(int cap);
void raw_stack_push(raw_stack* s, int val);
int raw_stack_pop(raw_stack* s);

调用者可以直接写s->data[s->top++]，绕过push/pop，破坏了栈的LIFO规则。

封装版本：

// stack.h
typedef struct stack stack_t;

stack_t* stack_create(int capacity);
void     stack_push(stack_t* s, int value);
int      stack_pop(stack_t* s);
int      stack_empty(stack_t* s);
void     stack_destroy(stack_t* s);

调者只能用函数操作，内部结构完全隔离。即使以后改成链表实现，接口也不用变。

本章知识体系

下面这张图帮你梳理C API封装的核心概念脉络：

这张图展示了封装的核心三层结构：用户代码只接触API接口，内部实现完全隐藏，不透明句柄和结构体定义都被隔离在实现层。做得好的封装，用户根本不需要关心内部。