c++oding="utf-8" ?>
extern "c" 无法解决 c++ abi 兼容性问题，必须用 opaque pointer + 纯 c 头文件 + 显式生命周期控制实现稳定 c abi 封装。
不能直接用 extern "C" 包裹 C++ 类或模板函数——这只会让编译失败，或导出不稳定的符号。真正能落地的 C ABI 封装必须绕过 C++ 语言特性，用 opaque pointer + 纯 C 头文件 + 显式生命周期控制来实现。
为什么 extern "C" 单独使用不行
它只解决 name mangling，但掩盖不了更深层的 ABI 破坏点：类成员布局、std::string 内存结构、虚函数表偏移、异常传播机制等。即使函数名导出了，调用方传入一个 std::string*，而库内部用的是 libc++ 的 SSO 实现，主程序用的是 libstdc++，运行时就会在析构时 double-free 或越界访问。
常见错误现象：
- 链接成功，运行时崩溃在
std::string::~string()或std::vector::~vector() -
nm -D libmy.so看到符号是my_function，但dlsym(handle, "my_function")返回NULL（实际是符号被意外隐藏或未导出） - C 端传
const char* s = "hello"，C++ 端用std::string(s)构造后立即释放——因为 C 端没管理内存，而 C++ 端误以为要接管所有权
必须用 opaque pointer 模式隔离实现
对外头文件只声明不完整类型，禁止暴露任何 C++ 类型或 STL 容器。所有对象操作都通过函数指针完成，且生命周期完全由 C 函数控制。
实操要点：
- 头文件中写
typedef struct MyHandle MyHandle;，不定义结构体内容 - 构造函数封装为
MyHandle* my_handle_create(void)，内部用new MyClass并返回static_cast<void>(ptr)</void>或直接reinterpret_cast<myhandle>(ptr)</myhandle> - 析构函数必须显式调用：
void my_handle_destroy(MyHandle* h)，内部delete static_cast<myclass>(h)</myclass> - 所有方法调用都带
MyHandle*参数，如int my_handle_process(MyHandle*, const char*, size_t)，内部做类型转换
这样改了 MyClass 成员变量数量、顺序，甚至把 std::vector 换成 std::deque，都不影响 C 端二进制兼容性。
C 头文件里禁止出现任何 C++ 关键字和 STL 类型
头文件必须能被 gcc -x c 直接编译通过。这是验证 ABI 稳定性的最低门槛。
必须遵守：
- 枚举必须指定底层类型：
enum my_error_t : int { MY_OK = 0, MY_ERROR = -1 };，不能用enum class - 字符串统一用
const char*，长度由调用方保证以\0结尾；如需带长度，额外加size_t len参数 - 回调函数用函数指针类型：
typedef void (*my_callback_t)(int code, void* user_data); - 禁止
class、template、std::string、throw、constexpr、auto等任何 C++ 特性
示例片段（合法 C 头文件）：
#ifdef __cplusplus
extern "C" {
#endif
<p>typedef struct MyHandle MyHandle;</p><p>enum my_error_t : int { MY_OK = 0, MY_ERROR = -1 };</p><p>MyHandle<em> my_handle_create(void);
void my_handle_destroy(MyHandle</em> h);
my_error_t my_handle_do_work(MyHandle<em> h, const char</em> input, size_t len, my_callback_t cb, void* user_data);</p><h1>ifdef __cplusplus</h1><p>}</p><h1>endif</h1><p></p>
符号导出必须精确控制，不能依赖默认行为
Linux/macOS 下默认所有全局符号都可能被导出，Windows 下 __declspec(dllexport) 又容易漏写。不加约束会导致内部实现符号泄漏，破坏 ABI 隐私性，也增加未来重构风险。
推荐做法：
- GCC/Clang：在编译时加
-fvisibility=hidden，再对每个导出函数加__attribute__((visibility("default"))) - MSVC：用模块定义文件（.def）显式列出
EXPORTS，或对每个函数加__declspec(dllexport) - 避免用
extern "C" { ... }块包裹整个头文件——它不控制符号可见性，只控制 name mangling - 用
nm -D libmy.so | grep my_验证只有预期符号存在，无多余_Z开头符号
最容易被忽略的一点：C++ 实现文件（.cpp）里所有非导出函数、静态变量、内联辅助函数，必须加 static 或 __attribute__((visibility("hidden")))，否则它们可能被意外链接，造成 ABI 泄漏。
13万字C语言保姆级教程（深入）：立即使用
在学习笔记中，你将探索c语言的核心概念和高级技巧！
