头文件依赖多会引发编译慢、ODR冲突、静默行为异常等问题；应采用pimpl模式、非模板接口、最小标准库依赖和前向声明来提升API稳定性与易用性。
为什么头文件依赖多会导致 API 难用
用户只要 #include 你的头文件，就得被迫编译所有间接包含的第三方或内部头文件。一旦某个底层头文件改了 struct 布局、加了默认模板参数、或仅因平台宏变动而重定义类型，调用方就可能静默行为异常，或触发 ODR（One Definition Rule）冲突。更糟的是，编译时间线性增长，CI 构建变慢，跨团队协作时连头文件路径都容易出错。
用 pimpl 模式隔离实现细节
把具体类定义、私有成员、第三方类型全挪进 .cpp 文件里，头文件只留一个不透明指针和公有接口声明。这是控制头文件污染最直接有效的手段。
-
std::unique_ptr<impl></impl>是首选：自动管理生命周期，无需手动写析构函数 - 构造函数和析构函数必须在 .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<Impl> pimpl_;
};用非模板接口降低实例化爆炸风险
模板函数/类虽灵活，但每个不同模板实参都会生成一份符号和代码。用户一传 std::vector<int></int> 和 std::vector<double></double>，你就得链接两套实现 —— 还得确保它们 ABI 兼容。对稳定 API 来说，这是不可控变量。
- 对外提供非模板重载（如
save_to_file(const std::string&)），内部再做类型分发 - 若必须支持泛型，用
std::any或抽象基类 + 工厂，而非暴露模板参数 - 禁止导出模板特化（
template class EXPORTED_TEMPLATE<int>;</int>），它绑定编译器和 STL 版本，极难维护
头文件只依赖标准库子集 + 显式前向声明
标准库中只有少数头是“安全”的：<memory></memory>、<string></string>、<cstdint></cstdint>、<exception></exception>。像 <vector></vector>、<map></map>、<chrono></chrono> 虽常用，但内部实现差异大，跨编译器/STL 版本易出问题。
立即学习“C++免费学习笔记（深入）”；
- 能前向声明就不
#include：比如只用std::shared_ptr<foo></foo>，就在头文件里写class Foo;+#include <memory></memory> - 禁止在头文件中使用
using namespace，尤其不能引入std的别名（如using size_t = std::size_t;） - 所有跨模块传递的类型必须显式定义或完整声明；不要依赖隐式包含（例如靠
<iostream></iostream>顺带拉进<string></string>）
真正稳定的 C++ API 不是功能最多那个，而是头文件打开后只看到 3 行 #include、5 个函数声明、没有宏定义、也不需要用户配 -I 路径的那个。
