WARNING
AI 生成, 有感勿看.
C 和 C++ 采用分离编译模型。当我们执行构建命令时，编译器实际处理的对象并非整个项目，而是翻译单元。一个翻译单元，就是经过预处理之后的单个 .cpp 文件。理解这个预处理步骤，是厘清所有头文件规则的基础。
一、声明是承诺，定义是兑现
C++ 语法上允许声明与实现分离，这并非为了“好看”，而是直接面向编译器的底层机制。
- 声明告诉编译器：“某个符号（函数或变量）存在，它的类型是这样的。请为它预留一个引用占位。”
- 定义则提供了具体的内存布局或机器码。
编译器在编译每个翻译单元时，必须知晓所有符号的声明，但不需要看到定义。这背后是 单一定义规则（ODR） 在约束：在整个程序中，一个变量或非内联函数的定义只能出现一次。因此，我们把声明放在头文件，把定义放在源文件。如果头文件中包含了函数的定义，而该头文件被两个 .cpp 包含，预处理后两个翻译单元就会各产出一份相同的函数机器码。当链接器合并这些目标文件时，会发现重复的符号，进而报错中止构建。
二、分离带来的工程收益
文件分离直接带来了三项确定的好处。
第一，编译时平台适配。通过预处理宏（如 #ifdef _WIN32），头文件可以为不同操作系统声明不同的函数原型，而对应的 .cpp 实现文件则提供各自的平台代码。这本质是条件编译，它让同一套头文件在预处理阶段就拼接出针对当前平台的专属翻译单元。
第二，接口隔离与编译防火墙。头文件暴露了类成员和函数签名，而将具体算法细节隐藏在 .cpp 中。这不仅保护了源代码，更重要的是形成了一道编译防火墙：修改 .cpp 内部的逻辑，只会重新编译这一个文件；而修改头文件，将导致所有包含它的 .cpp 被重新编译。因此，在头文件中用前向声明代替直接包含其他头文件，是大型项目缩减编译时间的核心手段。
第三，延迟实现链接。你完全可以在头文件中声明一个函数，却不提供任何实现。只要在链接阶段，外部静态库或动态库提供了该符号的具体地址，构建就能成功。这是调用系统 API 或第三方 SDK 的基础模式。
三、文件后缀仅是约定
在编译器眼中，.h、.hpp、.c、.cpp 甚至 .txt 毫无区别。预处理器仅将 #include 指令替换为指定文件的完整文本内容。
后缀名仅是约定，编译器不会依据后缀名改变对文件内容的解读方式。为了验证这一点，你可以做一个极端的试验：在 a.h 中写一个非内联函数的完整实现，在 a.cpp 中仅放置该函数的声明，然后在 main.cpp 里 #include "a.cpp"。此时如果你直接调用编译器去编译 a.h 这个文件，例如 g++ -c a.h -o a.o，编译器会毫无障碍地将头文件中的实现编译为目标文件。这足以说明，.h 或 .cpp 无法改变文件的本质——它们只是供预处理器搬运的文本。真正决定编译行为的，是最终输入编译器的翻译单元里拼合出了什么内容，以及这些内容是否符合单一定义规则。只要这份文本中包含了完整的函数实现，编译器就生成代码；若该实现通过头文件被复制到多个翻译单元，链接器依然会报告重定义错误。
此外，为避免预处理器在单个翻译单元内多次展开同一头文件导致重复声明，通常使用 #pragma once 或 #ifndef 宏守卫来防止这种文本层的重复引入。
不过为了讨论方便，我们还是「以 .cpp 写实现， .h 写声明」的规范来继续讨论。
四、#include 的方向问题
编译器的入口永远是 .cpp 文件，而不是头文件。
当你在 main.cpp 中写 #include "tools.h" 时，预处理器将 tools.h 的文本内容原样复制进 main.cpp。此时，翻译单元中就有了 tools.h 里的函数声明。编译器看到这些声明后，生成目标文件，并将这些外部符号标记为“未解析”。
当引入外部库时，我们 #include 对方的头文件，作用完全相同：只是将声明复制进我们的翻译单元。编译器通过这些声明生成调用指令，但暂时搁置函数地址。等到链接阶段，链接器拿着这些未解析的符号名称，去逐个搜索你指定的库文件，一旦匹配，便将库中的具体实现地址填入调用处。
五、模板：编译期的代码生成
模板是编译期的代码生成器。编译器处理模板时，需完成词法解析、类型推导与语义检查，并根据实例化时传入的具体类型，在编译阶段生成对应的特化机器码。
举例来说，当你编写 std::vector<int> 和 std::vector<std::string> 时，编译器在编译期分别为 int 和 std::string 各生成一份独立的 vector 类代码，包含各自类型对应的内存布局和成员函数实现。这两份代码仅在当前翻译单元中可见，并参与该单元的目标文件生成。如果另一个翻译单元也使用了 std::vector<int>，该翻译单元将再次实例化一份相同的代码。链接器最终会合并这些重复的实例化副本。
但因为调用模板时需要知道模板细节才能生成代码，因此模板的实例化要求编译器在调用点看到完整的定义。编译器无法仅凭模板声明生成特定类型的代码，因此模板的实现必须暴露在头文件中，以便每个翻译单元独立完成实例化。
又因为模板实现和声明都写在头文件中会相当乱，为维持头文件结构的清晰，业界将模板的实现移入独立的 .tpp 文件，再在对应的 .h 文件末尾通过 #include 引入该 .tpp。这种拆分方式利用了预处理的文本展开特性，既保证了模板定义的可见性，又使接口声明与实现细节在形式上保持分离。编译时，#include 将模板实现文本拼接到头文件中，编译器随后进行类型检查并生成实例化代码。
总结
理解 C++ 编译模型，归根结底只需记住三句话：
头文件仅装载声明，用于向编译器交付“承诺”；源文件承载定义，用于向链接器交付“实现”；模板是编译期生成器，必须暴露全貌，否则无法实例化。区分预处理文本替换与编译期代码生成，分清编译时依赖与链接时解析，所有关于后缀名、包含规则和 ODR 的困惑都将迎刃而解。
或者说更简单的办法：
.h/.hpp里面写声明，.c/.cpp里面写代码实现，.tpp里面写模板实现。.h/.hpp要#include的是.tpp文件。.tpp和.c/.cpp要#inlucde的是.h/.hpp文件。