头文件依赖多会引发编译慢、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 版本，极难维护;
头文件只依赖标准库子集 + 显式前向声明
标准库中只有少数头是“安全”的：、
立即学习“C++免费学习笔记（深入）”；
- 能前向声明就不
#include：比如只用std::shared_ptr，就在头文件里写class Foo;+#include - 禁止在头文件中使用
using namespace，尤其不能引入std的别名（如using size_t = std::size_t;） - 所有跨模块传递的类型必须显式定义或完整声明；不要依赖隐式包含（例如靠
真正稳定的 C++ API 不是功能最多那个，而是头文件打开后只看到 3 行 #include、5 个函数声明、没有宏定义、也不需要用户配 -I 路径的那个。
