头文件依赖多会引发编译慢、ODR冲突、静默行为异常等问题；应采用pimpl模式、非模板接口、最小标准库依赖和前向声明来提升API稳定性与易用性。

为什么头文件依赖多会导致 API 难用

用户只要 #include 你的头文件，就得被迫编译所有间接包含的第三方或内部头文件。一旦某个底层头文件改了 struct 布局、加了默认模板参数、或仅因平台宏变动而重定义类型，调用方就可能静默行为异常，或触发 ODR（One Definition Rule）冲突。更糟的是，编译时间线性增长，CI 构建变慢，跨团队协作时连头文件路径都容易出错。

用 pimpl 模式隔离实现细节

把具体类定义、私有成员、第三方类型全挪进 .cpp 文件里，头文件只留一个不透明指针和公有接口声明。这是控制头文件污染最直接有效的手段。

• std::unique_ptr 是首选：自动管理生命周期，无需手动写析构函数
• 构造函数和析构函数必须在 .cpp 中定义（哪怕空实现），否则编译器无法生成正确销毁逻辑
• 避免在头文件中暴露任何第三方库类型（如 boost::optional、std::filesystem::path），统一转为 std::string 或自定义轻量 wrapper

/* logger.h */
class Logger {
public:
    Logger();
    ~Logger(); // 必须定义在 .cpp 中
    void log(const std::string& msg);
private:
    struct Impl;
    std::unique_ptr pimpl_;
};

用非模板接口降低实例化爆炸风险

模板函数/类虽灵活，但每个不同模板实参都会生成一份符号和代码。用户一传 std::vector 和 std::vector，你就得链接两套实现 —— 还得确保它们 ABI 兼容。对稳定 API 来说，这是不可控变量。

• 对外提供非模板重载（如 save_to_file(const std::string&)），内部再做类型分发
• 若必须支持泛型，用 std::any 或抽象基类 + 工厂，而非暴露模板参数
• 禁止导出模板特化（template class EXPORTED_TEMPLATE;），它绑定编译器和 STL 版本，极难维护

头文件只依赖标准库子集 + 显式前向声明

标准库中只有少数头是“安全”的：、、、。像 、、 虽常用，但内部实现差异大，跨编译器/STL 版本易出问题。

• 能前向声明就不 #include：比如只用 std::shared_ptr，就在头文件里写 class Foo; + #include
• 禁止在头文件中使用 using namespace，尤其不能引入 std 的别名（如 using size_t = std::size_t;）
• 所有跨模块传递的类型必须显式定义或完整声明；不要依赖隐式包含（例如靠 顺带拉进 ）

真正稳定的 C++ API 不是功能最多那个，而是头文件打开后只看到 3 行 #include、5 个函数声明、没有宏定义、也不需要用户配 -I 路径的那个。