必须用ffibuilder.set_source()+compile()构建API模式扩展，因其兼顾类型安全、调试能力与生产稳定性；仅用ffi.dlopen()属ABI模式，无法真正嵌入C代码，易因签名/对齐/汇编变更导致崩溃且无上下文错误。
直接用 ffibuilder.set_source() + ffibuilder.compile() 构建 API 模式扩展，而不是靠 ffi.dlopen() 动态加载——这是唯一能兼顾类型安全、调试能力和生产稳定性的做法。
为什么不能只用 ffi.dlopen() 嵌入 C 代码
很多人误以为“嵌入 C 代码”就是写个 .c 文件、编译成 .so、再用 ffi.dlopen() 加载。这其实是 ABI 模式，它根本不支持“嵌入”：C 代码必须提前编译好，Python 运行时只做符号查找。一旦函数签名改了、结构体对齐变了、或用了内联汇编，ffi.cdef() 和实际二进制不匹配，程序大概率在调用时崩溃，且错误信息只显示 Segmentation fault 或 undefined symbol，毫无上下文。
真正嵌入，意味着 C 代码和 Python 绑定逻辑一起管理、一起编译、一起分发。只有 API 模式能做到这点。
ffibuilder.set_source() 必须写对的三件事
API 模式下，set_source() 是把 C 代码注入生成过程的关键入口。常见翻车点：
立即学习“Python免费学习笔记（深入）”；
- 忘记在
source字符串里写#include——比如调用printf却没写#include <stdio.h></stdio.h>，编译会直接失败，报错是unknown type name 'FILE'这类看似无关的信息 - 把 C 函数声明（
cdef）和定义（source）搞混：前者只写签名（int add(int, int);），后者才写实现（int add(int a, int b) { return a + b; }）；漏掉任一，要么运行时报AttributeError: 'Lib' object has no attribute 'add'，要么编译不过 - 路径硬编码：在
source里写#include "mylib.h"，但没传include_dirs=['/path/to/include']给set_source()，构建就卡在找不到头文件
编译产物怎么用、怎么分发
调用 ffibuilder.compile() 后，会生成一个名为 _example.cpython-*.so（Linux/macOS）或 _example.pyd（Windows）的二进制模块。使用时不是 import _example，而是：
from _example import ffi, lib result = lib.add(3, 4)
分发时必须同时包含这个二进制文件和对应的 Python 包装模块（如 example.py），否则用户 import example 会提示 ModuleNotFoundError。不要试图把 .so 打包进 .pyz 或冻结进单文件可执行包——它会被 loader 忽略，导致运行时报 ImportError: dynamic module does not define init function。
字符串、指针、内存生命周期最容易出错的地方
CFFI 不自动管理 C 端分配的内存，而 API 模式下你写的 C 代码完全由你自己控制。几个关键细节：
- Python 字符串传给 C 的
const char*，必须显式转bytes：用b"hello"或s.encode('utf-8')，否则传的是 Python 对象地址，C 读出来是乱码或段错误 - 需要 C 端 malloc 的场景（比如返回动态分配的 buffer），必须配套提供
free()函数，并在 Python 侧用ffi.gc(ptr, lib.free)包裹，否则内存泄漏不可避免 - 结构体里含指针字段（如
char *name），不能直接ffi.new("struct foo *")就完事——那个name字段还是NULL，得额外ffi.new("char[]", b"abc")并赋值，否则访问时崩
这些都不是“写完就能跑”的细节，而是上线后压测才会暴露的隐性故障点。API 模式虽多一步编译，但它把类型检查、符号绑定、内存契约都推到构建期，反而省去了大量线上排障时间。
